Merge pull request #687 from nextstrain/update-api-docs

Update API docs
nextstrain · Feb 26, 2021 · 8556ac4 · 8556ac4
2 parents 698df3d + 93b977a
commit 8556ac4
Show file tree

Hide file tree

Showing 16 changed files with 148 additions and 2 deletions.
diff --git a/augur/index.py b/augur/index.py
@@ -32,6 +32,7 @@ def index_sequence(sequence, values):
         for the given values, and a final column with the number of characters
         that didn't match any of those in the given values.
 
+
     >>> other_IUPAC = {'r', 'y', 's', 'w', 'k', 'm', 'd', 'h', 'b', 'v'}
     >>> values = [{'a'},{'c'},{'g'},{'t'},{'n'}, other_IUPAC, {'-'}, {'?'}]
     >>> sequence_a = Bio.SeqRecord.SeqRecord(seq=Bio.Seq.Seq("ACTGN-?XWN"), id="seq_A")

diff --git a/docs/api/augur.import.rst b/docs/api/augur.import.rst
@@ -0,0 +1,7 @@
+augur.import module
+===================
+
+.. automodule:: augur.import
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/augur.index.rst b/docs/api/augur.index.rst
@@ -0,0 +1,7 @@
+augur.index module
+==================
+
+.. automodule:: augur.index
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/augur.rst b/docs/api/augur.rst
@@ -6,6 +6,13 @@ augur package
    :undoc-members:
    :show-inheritance:
 
+Subpackages
+-----------
+
+.. toctree::
+
+   augur.util_support
+
 Submodules
 ----------
 
@@ -22,7 +29,9 @@ Submodules
    augur.filter
    augur.frequencies
    augur.frequency_estimators
+   augur.import
    augur.import_beast
+   augur.index
    augur.lbi
    augur.mask
    augur.parse

diff --git a/docs/api/augur.util_support.color_parser.rst b/docs/api/augur.util_support.color_parser.rst
@@ -0,0 +1,7 @@
+augur.util\_support.color\_parser module
+========================================
+
+.. automodule:: augur.util_support.color_parser
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/augur.util_support.color_parser_line.rst b/docs/api/augur.util_support.color_parser_line.rst
@@ -0,0 +1,7 @@
+augur.util\_support.color\_parser\_line module
+==============================================
+
+.. automodule:: augur.util_support.color_parser_line
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/augur.util_support.date_disambiguator.rst b/docs/api/augur.util_support.date_disambiguator.rst
@@ -0,0 +1,7 @@
+augur.util\_support.date\_disambiguator module
+==============================================
+
+.. automodule:: augur.util_support.date_disambiguator
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/augur.util_support.metadata_file.rst b/docs/api/augur.util_support.metadata_file.rst
@@ -0,0 +1,7 @@
+augur.util\_support.metadata\_file module
+=========================================
+
+.. automodule:: augur.util_support.metadata_file
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/augur.util_support.node_data.rst b/docs/api/augur.util_support.node_data.rst
@@ -0,0 +1,7 @@
+augur.util\_support.node\_data module
+=====================================
+
+.. automodule:: augur.util_support.node_data
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/augur.util_support.node_data_file.rst b/docs/api/augur.util_support.node_data_file.rst
@@ -0,0 +1,7 @@
+augur.util\_support.node\_data\_file module
+===========================================
+
+.. automodule:: augur.util_support.node_data_file
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/augur.util_support.node_data_reader.rst b/docs/api/augur.util_support.node_data_reader.rst
@@ -0,0 +1,7 @@
+augur.util\_support.node\_data\_reader module
+=============================================
+
+.. automodule:: augur.util_support.node_data_reader
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/api/augur.util_support.rst b/docs/api/augur.util_support.rst
@@ -0,0 +1,21 @@
+augur.util\_support package
+===========================
+
+.. automodule:: augur.util_support
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+
+   augur.util_support.color_parser
+   augur.util_support.color_parser_line
+   augur.util_support.date_disambiguator
+   augur.util_support.metadata_file
+   augur.util_support.node_data
+   augur.util_support.node_data_file
+   augur.util_support.node_data_reader
+   augur.util_support.shell_command_runner
diff --git a/docs/api/augur.util_support.shell_command_runner.rst b/docs/api/augur.util_support.shell_command_runner.rst
@@ -0,0 +1,7 @@
+augur.util\_support.shell\_command\_runner module
+=================================================
+
+.. automodule:: augur.util_support.shell_command_runner
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/usage/cli/cli.rst b/docs/usage/cli/cli.rst
@@ -10,6 +10,7 @@ We're in the process of adding examples and more extensive documentation for eac
 	:maxdepth: 1
 
 	parse
+	index
 	filter
 	mask
 	align

diff --git a/docs/usage/cli/index.rst b/docs/usage/cli/index.rst
@@ -0,0 +1,46 @@
+============
+augur index
+============
+
+.. argparse::
+    :module: augur
+    :func: make_parser
+    :prog: augur
+    :path: index
+
+Speed up filtering with a sequence index
+========================================
+
+As we describe in :doc:`the zika tutorial <docs.nextstrain.org:tutorials/zika>`, augur index precalculates the composition of the sequences (e.g., numbers of nucleotides, gaps, invalid characters, and total sequence length) prior to filtering.
+The resulting sequence index speeds up subsequent filter steps especially in more complex workflows.
+
+.. code-block:: bash
+
+    mkdir -p results/
+    augur index \
+        --sequences data/sequences.fasta \
+        --output results/sequence_index.tsv
+
+The first lines in the sequence index look like this.
+
+.. code-block:: bash
+
+    strain	length	A	C	G	T	N	other_IUPAC	-	?	invalid_nucleotides
+    PAN/CDC_259359_V1_V3/2015	10771	2952	2379	3142	2298	0	0	0	0	0
+    COL/FLR_00024/2015	10659	2921	2344	3113	2281	0	0	0	0	0
+    PRVABC59	10675	2923	2351	3115	2286	0	0	0	0	0
+    COL/FLR_00008/2015	10659	2924	2344	3110	2281	0	0	0	0	0
+
+We then provide the sequence index as an input to augur filter commands to speed up filtering on sequence-specific attributes.
+
+.. code-block:: bash
+
+    augur filter \
+        --sequences data/sequences.fasta \
+        --sequence-index results/sequence_index.tsv \
+        --metadata data/metadata.tsv \
+        --exclude config/dropped_strains.txt \
+        --output results/filtered.fasta \
+        --group-by country year month \
+        --sequences-per-group 20 \
+        --min-date 2012
diff --git a/docs/usage/usage.rst b/docs/usage/usage.rst
@@ -2,8 +2,6 @@
 Using Augur
 ===========
 
-.. note:: We have just released version 6 of augur -- `check our upgrading guide <../releases/migrating-v5-v6.html>`__
-
 Augur consists of a number of tools that allow the user to filter and align sequences, infer trees, and integrate the phylogenetic analysis with meta data.
 The different tools are meant to be composable and the output of one command will serve as the input of other commands.
 All of Augur's commands are accessed through the ``augur`` program followed by the name of the command, e.g. ``augur ancestral`` to infer ancestral sequences.
-Original file line number
+Diff line change
@@ Expand Up @@
     	:maxdepth: 1
     	parse
+    	index
     	filter
     	mask
     	align
@@ Expand Down @@