Installation

Note

If you plan to generate alignments but not ancestors, you may want to run topiary on google colab instead of installing it locally. Running the full ancestral inference pipeline will require installing topiary in a high-performance Linux or macOS environment.

The basic installation instructions for topiary are:

  1. Download and install miniconda

  2. Install topiary using conda

  3. Install supporting software packages

1. Install miniconda

To prevent interference with other packages, we recommend installing topiary in its own conda environment. If you do not have conda installed, download and install miniconda before proceeding. Installation instructions are available on the linked miniconda page.

2. Install topiary

Once conda is installed, open a standard terminal (Linux or macOS) or an Anaconda Prompt (Windows). Copy the following commands into the prompt to run them.

conda install git
git clone https://github.com/harmslab/topiary
cd topiary
conda config --set channel_priority strict
conda env create -f environment.yml
conda activate topiary
python -m pip install . -vv

At this point, you have topiary, but not the software packages it wraps, installed. The next sections describe how to install the entire software stack.

3. Install supporting software packages

You can check which software packages are visible to topiary by:

topiary-check-installed

The output should look something like this:

topiary-check-installed terminal output


If some of the packages are not installed (passes: N), proceed to the sections below.

Important

Windows users must specify the complete path to each script when running topiary commands. To run the above command (topiary-check-installed) please type: python c:\users\harmsm\topiary\bin\topiary-check-installed, replacing the first part of the path (c:\users\harmsm) with the path on your system.

NCBI API Key

If you wish to use an NCBI API Key, set the environment variable NCBI_API_KEY to point to your key. For example:

export NCBI_API_KEY='abcdef012'

Topiary will recognize this key and increase the number of allowed requests per second to NCBI servers.

macOS and Linux instructions

You can install the software packages with:

conda install -c conda-forge -c bioconda mpi4py openmpi "muscle>=5.0" "raxml-ng>=1.1" "generax>=2.0" "blast>=2.2"

You can then check to make sure everything installed correctly by running:

topiary-check-installed

If any of these packages were not installed by conda–or you wish to install them yourself–you can install them manually using the following links:

After installation, you’ll need to make sure the directories containing these binaries are in your $PATH directory. (See here for instructions).

Note

As of this writing (Summer, 2022), conda will not install RAxML-NG, GeneRax, muscle, or blast+ on an arm64 mac (aka Apple Silicon, M1, M2, etc.). These packages must be installed manually. The RAxML-NG and GeneRax binaries remain experimental, so use with caution.

Windows instructions

Important

RAxML-NG and GeneRax do not run on Windows. To generate trees and ancestors, you must run topiary on a Linux or macOS machine. Topiary can be used on a local Windows computer to generate an alignment, which can then be passed to a Linux or macOS cluster for the ancestral inference. Tree plotting can also be run on a Windows machine.

To use topiary on Windows, you need to install two packages:

  • muscle >= 5.0. This binary comes as a single, read-to-run file. Download the file and place it in a convenient folder somewhere on your computer. Rename the file to muscle.exe.

  • NCBI blast+ >=2.0. This is a conventional package installer. Follow the on-screen prompts to install the program. This will install both the blastp and makeblastdb).

After you have installed blast+ and muscle, close and reopen the Anaconda Prompt. Then run:

conda activate topiary
python c:\Users\USERNAME\topiary\bin\topiary-check-installed

If the muscle, blastp and/or makeblastdb binaries are not found, you likely need to add the directories containing the blast and muscle binaries to the $PATH variable. This stackoverflow thread gives detailed instructions on how to accomplish this. Once you have added the directories containing muscle and blast+ to the $PATH variable, you need to close and reopen your Anaconda Prompt. Then check to see if the packages are installed.

Install from source

If you wish to install the package from source or make changes to the package, you’ll need to clone the repository:

git clone https://github.com/harmslab/topiary

You can install via conda:

cd topiary
conda env create -f environment.yml
conda activate topiary
python -m pip install . -vv

Alternatively, you can install via pip:

cd topiary
pip install -r requirements.txt

These steps will install topiary, but not the full software stack. If you are on macOS or Linux, you can install the core software by:

conda install -c conda-forge -c bioconda "openmpi<4.1.3" "muscle>=5.0" "raxml-ng>=1.1" "generax>=2.0" "blast>=2.2"

If you are on Windows, please see the windows section.

Required libraries