Python modules
==============

Introduction
------------

The `standard Python distribution <https://www.python.org/>`_ 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 <https://www.pypi.org>`_, which is the standard package repository for the Python community. The ``conda`` tool by default installs packages from repositories managed by `anaconda.org <https://anaconda.org/>`_, managed by `Anaconda Inc. <https://www.anaconda.com/>`_ as part of its Anaconda Python distribution. The ``conda`` package manager is also available using the minimal distribution provided by `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_. 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 <https://bitbucket.org/aplkaiju/kaiju/src/master/kaipy/requirements.txt>`_ 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 <https://github.com/bndr/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:

.. code-block:: shell

   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:

.. code-block:: shell

   conda env create -f environment.yml

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