Installation

mkprobes lives in its own repository (github.com/gofflab/mkprobes); the in-tree copy inside the fishtools repository is frozen legacy. Two supported setups: uv (Option A) or a conda/mamba environment (Option B). Both need the same external tools; Option B installs them for you from bioconda.

Requirements

  • OS: Linux/macOS recommended.

  • Python: >=3.12 (from pyproject.toml).

  • External tools (needed on PATH for CLI probe design/prep; all available on bioconda):

    • bowtie2

    • jellyfish (bioconda package kmer-jellyfish)

    • gffread

    • RepeatMasker (optional; only used at final manifest assembly)

All commands in this documentation are written bare (mkprobes ...), assuming your environment is activated. Activate once per shell session as shown below.

Option A: install with uv

From the repository root:

uv sync

This creates/updates the project virtual environment and installs mkprobes with all Python dependencies. External tools must already be on PATH (e.g. via Homebrew, module system, or a separate conda env).

Activate the environment, then run commands directly:

source .venv/bin/activate
mkprobes --help

Option B: install with conda/mamba

The repository ships an environment.yml that builds one environment containing the Python package and the external tools (bowtie2, jellyfish, gffread) from bioconda. From the repository root:

mamba env create -f environment.yml

(conda env create -f environment.yml works identically, just slower to solve.) Then:

conda activate mkprobes
mkprobes --help

Notes:

  • Create the environment from the repository root — the package is installed editable (pip: -e .), so the path is relative.

  • RepeatMasker is commented out in environment.yml (it is optional and pulls large repeat libraries); enable it there or add it later:

    mamba install -n mkprobes -c bioconda repeatmasker

  • After a git pull the editable install picks up code changes automatically; re-run mamba env update -f environment.yml only when dependencies change.

Verify installation

With your environment activated:

mkprobes --help
python -c "import mkprobes; print('mkprobes import OK')"
gffread --version && bowtie2 --version | head -1 && jellyfish --version

To run the test suite:

pip install -e ".[dev]"
pytest

HPC/cluster add-on guidance

Recommended pattern for cluster runs:

  1. Build and test one environment interactively.

  2. Freeze/package it for compute nodes.

  3. Keep large intermediate outputs on node-local scratch, then copy final outputs to shared storage.

Practical tips:

  • Put reference dataset prep (mkprobes prepare or mkprobes ingest) in a shared, versioned location to avoid repeated downloads/indexing.

  • Stage per-job output on local scratch (for high I/O steps) then sync back.

  • Cap thread/process settings to match scheduler allocation:

    • mkprobes prepare --threads <N>

Common install failures

  • ModuleNotFoundError: click or loguru:

    • You are likely outside the intended environment.

    • Activate it (source .venv/bin/activate or conda activate mkprobes) and retry; re-run uv sync / mamba env update -f environment.yml if it is stale.

  • mkprobes prepare or mkprobes ingest fails on external binaries:

    • Confirm bowtie2, jellyfish, and gffread are available in PATH on both login and compute nodes.