Skip to content

Installation

Requirements

  • Python 3.10 or later, on Linux or macOS (x86_64 or arm64)
  • External tools, called by kmhelpers:
Tool Version Role
kmindex ≥ 0.6.1 builds and queries the indexes
kmtricks ≥ 1.6.0 counts k-mers, run by kmindex
ntCard ≥ 1.2.2 estimates the number of k-mers of each sample

The pip and Bioconda installs below provide these tools. To use other versions, see Custom tool versions.

All conda commands require Conda (Miniconda or Miniforge, for instance).

With pip (PyPI)

python -m venv ~/.kmhelpers
source ~/.kmhelpers/bin/activate
pip install kmhelpers
kmhelpers install-deps

Note

install-deps downloads prebuilt kmtricks, kmindex and ntcard binaries next to the kmhelpers executable, here ~/.kmhelpers/bin, so they are in PATH whenever the environment is active. A virtual environment keeps them apart from the rest of the system. The architecture should be detected from the current machine; --target x86_64 or --target arm64 selects another one.

To update:

pip install --upgrade kmhelpers

With Conda (Bioconda)

conda create -n kmhelpers -c conda-forge -c bioconda kmhelpers
conda activate kmhelpers

kmindex (with kmtricks) and ntcard are installed as dependencies.

To update:

conda update -n kmhelpers -c conda-forge -c bioconda kmhelpers

Note

A new release reaches Bioconda a few hours to a few days after PyPI.

From source

1. Clone the repository

git clone --branch v0.7.3 https://github.com/sebllns/kmhelpers
cd kmhelpers

2. Create and activate the Conda environment

conda env create -f conda/environment.yml -p ./.env
conda activate ./.env

This installs kmindex, ntcard and the Python dependencies into .env, and kmhelpers itself in editable mode, so changes to the source take effect without reinstalling.

Note

Activate the environment in each new terminal session before using kmhelpers. It can also be created in a permanent location, for example -p ~/.kmhelpers.

Update

From the repository root:

git fetch --tags
git checkout v0.7.3
conda env update -f conda/environment.yml -p ./.env --prune

Verify the installation

kmhelpers --version
kmhelpers check-deps

check-deps prints the version and path of each tool, or a warning for a tool it cannot find. kh is a short alias for kmhelpers.

Custom tool versions

kmhelpers looks for each tool:

  1. in the directory given by <TOOL>_BIN_PATH (KMINDEX_BIN_PATH, KMTRICKS_BIN_PATH, NTCARD_BIN_PATH), if set
  2. then in PATH

kmindex itself runs kmtricks from PATH, so keep both in a directory that is in PATH, or in the same directory.

With install-deps

Each version option takes a release of the tool (0 skips it): --kmindex and --kmtricks take a version from the kmindex and kmtricks releases, without the leading v, and --ntcard a tag from the portable ntCard builds.

# Replace kmindex next to kmhelpers, keep the other tools
kmhelpers install-deps --kmindex 0.6.1 --kmtricks 0 --ntcard 0

# Install all tools into a separate directory
kmhelpers install-deps --path ~/kmh_tools
export PATH=~/kmh_tools:$PATH

From source, or another package manager

Build or install the tool following its own instructions (kmindex, kmtricks, ntCard), then make its binary directory visible to kmhelpers:

# Example for kmindex

# --> EASIEST <-- Add the directory to PATH 
export PATH=/path/to/kmindex/bin:$PATH

# OR

# For kmhelpers ONLY: set the variable of that tool
export KMINDEX_BIN_PATH=/path/to/kmindex/bin

Note

Add the export line to ~/.bashrc (or the profile of your shell) to keep it across sessions. In a Conda environment, a tool version can also be pinned directly, for example conda install -c conda-forge -c bioconda kmindex=0.6.1.

Run kmhelpers check-deps to confirm which binary and version are used.