The following instructions describe how to install
augur (bioinformatics tooling) and
auspice (our visualization app) on macOS or an Ubuntu-style Linux distribution.
If you are using Windows, we have instructions for installing a Linux subsystem to get Nextstrain running.
Before digging in, it’s worth reading the difference between a local & container installation, both of which will install the components behind nextstrain and allow you to run and visualize analyses on your computer.
Download and install the latest version of Miniconda which will make the
conda command available to you.
We’re going to create a new environment called “nextstrain”, which automatically installs
augur and dependencies. We’ll then install
auspice into this environment.
curl http://data.nextstrain.org/nextstrain.yml --compressed -o nextstrain.yml conda env create -f nextstrain.yml conda activate nextstrain npm install --global auspice
and we’re all done 🙌.
The beauty of this is that whenever you want to use
auspice you can just jump into the “nextstrain” conda environment and you’re good to go!
conda activate nextstrain # test things are installed / run analyses augur -h auspice -h # when you're done, leave the environment conda deactivate
source activate nextstrain pip install nextstrain-augur --upgrade npm update --global auspice
If you’d rather not use conda to manage things, then you’ll have to do a bit more work! This requires you to manage your python installation (python 3.4 or above is required). Augur’s published on PyPi as nextstrain-augur, so you can install it with pip like so:
python -m pip install nextstrain-augur
Test your installation.
Augur uses some common external bioinformatics programs which you’ll need to install to have a fully functioning toolkit.
augur tree requires at least one of
On macOS, you can install these external programs using Homebrew with:
brew install mafft iqtree raxml fasttree vcftools
On Debian/Ubuntu, you can install them via:
sudo apt install mafft iqtree raxml fasttree vcftools
Other Linux distributions will likely have the same packages available, although the names may differ slightly.
You’ll need to have an installation of Node.js to install auspice. This can be done via conda as simply as
conda create -yn auspice nodejs=10, or by using nvm or by installing manually.
Once this is done (check via
node --version), then:
npm install --global auspice auspice --help # to check things worked
This is useful for debugging, modifying the source code, or using an unpublished feature branch. Similar to installing augur with python you’ll need a copy of python and the required dependencies.
We’re going to use conda to manage environments here, but there’s a number of ways you can do this.
# clone the GitHub repo git checkout https://github.com/nextstrain/augur.git cd augur # make sure python & dependencies are installed. # if you'd like to use the "augur" pre-made conda environment then: conda env create -f environment.yml conda activate augur # install augur from source pip install -e .[dev] # test it works! augur --version
Note that you can use
pip install . as the final step, but this means changes to the source code won’t be reflected in your
auspice version… which you probably want if you’re going to the trouble of installing from source!
This gives us the same advantages as installing augur from source 😀 Note that here I’m using conda to create an “auspice” environment with nodejs installed — if you’d prefer to do something else then just replace those two steps.
# use conda to create an environment with nodejs 10 conda create -yn auspice nodejs=10 conda activate auspice # grab the GitHub auspice repo git checkout https://github.com/nextstrain/auspice.git cd auspice # install using npm npm install --global . # test it works auspice --version auspice --help
Auspice should now be available everywhere, as long as you’re in this environment. Easy! At least on MacOS, changes to the source code are reflected in this system-wide install.
This work is made possible by the open sharing of genetic data by research groups from all over the world. We gratefully acknowledge their contributions. Special thanks to Kristian Andersen, Allison Black, David Blazes, Peter Bogner, Matt Cotten, Ana Crisan, Gytis Dudas, Vivien Dugan, Karl Erlandson, Nuno Faria, Jennifer Gardy, Becky Garten, Dylan George, Ian Goodfellow, Nathan Grubaugh, Betz Halloran, Christian Happi, Jeff Joy, Paul Kellam, Philippe Lemey, Nick Loman, Sebastian Maurer-Stroh, Louise Moncla, Oliver Pybus, Andrew Rambaut, Colin Russell, Pardis Sabeti, Katherine Siddle, Kristof Theys, Dave Wentworth, Shirlee Wohl and Nathan Yozwiak for comments, suggestions and data sharing.
© 2015-2019 Trevor Bedford and Richard Neher