Merge pull request #99 from biocore/docs

Update docs

.gitignore

@@ -19,3 +19,4 @@ tests/custom_model
 docs/_build
 tags
 .coverage*
+dist/

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).
 

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()

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.
 

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

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 <https://mc-stan.org/cmdstanpy/installation.html>`_.

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!