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 Anaconda to installation of PhyloAcc. If you already have experience with Anaconda or 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 Anaconda

Anaconda is a distribution of the Python programming language with other software to facilitate data science tasks. We are interested in the package manager associated with Anaconda, conda, as it will handle the installation of PhyloAcc and its dependencies. So, to use conda we need to first install the Anaconda distribution.

Tip - check if Anaconda/conda is already installed

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

conda --version

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

To install Anacaonda, first navigate to the Anaconda downloads page and click on the link to download the install file.

Caution - Make sure you're downloading the right version for your OS

The Anaconda website automatically detects the operating system of the computer that has browsed to the site and recommends the Anaconda version for that OS. If you are installing Anaconda on your personal computer this should be fine. However, if you are installing on a remote server or cluster the OS is likely different. Click on the appropriate version for the OS on your desired install system under Get Additional Installers to get the correct version.

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 Anaconda. If you are installing on a remote server, you'll to need either download on that system directly with something 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 Anaconda should be installed!

2. Activating Anaconda

When Anaconda has been installed, it needs to be activated for the system to know to use its software (like conda). To activate, run: 

source /<path>/<to>/anaconda3/bin/activate

Where /<path>/<to>/ is the location where you installed Anaconda. For instance, if you installed Anaconda in your home directory, you should see the anaconda3/ folder there, and you could activate with the command: 

source ~/anaconda3/bin/activate

Once activated, you should be able to run conda: 

conda --version

This should print out the text conda X.XX.X, with each X being a number indicating the version. If you get an error at this point, something has gone wrong with installation or activation and you'll need to re-visit those steps.

Tip - Add the Anaconda activate command to your user profile

You may want Anaconda to be activated automatically when you login, you could add the source /<path>/<to>/anaconda3/bin/activate command to your user profile. Your user profile is located in your home directory, though it is hidden (use ls -a to see hidden files). It will usually be called something like .bash_profile or .profile. If none of those files exist, you may be able to create them. Open your profile file and add the command and save. It will then be run whenever you login. For more information about bash profiles see: Bash startup files

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: 

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

conda create -n phyloacc-env

Follow the 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: 

conda 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 conda deactivate.

5. Installing PhyloAcc from bioconda

Now that a Anaconda has been installed and a conda environment set up you are ready to install PhyloAcc from 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. Follow the instructions in the link above to setup channels for bioconda for the first time.

You can also change your channel order at any time by editing their order in your .condarc file in your home directory

To install PhyloAcc, run the command: 

conda 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.

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. Anaconda isn't installed - See here for installation instructions
  2. Anaconda isn't activated - See here for activation instructions

2. conda cannot solve the environment

If the conda 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 conda 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.