Step-by-step installation instructions and best practices

PhyloAcc is a mix of Python and C++ code with dependencies for each. As such, we do not support building from source as dependency installation will vary from system to system. Instead, we offer a pre-built package through bioconda which allows installation with the package manager conda.

This section outlines in detail the steps starting from installation of conda to installation of PhyloAcc. If you already have experience with conda feel free to skip steps that you are familiar with.

PhyloAcc can be used on Windows via the WSL

While we don't have a dedicated build for Windows up on bioconda yet, you can still install and run on your Windows PC via the Windows Subsystem for Linux. This essentially installs a Linux distribution within Windows so that you can install Linux progams and run Linux commands, and it works pretty seamlessly.

Check here for more info on installing WSL. And once you do you should be able to activate a bash shell within your Windows Powershell and follow the instructions below for Linux.

1. Installing conda and mamba

conda is a cross-platform package manager, as well as the name of the command-line tool to access conda channels. mamba is a reimplementation of the conda command-line tool and is much faster than conda. We recommend using mamba and will do so through this walkthrough, but you can use conda if you prefer. Simply replace mamba with conda in the commands below.

Tip - check if mamba/conda is already installed

If you are on an institutional server or cluster, it is possible they already have mamba (or conda) installed and activated. You can check this by simply running the command:

mamba --version

If you see the text mamba X.X.X conda X.X.X, with each X being a number indicating the version, then mamba and conda are already installed and you can skip to step 3!

To install conda and mamba, first navigate to the Miniforge3 repository page. Scroll down and you will see a table in the Download section titled Miniforge3, with links for different operating systems (OS). Click on the link that coincides with your OS to download the install file.

This should download a .sh file for Linux and OSX.

Next, place the downloaded file in the location on your system where you want to install conda and mamba. If you are installing on a remote server, you'll to need either download on that system directly with a tool like wget or use another file transfer program to move the file over. You'll need to place this file somewhere on the remote system where you have permission to run programs, like your home directory.

Finally, run the install script by running the command:

bash <filename>.sh

where <filename> is the name of the script. Follow the prompts and let the script run and mamba and conda should be installed! You will also need to restart your shell (re-login) for the changes to take effect.

2. Setting up channels for bioconda

If this is your first time using conda or bioconda, you may have to set-up your channels. A channel is a remote host for different types of software. For instance, lots of biology related software is found in the bioconda channel and a lot of other software is found in the conda-forge channel. Since we are primarily interested in biological software, we want to make sure that bioconda has priority.

To set-up channels, you'll need a file in your home directory called .condarc with the following contents:

  - conda-forge
  - bioconda
  - defaults
channel_priority: strict

bioconda has instructions for automatically generating this file by running the following commands:

conda config --add channels defaults
conda config --add channels bioconda
conda config --add channels conda-forge
conda config --set channel_priority strict

Finally, you can confirm that your .condarc file is set up correctly by running the command:

cat ~/.condarc

The output should look like the yellow box above.

3. Creating a conda environment for PhyloAcc

conda is able to install and solve package dependencies by working in environments, self-contained file systems where the current user has full permissions. To create a new enviornment, run:

mamba create -n <environment name>

Where <environment name> is something descriptive for the purpose of the environment. For instance, for installing and running PhyloAcc, I would call this one phyloacc-env:

mamba create -n phyloacc-env

Follow any prompts on the screen to create the environment.

4. Activating your PhyloAcc conda environment

Even though an envrionment has been created, to install software or run software you've already installed in it you must activate it:

mamba activate phyloacc-env

You might notice that your command prompt changes based on which environment you have activated. If you ever wish to exit an environment, simply type mamba deactivate.

5. Installing PhyloAcc from bioconda

Now that a conda environment is set up you are ready to install PhyloAcc from bioconda!

To install PhyloAcc, run the command:

mamba install phyloacc

Follow the prompts on the screen and wait for the dependencies to install. Once finished, you should be ready to run PhyloAcc! To make sure, run the command: --version

which should print out the version info for PhyloAcc and: --depcheck

which ensures that the C++ binaries are installed. If you get an error during either of these commands, or one of the dependency checks fails, you will have to troubleshoot the installation process.

Troubleshooting common installation problems

1. conda: command not found

If you see the conda: command not found error when trying to install PhyloAcc it likely means:

  1. conda isn't installed - See here for installation instructions
  2. conda or mamba hasn't been initialized - If you didn't say yes to the final prompt when installing Miniforge3 (conda and mamba), your shell hasn't been setup yet. You may need to run mamba init and restart your shell. If you try to run mamba init and get the same error, you'll have to provide the full path to the mamba executable, which should be something like /where/you/installed/miniforge3/bin/mamba

2. conda cannot solve the environment

If the mamba install phyloacc command fails or hangs for a long time the program might be struggling with installing dependencies given the current settings. To solve this, try the following:

  1. Make sure conda is up to date. To update conda, run the command:
    conda update -n base -c defaults conda
  2. Make sure your channels are set-up to give bioconda priority

3. command not found

If you see the command not found error some time after you have successfully run the mamba install phyloacc command, it likely means you aren't in the same environment as where you installed PhyloAcc. Make sure you activate the correct conda environment.