More doc

Author: 4ment

.github/workflows/publish_branch.yml

@@ -0,0 +1,34 @@
+name: Publish the documentation on a branch
+
+on:
+  push:
+    branches:
+      - improve-documentation
+
+jobs:
+  publish:
+    name: Publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the branch
+        uses: actions/checkout@v2.3.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.9
+      - name: Build the documentation with Sphinx
+        run: |
+          pip install -r docs/requirements.txt
+          sphinx-build -b html docs docs/build/html
+
+      - name: Publish the documentation
+        uses: JamesIves/github-pages-deploy-action@3.6.2
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: docs/build/html
+          target-folder: improve-documentation
+          CLEAN: false

README.md

@@ -9,11 +9,14 @@
 
 torchtree is a program designed for developing and inferring phylogenetic models. Implemented in Python, it leverages [PyTorch] for automatic differentiation. The suite of inference algorithms encompasses variational inference, Hamiltonian Monte Carlo, maximum *a posteriori*, and Markov chain Monte Carlo.
 
+For a comprehensive assessment of torchtree's performance and use cases, please see our evaluation repository, [torchtree-experiments](https://github.com/4ment/torchtree-experiments), where torchtree was rigorously tested on various datasets and benchmarked for accuracy and speed.
+
+
 - [Getting Started](#getting-started)
   - [Dependencies](#dependencies)
   - [Installation](#installation)
 - [Quick start](#quick-start)
-- [Documentatoin](#documentation)
+- [Documentation](#documentation)
 - [Plug-ins](#torchtree-plug-in)
 
 ## Getting Started
@@ -84,6 +87,23 @@ torchtree can be easily extended without modifying the code base thanks its modu
 
 A GitHub [template](https://github.com/4ment/torchtree-plugin-template) is available to assist in the development of a plug-in, and it is highly recommended to use it. This template provides a structured starting point, ensuring consistency and compatibility with `torchtree` while streamlining the development process.
 
+## How to cite
+
+If you use torchtree, please consider citing:
+
+```
+
+@misc{fourment2024torchtree,
+      title={torchtree: flexible phylogenetic model development and inference using {PyTorch}}, 
+      author={Mathieu Fourment and Matthew Macaulay and Christiaan J Swanepoel and Xiang Ji and Marc A Suchard and Frederick A Matsen IV},
+      year={2024},
+      eprint={2406.18044},
+      archivePrefix={arXiv},
+      primaryClass={q-bio.PE},
+      url={https://arxiv.org/abs/2406.18044}
+}
+```
+
 ## License
 
 Distributed under the GPLv3 License. See [LICENSE](LICENSE) for more information.

docs/advanced/benchmark.rst

@@ -0,0 +1,71 @@
+Benchmark
+=========
+
+The `torchtree` software was evaluated alongside other phylogenetic tools in a published `benchmark study <https://github.com/4ment/gradient-benchmark>`_ [#Fourment2022]_.
+
+This benchmark assesses the memory usage and speed of various gradient implementations for phylogenetic models, including tree likelihood and coalescent models.
+The study's aim was to compare the efficiency of automatic differentiation (AD) and analytic gradient methods.
+The gradient of the tree likelihood can be computed by `BITO <https://github.com/phylovi/bito>`_ or `physher <https://github.com/4ment/physher>`_ [#Fourment2014]_, efficient C++ and C libraries that analytically calculate the gradient.
+`torchtree` integrates with these libraries through the `torchtree-bito <https://github.com/4ment/torchtree-bito>`_ and `torchtree-physher <https://github.com/4ment/torchtree-physher>`_ plug-ins.
+
+.. list-table:: Programs compared in the benchmark
+   :header-rows: 1
+
+   * - Program
+     - Language
+     - Framework
+     - Gradient
+     - Libraries
+   * - `physher <https://github.com/4ment/physher>`_
+     - C
+     -
+     - analytic
+     -
+   * - `phylostan <https://github.com/4ment/phylostan>`_ [#Fourment2019]_
+     - Stan
+     - Stan
+     - AD
+     -
+   * - `phylojax <https://github.com/4ment/phylojax>`_
+     - python
+     - JAX
+     - AD
+     -
+   * - `torchtree <https://github.com/4ment/torchtree>`_
+     - python
+     - PyTorch
+     - AD
+     - BITO and physher
+   * - `treeflow <https://github.com/christiaanjs/treeflow>`_
+     - python
+     - TensorFlow
+     - AD
+     -
+
+In this study, we compared six gradient implementations of the phylogenetic likelihood functions, in isolation and also as part of a variational inference procedure.
+The data consisted of a collection of influenza A datasets ranging from 20 to 2000 sequences sampled from 2011 to 2013.
+
+This macrobenchmark simulates the core steps of a real phylogenetic inference algorithm but simplifies the model to make it easier to implement across different frameworks.
+In this setup, we are estimating parameters of time tree under a strict clock with a constant-size coalescent model.
+Each implementation relies on automatic differentiation variational inference (ADVI) to maximize the evidence lower bound (ELBO) over 5,000 iterations.
+We specify an exponential prior (mean = 0.001) on the substitution rate and the Jeffrey's prior for the unknown population size.
+
+.. figure:: images/benchmark-macro-time.png
+   :align: center
+   :alt: Speed of implementations for 5,000 iterations of variational time-tree inference with a strict clock
+   
+   Speed of implementations for 5,000 iterations of variational time-tree inference with a strict clock.
+
+As shown in the next figure, the relative performance of AD depends on the task.
+
+.. figure:: images/benchmark-micro-time.png
+   :align: center
+   :alt: Speed of implementations for the gradient of various tasks needed for inference
+
+   Speed of implementations for the gradient of various tasks needed for inference.
+
+.. [#Fourment2022] Fourment M, Swanepoel CJ, Galloway JG, Ji X, Gangavarapu K, Suchard MA, Matsen IV FA. Automatic differentiation is no panacea for phylogenetic gradient computation. *Genome Biology and Evolution*, 2023. doi:`10.1093/gbe/evad099 <https://doi.org/10.1093/gbe/evad099>`_ `arXiv:2211.02168 <https://arxiv.org/abs/2211.02168>`_
+
+.. [#Fourment2014] Fourment M and Holmes EC. Novel non-parametric models to estimate evolutionary rates and divergence times from heterochronous sequence data. *BMC Evolutionary Biology*, 2014. doi:`10.1186/s12862-014-0163-6 <https://doi.org/10.1186/s12862-014-0163-6>`_
+
+.. [#Fourment2019] Fourment M and Darling AE. Evaluating probabilistic programming and fast variational Bayesian inference in phylogenetics. *PeerJ*, 2019. doi:`10.7717/peerj.8272 <https://doi.org/10.7717/peerj.8272>`_

docs/advanced/images/benchmark-macro-time.png

@@ -0,0 +1,63 @@
+Features
+========
+
+Phylogenetic models
+-------------------
+
+**Tree model:**
+
+- unrooted tree with branches lengths representing expected number of substitutions.
+- Time (rooted) tree with branch lengths representing units of time.
+
+**Substitution model:**
+
+- Nucleotide models: JC69, HKY, GTR, SRD06. Any model nested within the GTR model using :py:class:`~torchtree.evolution.substitution_model.general.GeneralSymmetricSubstitutionModel`.
+- Amino acid models: LG and WAG.
+- Codon model: Muse and Gaut (MG94).
+- Any discrete trait model (e.g. phylogeography model).
+
+**Rate heterogeneity across site:** Constant, proportion of invariant sites, discretized Weibull distribution.
+
+**Molecular clock:** strict and variable (i.e. one rate per branch).
+
+Phylogenetic priors
+-------------------
+
+
+**Unrooted tree branch lengths:**
+
+- Exponential distribution (any appropriate distribution).
+- Compound gamma-Dirichlet prior.
+
+**Time tree:**
+
+- Coalescent:
+
+  - Constant and exponential growth population size.
+  - Piecewise functions: skyride, skygrid (piecewise-constant on a grid), and skyglide (piecewise-linear on a grid).
+
+- Birth-death: constant, exponential, and BDSKY.
+
+**Molecular clock:**
+
+- Strict: CTMC reference prior.
+- Variable: uncorrelated and correlated.
+
+
+Inference algorithms
+--------------------
+
+**Variational Inference:**
+
+- Automatic Differentiation Variational Inference (ADVI).
+
+**Markov chain Monte Carlo (MCMC):**
+
+- Vanilla MCMC.
+- Hamiltonian Monte Carlo (HMC).
+
+**Optimization:**
+
+- Maximum *a posteriori* (MAP).
+- Maximum likelihood.
+

docs/advanced/images/benchmark-micro-time.png

@@ -43,13 +43,34 @@ torchtree can be easily extended without modifying the code base thanks its modu
 .. _bito: https://github.com/phylovi/bito
 
 
+How to cite
+-----------
+
+.. tabs::
+
+   .. tab:: Cite
+
+      Mathieu Fourment, Matthew Macaulay, Christiaan J Swanepoel, Xiang Ji, Marc A Suchard and Frederick A Matsen IV. *torchtree: flexible phylogenetic model development and inference using PyTorch*, 2024 `arXiv:2406.18044 <https://arxiv.org/abs/2406.18044>`_
+
+   .. code-tab:: bibtex
+
+      @misc{fourment2024torchtree,
+            title={torchtree: flexible phylogenetic model development and inference using {PyTorch}}, 
+            author={Mathieu Fourment and Matthew Macaulay and Christiaan J Swanepoel and Xiang Ji and Marc A Suchard and Frederick A Matsen IV},
+            year={2024},
+            eprint={2406.18044},
+            archivePrefix={arXiv},
+            primaryClass={q-bio.PE},
+            url={https://arxiv.org/abs/2406.18044}
+      }
 
 .. toctree::
    :maxdepth: 1
    :caption: Getting Started
 
    getting_started/install.rst
    getting_started/quick_start.rst
+   getting_started/features.rst
    getting_started/json_reference.rst
 
 
@@ -59,6 +80,7 @@ torchtree can be easily extended without modifying the code base thanks its modu
 
    advanced/concepts.rst
    advanced/tree_likelihood.rst
+   advanced/benchmark.rst
 
 .. toctree::
    :hidden: