diff --git a/.gitignore b/.gitignore index c98bf80..7919b72 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ tests/custom_model docs/_build tags .coverage* +dist/ diff --git a/README.md b/README.md index 46e777d..b996b33 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ # BIRDMAn [![GitHub Actions CI](https://github.com/biocore/birdman/workflows/BIRDMAn%20CI/badge.svg)](https://github.com/biocore/BIRDMAn/actions) -[![Documentation Status](https://readthedocs.org/projects/birdman/badge/?version=stable)](https://birdman.readthedocs.io/en/stable/?badge=stable) +[![Documentation Status](https://readthedocs.org/projects/birdman/badge/?version=latest)](https://birdman.readthedocs.io/en/latest/?badge=latest) [![PyPI](https://img.shields.io/pypi/v/birdman.svg)](https://pypi.org/project/birdman) [![DOI](https://zenodo.org/badge/312046610.svg)](https://zenodo.org/badge/latestdoi/312046610) **B**ayesian **I**nferential **R**egression for **D**ifferential **M**icrobiome **An**alysis (**BIRDMAn**) is a framework for performing differential abundance analysis through Bayesian inference. -See the [documentation](https://birdman.readthedocs.io/en/stable/?badge=stable) for details on usage. +See the [documentation](https://birdman.readthedocs.io/en/latest/?badge=latest) for details on usage. For an example of running BIRDMAn - see this [Google Colab notebook](https://colab.research.google.com/drive/1zT4eIgiz0Jl5TVmttE3gwWnrhNlPeYDc?usp=sharing). diff --git a/docs/custom_model.rst b/docs/custom_model.rst index 03bef66..d0092c6 100644 --- a/docs/custom_model.rst +++ b/docs/custom_model.rst @@ -315,10 +315,6 @@ We pass all these arguments into the ``specify_model`` method of the ``Model`` o Finally, we compile and fit the model. -.. note:: - - Fitting this model took approximately 6 minutes on my laptop. - .. code-block:: python nb_lme.compile_model() diff --git a/docs/default_model_example.rst b/docs/default_model_example.rst index 0563fa0..c7cffa0 100644 --- a/docs/default_model_example.rst +++ b/docs/default_model_example.rst @@ -20,11 +20,10 @@ Next, we want to import the data into Python so we can run BIRDMAn. import biom import pandas as pd - - from birdman import NegativeBinomial + import glob fpath = glob.glob("templates/*.txt")[0] - table = biom.load_table("BIOM/44773/reference-hit.biom") + table = biom.load_table("BIOM/44773/otu_table.biom") metadata = pd.read_csv( fpath, sep="\t", @@ -57,15 +56,10 @@ For this example we're going to use a simple formula that only takes ``diet`` in We then have to compile and fit our model. This is very straightforward in BIRDMAn. -.. note:: - - Fitting this model took approximately 25 minutes on my laptop. - - .. code-block:: python nb.compile_model() - nb.fit_model() + nb.fit_model(method="vi", num_draws=500) Now we have our parameter estimates which we can use in downstream analyses. Many of BIRDMAn's included analysis & visualization functions take an ``arviz.InferenceData`` object. We provide a simple method to convert your BIRDMAn fit into this data structure. Note that the included ``NegativeBinomial`` model performs ALR regression, meaning that the one of the features (the first) is used as a reference. As a result, the resulting inference will have 1 fewer microbe than were in the original table. We can "add the other microbe back" by converting to CLR coordinates. We provide an easy function to do this in the ``transform`` module. diff --git a/docs/index.rst b/docs/index.rst index efec3ee..5075bb0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,6 +34,7 @@ If you are planning on contributing to BIRDMAn you must also install the followi :maxdepth: 2 :caption: User Guide + installation default_model_example custom_model diagnosing_model diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..f2c597c --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,26 @@ +Installing cmdstanpy +==================== + +BIRDMAn uses the popular ``cmdstanpy`` interface for Bayesian inference. ``cmdstanpy`` is simply a lightweight Python wrapper around the ``cmdstan`` C++ toolchain. + +Depending on how you install ``cmdstanpy``, there may be some additional steps you need to take. We recommend installing via conda/mamba if possible because this will automatically install ``cmdstan`` to your system. + +.. code-block:: bash + + mamba install -c conda-forge cmdstanpy + +If you are installing via pip, you need to install ``cmdstan`` manually. This is because pip cannot install the C++ components on its own. + +First, install ``cmdstanpy`` as follows: + +.. code-block:: bash + + pip install cmdstanpy + +Then, from your terminal you can run the ``install_cmdstan`` script to install the C++ toolchain. + +.. code-block:: bash + + install_cmdstan + +For more information on installing ``cmdstanpy``, please see the `documentation `_. diff --git a/docs/parallelization.rst b/docs/parallelization.rst index c61c803..a165f3c 100644 --- a/docs/parallelization.rst +++ b/docs/parallelization.rst @@ -273,6 +273,6 @@ With our Python script, we can now write a simple script that tells our cluster --num-warmup 1000 \ --beta-prior 2.0 \ --inv-disp-sd 0.5 \ - --re-prior 2.0 \ + --re-prior 2.0 If you run this script your scheduler should start up 20 jobs, each one running a different chunk of features!