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.

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.

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:

channels:
  - 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:

phyloacc.py --version

which should print out the version info for PhyloAcc and:

phyloacc.py --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.

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. phyloacc.py: command not found

If you see the phyloacc.py: 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.