Updated gh-pages html pages from dockerfile-fix branch. (#383)

matsen · Jul 17, 2024 · 90fc310 · 90fc310
1 parent 648692f
commit 90fc310
Show file tree

Hide file tree

Showing 112 changed files with 26,363 additions and 2,064 deletions.
diff --git a/_images/math/35aa292c643aceacdb42eb4eff352a2f5c58a710.png b/_images/math/35aa292c643aceacdb42eb4eff352a2f5c58a710.png
diff --git a/_images/math/3d6a321e68755883e7845e4afeacca44889b9e92.png b/_images/math/3d6a321e68755883e7845e4afeacca44889b9e92.png
diff --git a/_images/math/3eca8557203e86160952e1c0f735f7417f3285b1.png b/_images/math/3eca8557203e86160952e1c0f735f7417f3285b1.png
diff --git a/_images/math/40cdb0e5fc0c7cf6e3d3248c29f7de379c0f6abb.png b/_images/math/40cdb0e5fc0c7cf6e3d3248c29f7de379c0f6abb.png
diff --git a/_images/math/4cc22f2b11bccf0d92bf189ecadf822f7f71ee66.png b/_images/math/4cc22f2b11bccf0d92bf189ecadf822f7f71ee66.png
diff --git a/_images/math/630e3a780577ea7921e81ee2ac5237dd1802ec8d.png b/_images/math/630e3a780577ea7921e81ee2ac5237dd1802ec8d.png
diff --git a/_images/math/6859317dd1b439cef34131bcd4bafee8393444e0.png b/_images/math/6859317dd1b439cef34131bcd4bafee8393444e0.png
diff --git a/_images/math/800e5f6a693d4935314b071161bee0f4f31153e8.png b/_images/math/800e5f6a693d4935314b071161bee0f4f31153e8.png
diff --git a/_images/math/a6fb61a30ff1550011bab9c175d31e32b9508202.png b/_images/math/a6fb61a30ff1550011bab9c175d31e32b9508202.png
diff --git a/_images/math/b8c3200c42e8bebe1b12dea779a9aa01abbc949d.png b/_images/math/b8c3200c42e8bebe1b12dea779a9aa01abbc949d.png
diff --git a/_images/math/ba3d12b8e89f22443899d5f897ee4e9637b664d0.png b/_images/math/ba3d12b8e89f22443899d5f897ee4e9637b664d0.png
diff --git a/_images/math/c9bf86d3757c5b26237be228c2c5d84138927661.png b/_images/math/c9bf86d3757c5b26237be228c2c5d84138927661.png
diff --git a/_images/math/dd95c55069c86910ffbe2f9833321d0034fd8036.png b/_images/math/dd95c55069c86910ffbe2f9833321d0034fd8036.png
diff --git a/_images/math/e0b5f1d1ff7f6fd964a048b37a4370d48ea3b9e6.png b/_images/math/e0b5f1d1ff7f6fd964a048b37a4370d48ea3b9e6.png
diff --git a/_images/math/e9203da50e1059455123460d4e716c9c7f440cc3.png b/_images/math/e9203da50e1059455123460d4e716c9c7f440cc3.png
diff --git a/_images/math/f1b8943f45bdd07ff249cf33e6b1d9129e7749b5.png b/_images/math/f1b8943f45bdd07ff249cf33e6b1d9129e7749b5.png
diff --git a/_images/math/f622ac6ea9f75f9e7524fb75d1a699024215a9e5.png b/_images/math/f622ac6ea9f75f9e7524fb75d1a699024215a9e5.png
diff --git a/_images/math/fc68b5ce50859331bdff9b667ab4509b0152dc09.png b/_images/math/fc68b5ce50859331bdff9b667ab4509b0152dc09.png
diff --git a/_sources/changelog.rst.txt b/_sources/changelog.rst.txt
@@ -0,0 +1,6 @@
+:tocdepth: 1
+
+Changelog
+=========
+
+.. include:: ../CHANGELOG
diff --git a/_sources/compiling.rst.txt b/_sources/compiling.rst.txt
@@ -0,0 +1,83 @@
+:tocdepth: 1
+
+Compiling ``pplacer`` from source
+=================================
+
+.. important::
+
+    We provide binaries on the `main pplacer site`_ and encourage their use.
+    However, for those who want to be on the bleeding edge of development, here are
+    instructions and scripts for setting up a compilation environment.
+
+Compiling ``pplacer`` requires a number of libraries and tools to be installed:
+
+* make
+* OPAM (:ref:`see below <OPAM>`)
+* `OCaml 3.12.1 or 4.01.0 <http://www.ocaml.org>`_ (installed via your package manager, compiling from source, or :ref:`OPAM`)
+* patch
+* m4
+* gawk
+* `GNU Scientific Library (GSL)`_ (on Linux, the static library ``libgsl.a`` is required)
+* `libsqlite3 <http://www.sqlite.org>`_  (on Linux, the static library ``libsqlite3.a`` is required)
+* zlib (on Linux, the static library ``libz.a`` is required)
+
+On Debian/Ubuntu 12.04, everything but OPAM can be installed with:
+
+.. code-block:: bash
+
+    apt-get install -y \
+      camlp4-extra \
+      gawk \
+      libgsl0-dev \
+      libsqlite3-dev \
+      libz-dev \
+      m4 \
+      make \
+      ocaml \
+      patch
+
+.. _OPAM:
+
+OPAM
+^^^^
+
+``pplacer`` uses the `OPAM package manager`_ for installing OCaml dependencies.
+OPAM can also manage different versions of the OCaml compiler - ``pplacer`` is tested against version 3.12.1.
+
+See the the `official instructions
+<http://opam.ocaml.org/doc/Install.html>`_ for installation details.
+
+Once OPAM is installed, it needs to be configured:
+
+.. code-block:: bash
+
+    # Install version 3.12.1 of the OCaml compiler version if it's not active
+    command -v ocamlc && ( ocamlc -version | grep -q 3.12.1 ) || opam switch install 3.12.1
+
+    opam init
+    opam repo add pplacer-deps http://matsen.github.io/pplacer-opam-repository
+    opam update pplacer-deps
+    eval `opam config env`
+
+Building ``pplacer``
+^^^^^^^^^^^^^^^^^^^^
+
+Once the dependencies above are installed, navigate to the checkout of
+``pplacer``, and use OPAM to install the OCaml modules used by ``pplacer``:
+
+.. code-block:: bash
+
+    cd /path/to/pplacer
+    # Install required OCaml packages
+    cat opam-requirements.txt | xargs opam install -y
+
+Finally, build ``pplacer``, ``guppy`` and ``rppr`` with::
+
+    make
+
+Now the binaries should be in the ``bin/`` directory. Put them in your
+path and you are ready to go!
+
+.. _GNU Scientific Library (GSL): http://www.gnu.org/s/gsl/
+.. _main pplacer site: http://matsen.fhcrc.org/pplacer/
+.. _OPAM package manager: http://opam.ocaml.org
diff --git a/_sources/compiling.txt b/_sources/compiling.txt
@@ -55,7 +55,7 @@ Once OPAM is installed, it needs to be configured:
     command -v ocamlc && ( ocamlc -version | grep -q 3.12.1 ) || opam switch install 3.12.1
 
     opam init
-    opam repo add pplacer-deps http://matsen.github.com/pplacer-opam-repository
+    opam repo add pplacer-deps http://matsen.github.io/pplacer-opam-repository
     opam update pplacer-deps
     eval `opam config env`
 

diff --git a/_sources/faq.rst.txt b/_sources/faq.rst.txt
@@ -0,0 +1,52 @@
+.. _faq:
+
+FAQ
+===
+
+How can I cite pplacer?
+-----------------------
+Right now there is only one paper to cite::
+
+  @article{matsen2010pplacer,
+    title={pplacer: linear time maximum-likelihood and Bayesian phylogenetic placement of sequences onto a fixed reference tree},
+    author={Matsen, F.A. and Kodner, R.B. and Armbrust, E.},
+    journal={BMC Bioinformatics},
+    volume={11},
+    number={1},
+    pages={538},
+    year={2010},
+    publisher={BioMed Central Ltd}
+  }
+
+At some point we will write something up for the new pplacer, guppy, taxtastic, etc., but if you use a method implemented in guppy (such as edge PCA) we hope you will cite the paper describing that method.
+
+
+Why is pplacer taking up so much memory?
+----------------------------------------
+Because it caches likelihood vectors for all of the internal nodes.
+This is what makes it fast!
+
+Pplacer uses about 1/4 of the memory when placing on a FastTree tree as compared to a RAxML tree inferred with GTRGAMMA.
+If your reads are short and in a fixed region, the memory used by pplacer v1.1 alpha08 (or later) scales with respect to the total number of non-gap columns in your query alignment.
+You can also make it use less memory (and run faster) by cutting down the size of your reference tree.
+
+Additionally, if you are placing metagenomic reads onto a very wide alignment (such as a concatenation) read about the ``--groups`` feature in the documentation.
+
+If all else fails, there is also a flag ``--mmap-file`` to pplacer. If this
+flag is passed, pplacer will use an mmapped file instead of making large
+allocations.
+
+Details about mmap are covered in more detail in the :ref:`pplacer details section <memory usage>`.
+
+
+Why doesn't pplacer output a Newick tree?
+-----------------------------------------
+Pplacer does not output a Newick tree because it does not build phylogenetic trees.
+It maps sequences into trees, with uncertainty, and thus its output format encodes those maps.
+You can read more about the pplacer/EPA output format and our motivations for it in the corresponding paper_.
+
+If you do need a newick tree, you can look at guppy's :ref:`tog <guppy_tog>` command, but be careful, as the output is not a real phylogenetic tree.
+For example, two very similar query sequences that are both rather different than the reference sequences will end up on long parallel branches rather than in a subtree of size two.
+
+.. _paper: http://www.plosone.org/article/info%3Adoi%2F10.1371%2Fjournal.pone.0031009
+
diff --git a/_sources/faq.txt b/_sources/faq.txt
@@ -5,7 +5,7 @@ FAQ
 
 How can I cite pplacer?
 -----------------------
-Right now there is only one paper to cite::
+Please cite::
 
   @article{matsen2010pplacer,
     title={pplacer: linear time maximum-likelihood and Bayesian phylogenetic placement of sequences onto a fixed reference tree},
@@ -18,8 +18,7 @@ Right now there is only one paper to cite::
     publisher={BioMed Central Ltd}
   }
 
-At some point we will write something up for the new pplacer, guppy, taxtastic, etc., but if you use a method implemented in guppy (such as edge PCA) we hope you will cite the paper describing that method.
-
+If you use a method implemented in guppy (such as edge PCA) we hope you will cite the paper describing that method.
 
 Why is pplacer taking up so much memory?
 ----------------------------------------

diff --git a/_sources/glossary.rst.txt b/_sources/glossary.rst.txt
@@ -0,0 +1,29 @@
+:tocdepth: 3
+
+.. _glossary:
+
+========
+glossary
+========
+
+We try to keep things as simple as possible, but by necessity have developed a bit of lingo.
+Here are the definitions for some words that you will see in the manual.
+
+placement
+  An assignment of a single query sequence to a single location in the reference tree.
+  (Contrast with pquery).
+
+pquery
+  A "placed query" sequence, with uncertainty.
+  In practice this means a collection of placements and their corresponding confidence values (e.g. likelihood weight ratio, etc).
+
+placerun
+  A collection of pqueries.
+  Short for a run of a placement program.
+
+query sequence
+  The sequence getting placed into the reference tree.
+  Typically a short read.
+
+reference tree
+  The fixed tree on which placement occurs.
diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt
@@ -0,0 +1,77 @@
+pplacer documentation home
+==========================
+
+The pplacer suite consists of three separate binaries: pplacer, guppy, and rppr.
+The pplacer binary actually does phylogenetic placement and produces place files, guppy does all of the downstream analysis of placements, and rppr does useful things having to do with reference packages.
+If this is your first time looking at this documentation we suggest looking at our `overview`_.
+
+Precompiled binaries for Mac OS X and Linux can be found on the `main pplacer site`_.
+
+.. toctree::
+   :maxdepth: 2
+
+   generated_rst/pplacer
+   generated_rst/guppy
+   generated_rst/rppr
+   scripts
+   glossary
+   compiling
+   changelog
+
+
+.. raw:: html
+
+   <h2> <font color="red">Warning</font> </h2>
+
+pplacer is under heavy development, and not all parts are at the same level of maturity.
+The general guideline is: if we have released a paper about a method, then we have verified and tested it.
+Thus, the following functionality is stable:
+
+* placement and visualization ability as described in the BMC Bioinformatics paper
+* Kantorovich-Rubenstein distances
+* edge principal components and squash clustering
+* taxonomic/phylogenetic discordance analysis
+* taxon subsetting by minimizing the average distance to the closest leaf
+
+We suggest that you wait to do any serious analysis using features not described on this list.
+In particular, the taxonomic classification functionality is not stable and is still being validated.
+
+
+Tutorial
+--------
+
+We have made a tutorial_ available that demonstrates most of the functionality of the pplacer suite of programs.
+It can be downloaded and run as a shell script.
+
+
+Getting help
+------------
+
+Your question might be covered in the pplacer FAQ already:
+
+.. toctree::
+   :maxdepth: 2
+
+   faq
+
+Otherwise, support for pplacer happens through the `user group`_.
+If something is unclear in the manual and you can't find anything in past discussions, post to the group and we will get back to you right away.
+
+
+Acknowledgements
+----------------
+The pplacer code and documentation is written and maintained by the Matsen group at the Fred Hutchinson Cancer Research Center.
+Noah Hoffman has contributed many valuable ideas and bits of documentation.
+We are greatly indebted to our biological collaborators, including
+Ginger Armbrust,
+David Fredricks,
+Robin Kodner,
+Martin Morgan,
+and
+Sujatha Srivnasan
+for their suggestions.
+
+.. _user group: http://groups.google.com/group/pplacer-users
+.. _tutorial: http://fhcrc.github.com/microbiome-demo/
+.. _main pplacer site: http://matsen.fhcrc.org/pplacer/
+.. _overview: http://matsen.github.io/pplacer/generated_rst/pplacer.html#details
diff --git a/_sources/index.txt b/_sources/index.txt
@@ -5,7 +5,7 @@ The pplacer suite consists of three separate binaries: pplacer, guppy, and rppr.
 The pplacer binary actually does phylogenetic placement and produces place files, guppy does all of the downstream analysis of placements, and rppr does useful things having to do with reference packages.
 If this is your first time looking at this documentation we suggest looking at our `overview`_.
 
-Precompiled binaries for Mac OS X and Linux can be found on the `main pplacer site`_.
+Precompiled binaries for Mac OS X and Linux can be found on the the `GitHub releases page <https://github.com/matsen/pplacer/releases/tag/v1.1.alpha19>`_.
 
 .. toctree::
    :maxdepth: 2
@@ -23,19 +23,14 @@ Precompiled binaries for Mac OS X and Linux can be found on the `main pplacer si
 
    <h2> <font color="red">Warning</font> </h2>
 
-pplacer is under heavy development, and not all parts are at the same level of maturity.
-The general guideline is: if we have released a paper about a method, then we have verified and tested it.
-Thus, the following functionality is stable:
+pplacer is no longer under development. Here are some things that people have used the pplacer suite for:
 
-* placement and visualization ability as described in the BMC Bioinformatics paper
+* placement and visualization
 * Kantorovich-Rubenstein distances
 * edge principal components and squash clustering
 * taxonomic/phylogenetic discordance analysis
 * taxon subsetting by minimizing the average distance to the closest leaf
-
-We suggest that you wait to do any serious analysis using features not described on this list.
-In particular, the taxonomic classification functionality is not stable and is still being validated.
-
+* taxonomic classification
 
 Tutorial
 --------