Installation

The instructions below assume you are either:

  1. running osx
  2. running linux (x86_64)

We do not support any other platforms, although you should be able to install and run illumiprocessor and its dependencies on various flavors of windows.

trimmomatic & illumiprocessor

You can install the illumiprocessor dependencies in one of two ways: (1) using conda and (2) manually. We strongly suggest that you use conda. There are several reasons for this, one being that we can manage lots of types of packages with conda. Another is that conda manages dependencies of packages very, very well.

Attention

Manual installation of illumiprocessor is not supported.

Attention

illumiprocessor is already installed as part of phyluce. You do not need to install anything else after installing phyluce.

First, you need to install anaconda or miniconda with Python 2.7. Whether you choose miniconda or anaconda is up to you, your needs, how much disk space you have, and if you are on a fast/slow connection.

Attention

You can easily install anaconda or miniconda in your $HOME, although you should be aware that this setup can sometimes cause problems in cluster-computing situations.

Tip

Do I want anaconda or miniconda?

The major difference between the two python distributions is that anaconda comes with many, many packages pre-installed, while miniconda comes with almost zero packages pre-installed. As such, the beginning anaconda distribution is roughly 200-500 MB in size while the beginning miniconda distribution is 15-30 MB in size.

We suggest that you install miniconda.

Tip

What version of miniconda or anaconda do I need?

Right now, illumiprocessor only runs with Python 2.7. This means that you need to install a version of miniconda or anaconda that uses Python 2.7. The easiest way to do this is to choose carefully when you download a particular distribution for your OS (be sure to choose the Python 2.7 version).

miniconda

Follow the instructions here for your platform: https://conda.io/docs/user-guide/install/index.html

Note

Once you have installed either Miniconda or Anaconda, we will refer to the install as conda throughout the remainder of this documentation.

anaconda

Follow the instructions here for your platform: http://docs.continuum.io/anaconda/install.html

Note

Once you have installed either Miniconda or Anaconda, we will refer to the install as conda throughout the remainder of this documentation.

Checking your $PATH

Regardless of whether you install miniconda or anaconda, you need to check that you’ve installed the package correctly. To ensure that the correct location for anaconda or miniconda are added to your $PATH (this occurs automatically on the $BASH shell), run the following:

$ python -V

The output should look similar to (x will be replaced by a version):

Python 2.7.x :: Anaconda x.x.x (x86_64)

Notice that the output shows we’re using the Anaconda x.x.x version of Python. If you do not see the expected output (or something similar), then you likely need to edit your $PATH variable to add anaconda or miniconda.

The easiest way to edit your path, if needed is to open ~/.bashrc with a text editor (if you are using ZSH, this will be ~/.zshrc) and add, as the last line:

export PATH=$HOME/path/to/conda/bin:$PATH

where $HOME/path/to/conda/bin is the location of anaconda/miniconda on your system (usually $HOME/anaconda/bin or $HOME/miniconda/bin).

Warning

If you have previously set your $PYTHONPATH elsewhere in your configuration, it may cause problems with your anaconda or miniconda installation of illumiprocessor. The solution is to remove the offending library (-ies) from your $PYTHONPATH.

Add the necessary bioconda repositories to conda

You need to add the location of the bioconda_ repositories to your conda installation. To do that, you can follow the instructions at the bioconda site or you can simply edit your ~/.condarc file to look like:

channels:
  - defaults
  - conda-forge
  - bioconda

Once you do this, you have access to all of the packages installed at bioconda_ and conda-forge_. The order of this file is important - conda will first search in it’s default repositories for package, then it will check conda-forge, finally it will check bioconda.

How to install illumiprocessor

You now have two options for installing illumiprocessor. You can install illumiprocessor in what is known as a conda environment, which lets you keep code for different applications separated into different environments. We suggest this route.

You can also install all of the illumiprocessor code and dependencies in your default conda environment.

Install illumiprocessor in it’s own conda environment

We can install everything that we need for illumiprocessor in it’s own environment by running:

conda create --name illumiprocessor illumiprocessor

This will create an environment named illumiprocessor, then download and install everything you need to run illumiprocessor into this illumiprocessor conda environment. To use this illumiprocessor environment, you must run:

source activate illumiprocessor

To stop using this illumiprocessor environment, you must run:

source deactivate

Install illumiprocessor in the default conda environment

We can simply install everything that we need in our default conda environment, as well. In some ways, this is easier, but it could be viewed as a less-ideal option in terms of repeatability and separability of functions. To install illumiprocessor in the default environment, after making sure that you have miniconda or anaconda in your $PATH, and after adding the bioconda repositories, run:

conda install illumiprocessor