Installation

The following instructions will install PALEOMIX for the current user, but does not include specific programs required by the pipelines. For pipeline specific instructions, refer to the requirements sections for the BAM, the Phylogentic, and the Zonkey pipeline.

The recommended way of installing PALEOMIX is by use of the pip package manager for Python 3. If pip is not installed, then please consult the documentation for your operating system. For Debian based operating systems, pip may be installed as follows:

$ sudo apt-get install python3-pip

In addition, some libraries used by PALEOMIX may require additional development files, namely those for zlib, libbz2, liblzma, and for Python 3:

$ sudo apt-get install libz-dev libbz2-dev liblzma-dev python3-dev

Once all requirements have been installed, PALEOMIX may be installed using pip:

$ python3 -m pip install paleomix==1.3.7

To verify that the installation was carried out correctly, run the command paleomix:

$ paleomix
PALEOMIX - pipelines and tools for NGS data analyses
Version: v1.3.7

...

If you have not previously used pip, then you may need to add the pip bin folder to your PATH and restart your terminal before running the paleomix command:

$ echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc

Self-contained installation

The recommended method for installing PALEOMIX is using a virtual environment. Doing so allows different versions of PALEOMIX to be installed simultaneously and ensures that PALEOMIX and its dependencies are not affected by the addition or removal of other python modules.

This installation method requires the venv module. On Debian based systems, this module must be installed separately:

$ sudo apt-get install python3-venv

Once venv is installed, creation of a virtual environment and installation of PALEOMIX may be carried out as shown here:

$ python3 -m venv venv
$ ./venv/bin/pip install paleomix==v1.3.7

Following successful completion of these commands, the paleomix executable will be accessible in the ./venv/bin/ folder. However, as this folder also contains a copy of Python itself, it is not recommended to add it to your PATH. Instead, simply link the paleomix executable to a folder in your PATH. This can be accomplished as follows:

$ mkdir -p ~/.local/bin/
$ ln -s ${PWD}/venv/bin/paleomix ~/.local/bin/

If ~/.local/bin is not already in your PATH, then it can be added as follows:

$ echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc

Upgrading an existing installation

Upgrade an existing installation of PALEOMIX, installed using the methods described above, may also be accomplished using pip. To upgrade a regular installation, simply run pip install with the --upgrade option:

$ pip install --upgrade paleomix

To upgrade an installation a self-contained installation, simply call the pip executable in that environment:

$ ./venv/bin/pip install --upgrade paleomix

Conda installation

Conda can be used to automatically setup a self-contained environment that includes the software required by PALEOMIX.

To install conda and also set it up so it can use the bioconda bioinformatics repository, follow the instructions on the bioconda website here.

Next, run the following commands to download the conda environment template for this release of PALEOMIX and to create a new conda environment named paleomix using that template:

$ curl -fL https://github.com/MikkelSchubert/paleomix/releases/download/v1.3.7/paleomix_environment.yaml > paleomix_environment.yaml
$ conda env create -n paleomix -f paleomix_environment.yaml

You can now activate the paleomix environment with:

$ conda activate paleomix

PALEOMIX requires that the Picard JAR file can be found in a specific location, so we can symlink the versions in your conda environment into the correct place:

$ (paleomix) mkdir -p ~/install/jar_root/
$ (paleomix) ln -s ~/*conda*/envs/paleomix/share/picard-*/picard.jar ~/install/jar_root/

Note

If you installed conda in a different location, then you can obtain the location of the paleomix environment by running conda env list.

Once completed, you can test the environment works correctly using the pipeline test commands described in Example projects and data-sets.

To deactivate the paleomix environment, simply run:

$ conda deactivate

If you ever need to remove the entire environment, run the following command:

$ conda env remove -n paleomix