Python modules

Introduction

The standard Python distribution includes the standard Python library. However, several additional Python modules are required for building and running the kaiju software. These additional modules can be installed in one of 3 standard ways (there are others, but these are by far the most common):

  • Build from a source tarball.

  • Use the pip package manager.

  • Use the conda package manager.

Code built from a source tarball provides the most flexibility in your installation, but also requires the most time, as well as detailed knowledge of build procedures. We will only use this method when the required modules are not available via pip or conda.

The pip and conda tools provide the same function - Python package management. The major difference (other than command syntax) is the default software source used by the tools. For pip, packages are (by default) installed from the Python Package Index, which is the standard package repository for the Python community. The conda tool by default installs packages from repositories managed by anaconda.org, managed by Anaconda Inc. as part of its Anaconda Python distribution. The conda package manager is also available using the minimal distribution provided by Miniconda. We strongly prefer to use the miniconda-based installation on all platforms, since it gives the user complete control over the precise Python package versions in use. However, most other python environments should “just work”. For example, users have reported success using this procedure with the python “module” system provided on pleiades.

Regardless of your Python distribution and version, this documentation will presume use of the pip package manager, since it is a default feature of the standard Python distribution. Where appropriate, instructions will also be provided for those using the conda package manager.

Installing additional modules

These instructions should work on all platforms (MacOS, Linux, HPC).

This OUTDATED file specifies the minimum versions of the additional modules (relative to the standard Python distribution) required by the kaiju software. This list was automatically generated by the pipreqs tool. You may be able to use later versions of these packages, but these are the versions we are currently using, and this list may be considered as a stable starting point for the required Python packages. These packages may be installed together using the following command:

pip install -r requirements.txt

If version conflicts arise, you can install different versions of each package individually with pip. You may need to adjust package versions based on your operating system and python version. For reference, we provide the following environment files generated from working conda-based environments on a Big Sur Mac, on cheyenne.ucar.edu, and on pleiades.nas.nasa.gov, for python 3.7 and 3.8:

You can create copies of these environments with the command:

conda env create -f environment.yml

where environment.yml is replaced by the name of the environment file for your platform and python version.