Nextstrain is an open-source project to harness the scientific and public health potential of pathogen genome data. We provide a continually-updated view of publicly available data with powerful analytics and visualizations showing pathogen evolution and epidemic spread. Our goal is to aid epidemiological understanding and improve outbreak response.
Resulting data and inferences are available live at the website nextstrain.org. Documentation is available at nextstrain.org/docs.
Definition: One held to foretell events by omens.
Augur is the bioinformatics toolkit we use to track evolution from sequence and serological data. It provides a collection of commands which are designed to be composable into larger processing pipelines. Documentation for augur is available at nextstrain.org/docs/bioinformatics.
Augur is written in Python 3 and requires at least Python 3.4.
It's published on PyPi as nextstrain-augur, so you can install it with pip (or pip3) like so:
pip install nextstrain-augur
You can also install from a git clone or other copy of the source code by running:
pip install .
If your system has both Python 2 and Python 3 installed side-by-side, you may need to use pip3 or python3 -m pip instead of just pip (which often defaults to Python 2 when both Python versions are installed).
This install depends on a fairly minimal set of external Python libraries. There are some functions in augur that require a larger set of dependencies. These can be installed via:
pip install .[full]
pip install nextstrain-augur[full]
Augur uses some common external bioinformatics programs which you'll need to install to have a fully functioning toolkit:
-
augur alignrequires mafft -
augur treerequires at least one of: -
Bacterial data (or any VCF usage) requires vcftools
Alternatively, all these dependencies (as well as augur itself) can be installed via Conda by running:
conda env create -f environment.yml
Once installed, Conda the enviroment need to be activated whenever augur is to be used, by running:
conda activate augur
All of Augur's commands are accessed through the augur program.
For example, to infer ancestral sequences from a tree, you'd run augur ancestral.
If you've installed the nextstrain-augur package, you can just run augur.
Otherwise, you can run ./bin/augur from a copy of the source code.
usage: augur [-h] {parse,filter,mask,align,tree,refine,ancestral,translate,clades,traits,sequence-traits,titers,export,validate,version} ...
Augur: A bioinformatics toolkit for phylogenetic analysis.
positional arguments:
{parse,filter,mask,align,tree,refine,ancestral,translate,clades,traits,sequence-traits,titers,export,validate,version}
parse Parse delimited fields from FASTA sequence names into
a TSV and FASTA file.
filter Filter and subsample a sequence set.
mask Mask specified sites from a VCF file.
align Align multiple sequences from FASTA or VCF.
tree Build a tree using a variety of methods.
refine Refine an initial tree using sequence metadata.
ancestral Infer ancestral sequences based on a tree.
translate Translate gene regions from nucleotides to amino
acids.
clades Assign clades to nodes in a tree based on amino-acid
or nucleotide signatures.
traits Infer ancestral traits based on a tree.
sequence-traits Annotate sequences based on amino-acid or nucleotide
signatures.
titers Annotate a tree with actual and inferred titer
measurements.
export Export JSON files suitable for visualization with
auspice.
validate Validate a set of JSON files intended for
visualization in auspice.
version Print the version of augur.
optional arguments:
-h, --help show this help message and exit
For more information on a specific command, you can run it with the --help option, for example, augur tree --help.
Development of augur happens at https://github.com/nextstrain/augur.
We currently target compatibility with Python 3.4 and higher. This may be increased to in the future.
Versions for this project from 3.0.0 onwards aim to follow the Semantic Versioning rules.
From within a clone of the git repository you can run ./bin/augur to test your local changes without installing them.
(Note that ./bin/augur is not the script that gets installed by pip as augur; that script is generated by the entry_points configuration in setup.py.)
You can also install augur from source as an "editable" package so that your global augur command always uses your local source code copy:
pip install -e .[dev]
This is not recommended if you want to be able to compare output from a stable version of augur to a development version (e.g. comparing output of augur installed with pip and ./bin/augur from your local source code).
Run doctests and unit tests for augur from Python 3 with pytest from the top-level of the augur repository.
pytest -c pytest.python3.ini
Or, run tests for augur from Python 2.
pytest -c pytest.python2.ini
As tests run on the development code in the augur repository, your environment should not have an existing augur installation that could cause a conflict in pytest.
New releases are tagged in git using an "annotated" tag. If the git option
user.signingKey is set, the tag will also be signed. Signed tags are
preferred, but it can be hard to setup GPG correctly. The release branch
should always point to the latest release tag. Source and wheel (binary)
distributions are uploaded to the nextstrain-augur project on
PyPi.
There is a ./devel/release script which will prepare a new release from your
local repository. It ends with instructions for you on how to push the release
commit/tag/branch and how to upload the built distributions to PyPi. You'll
need a PyPi account and twine installed to do the latter.
Branches and PRs are tested by Travis CI jobs configured in .travis.yml.
New releases, via pushes to the release branch, trigger a new docker-base
build to keep the Docker image up-to-date.
Documentation is built using Sphinx and hosted on Read The Docs. Versions of the documentation for each augur release and git branch are available and preserved. Read The Docs is updated automatically from commits and releases on GitHub.
Documentation is mostly written as reStructuredText (.rst) files, but they can also be Markdown (.md) files. There are advantages to both formats:
- reStructuredText enables python-generated text to fill your documentation as in the auto-importing of modules or usage of plugins like
sphinx-argparse(see below). - Markdown is more intuitive to write and is widely used outside of python development.
- If you don't need autogeneration of help documentaiton, then you may want to stick with writing Markdown.
Sphinx, coupled with reStructuredText, can be tricky to learn. Here's a subset of reStructuredText worth committing to memory to help you get started writing these files.
Many Sphinx reStructuredText files contain a directive to add relations between single files in the documentation known as a Table of Contents Tree (TOC Tree).
Human-readable augur and augur subcommand documentation is written using a Sphinx extension called sphinx-argparse.
The documentation source-files are located in ./docs, with ./docs/index.rst being the main entry point.
Each subsection of the documentation is a subdirectory inside ./docs.
For instance, the tutorials are all found in ./docs/tutorials and are included in the documentation website via the directive in ./docs/index.rst.
Building the documentation locally is useful to test changes. First, make sure you have the development dependencies of augur installed:
pip install -e .[dev]
(This installs packages listed in the dev section of extras_require in setup.py, in addition to any normal augur dependencies as necessary.)
Then build the HTML output format by running:
make -C docs html
You can see other available formats by running:
make -C docs help
To update the API documentation after adding or removing an augur submodule, autogenerate a new API file as follows.
sphinx-apidoc -T -f -MeT -o docs/api augur
Sphinx caches built documentation by default, which is generally great, but can cause the sidebar of pages to be stale. You can clean out the cache with:
make -C docs clean
To view the generated documentation in your browser, Mac users should run:
open docs/_build/html/index.html
Linux users can view the docs by running:
xdg-open docs/_build/html/index.html
Copyright 2014-2019 Trevor Bedford and Richard Neher.
Source code to Nextstrain is made available under the terms of the GNU Affero General Public License (AGPL). Nextstrain is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.