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:
Download and install miniconda
Install topiary using conda
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:
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:
NCBI blast+ >= 2.2. (This will install both the blastp and makeblastdb programs.)
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
Core scientific python libraries:
Tree manipulation/drawing:
Packages used for tree/ancestor inferences: