How to install

Installation

Python 3.10–3.13; conda is recommended. R is not required for the Python pipeline.

Core install (required)

git clone https://github.com/ctlab/samovar
cd samovar
conda env create -f environment.yml
conda activate samovar
chmod +x install.sh
./install.sh

Without conda:

python3 -m pip install -e .
./install.sh

install.sh writes ~/.config/samovar/config.json (and a copy at build/config.json) with the repo root, Python path, NCBI email, and tools found on $PATH. After that, samovar can be run from any directory.

It prompts for an NCBI Entrez email (genome downloads). In CI the default is test@samovar.com. Override with NCBI_EMAIL=you@institution.edu.

After a successful install you get a required vs optional tool table. Re-print it any time:

samovar tools --status

Core flags and environment

Option	What it does
`./install.sh`	Editable Python package, ISS, snakemake, C++ combiner, plots
`SAMOVAR_INSTALL_DEV=1 ./install.sh`	Also pytest / flake8 extras (CI default)
`SAMOVAR_UPDATE_SHELL=0 ./install.sh`	Shared/HPC: no `PATH` / `~/.bashrc` edits; `source ~/.config/samovar/env`
`SAMOVAR_OFFLINE=1 SAMOVAR_WHEELHOUSE=/wheels ./install.sh`	Air-gapped pip
`NCBI_EMAIL=you@institution.edu`	Entrez email for genome fetch
`SAMOVAR_CONDA=/path/to/mamba`	Conda/mamba used for sidecar envs (NanoSim, ART)

Required programs (must be present after ./install.sh):

Program	Role in SamovaR
python	Pipeline runtime (`python_path`)
iss	Default `samovar generate` (InSilicoSeq)
snakemake	Annotator Snakefiles
C++ combiner	Merge annotator reports (`make -C src/cpp`)
cnsplots / altair	Pipeline plots

Annotators (Kraken2, Kaiju, …) are not required to install SamovaR. Configure them when you samovar prepare.

Optional extras

Install extras after the core package (they import samovar). You can stack names:

./install.sh OPAL MultiQC CAMISIM NanoSim ART
# or with the core install:
SAMOVAR_INSTALL_CAMISIM=1 SAMOVAR_INSTALL_NANOSIM=1 ./install.sh

Fragile simulators (NanoSim, ART) go into separate conda prefixes under ~/.cache/samovar/envs/ so they never pin scikit-learn 0.23 into the SamovaR env. Point SamovaR at them with tool_envs / *_path in config.json (see below).

OPAL (CAMI HTML profiles)

In SamovaR: pipeline plots always include OPAL-style metrics in Python. If opal.py is installed, exec also writes CAMI .profile files and the official OPAL HTML under <plots>/opal/. Disable a run with SAMOVAR_OPAL=0.

Install

./install.sh OPAL
# or SAMOVAR_INSTALL_OPAL=1 ./install.sh

Uses pip install cami-opal --no-deps so OPAL’s old numpy pins do not fight the SamovaR env.

Check

samovar tools --status    # line OPAL
python -c "from samovar.opal import opal_executable; print(opal_executable())"

Config (~/.config/samovar/config.json):

"opal_path": "/path/to/opal.py",
"tools": { "opal.py": "/path/to/opal.py" }

MultiQC (HTML report)

In SamovaR: samovar prepare turns the end-of-run MultiQC report on by default when MultiQC is installed. Native heatmaps/scatters/bars use MultiQC’s plot picker and --export. Disable with --no-multiqc or SAMOVAR_MULTIQC=0.

Install

./install.sh MultiQC

Check

samovar tools --status
multiqc --version

Config

"multiqc_path": "/path/to/multiqc",
"tools": { "multiqc": "/path/to/multiqc" }

CAMISIM (optional generate backend)

In SamovaR: samovar generate --simulator camisim writes .generate/configs/camisim.yaml. Modes:

Mode	What happens
`table`	Community design, then ISS (no Nextflow)
`illumina`	CAMISIM + ART
`ont`	CAMISIM + NanoSim
`wgsim`	CAMISIM + wgsim
`hybrid`	Same community, mixed technologies; annotation tables get `read_type`

Install

./install.sh CAMISIM

Clones https://github.com/CAMI-challenge/CAMISIM into ~/.cache/samovar/CAMISIM and sets camisim_path. Needs Nextflow for read modes (not for table).

Check

samovar tools --status
ls "$(python -c 'from samovar.camisim import discover_camisim; print(discover_camisim())')/main.nf"
nextflow -version

Config

"camisim_path": "/home/you/.cache/samovar/CAMISIM",
"nextflow_path": "/usr/bin/nextflow",
"tools": { "camisim": "/home/you/.cache/samovar/CAMISIM", "nextflow": "/usr/bin/nextflow" }

Nextflow (not bundled): conda install -c bioconda nextflow or https://nextflow.io — then set nextflow_path.

NanoSim (ONT; sidecar env)

In SamovaR: CAMISIM --camisim-mode ont and hybrid. NanoSim 3.x wants Python 3.10 and scikit-learn 0.23. Installing it into the SamovaR env will break plots/ML.

Install (recommended)

./install.sh NanoSim
# prefix: ~/.cache/samovar/envs/nanosim

Requires conda/mamba (SAMOVAR_CONDA if it is not on PATH).

Install yourself

conda create -p ~/.cache/samovar/envs/nanosim -c conda-forge -c bioconda \
  python=3.10 nanosim=3.2

Check

samovar tools --status
~/.cache/samovar/envs/nanosim/bin/simulator.py -h

Config (written by ./install.sh NanoSim)

"nanosim_path": "/home/you/.cache/samovar/envs/nanosim/bin/simulator.py",
"tools": { "simulator.py": "/home/you/.cache/samovar/envs/nanosim/bin/simulator.py" },
"tool_envs": { "nanosim": "/home/you/.cache/samovar/envs/nanosim" }

CAMISIM Nextflow then uses that prefix instead of building a second conda env for NanoSim processes.

ART (Illumina; sidecar env)

In SamovaR: CAMISIM --camisim-mode illumina and hybrid. Nextflow can also create ART on first run (bioconda::art). A sidecar env is faster and survives a clean Nextflow work dir.

Install

./install.sh ART

Install yourself

conda create -p ~/.cache/samovar/envs/art -c bioconda -c conda-forge art samtools

Check

samovar tools --status
art_illumina -h    # after the env bin dir is on PATH, or call the absolute path

Config

"art_path": "/home/you/.cache/samovar/envs/art/bin/art_illumina",
"tool_envs": { "art": "/home/you/.cache/samovar/envs/art" }

wgsim

In SamovaR: CAMISIM --camisim-mode wgsim. Often already on PATH with samtools. CAMISIM Nextflow can install it via conda.

Install yourself: conda install -c bioconda wgsim

Config: "wgsim_path": "/usr/bin/wgsim" and/or "tool_envs": { "wgsim": "/opt/conda/envs/wgsim" }

R package (`samovaR`)

In SamovaR: optional annotation regenerator from GitHub branch r-package. Not needed for the Python ensemble.

Install

./install.sh R-package

Config: "r_path", "annotation_regenerate_r" (script copied to ~/.config/samovar/annotation_regenerate.R).

Annotators (Kraken2, Kaiju, MetaPhlAn, Centrifuge, …)

In SamovaR: ensemble members at samovar prepare. Each can live in its own conda env.

{
  "path": ["/opt/other-env/bin"],
  "tools": { "kaiju": "/opt/conda/envs/kaiju/bin/kaiju" },
  "tool_envs": { "kaiju": "/opt/conda/envs/kaiju", "kraken2": "/opt/conda/envs/kraken2" }
}

path and tool_envs.<name>/bin are prepended in generated .log/samovar.sh, so bash .log/samovar.sh finds them without module load. Extra dirs at runtime: SAMOVAR_PATH=/more/bin.

Example (Kaiju only):

conda create -n kaiju -c bioconda kaiju
# then set tool_envs.kaiju to that env prefix

./install.sh keeps existing path / tools / tool_envs.

Config cheat sheet

File: ~/.config/samovar/config.json (copied to build/config.json on install).

Key	Meaning
`python_path`	Interpreter for generated scripts
`iss_path`	InSilicoSeq CLI
`opal_path` / `multiqc_path`	Optional report tools
`camisim_path` / `nextflow_path`	CAMISIM checkout and Nextflow
`nanosim_path` / `art_path` / `wgsim_path`	Simulator binaries
`tools.<name>`	Absolute executable for an annotator or helper (`name:version` objects)
`databases.<tool>.<name>`	Annotator index (`path`, `flags`, `lazy-download`, `url`, `version`); import with `samovar tools import --type database`
`tool_envs.<name>`	Conda/module prefix; `<prefix>/bin` is used
`path`	Extra prefixes or `bin/` dirs prepended at runtime
`genomes` / `genome_dirs`	NCBI cache and extra assembly libraries
`genomes.taxdump`	NCBI `nodes.dmp` / `names.dmp` (env `SAMOVAR_TAXDUMP`; fallback `databases.taxdump.ncbi`)

After editing config, re-run samovar generate / prepare / exec so scripts pick up new paths.

Co-installed vs optional (summary)

Tool	With core `./install.sh`	Optional command
Python, ISS, snakemake, C++ combiner, cnsplots	yes	—
OPAL	no	`./install.sh OPAL`
MultiQC	no	`./install.sh MultiQC`
CAMISIM (git clone)	no	`./install.sh CAMISIM`
Nextflow	no	conda / nextflow.io; set `nextflow_path`
NanoSim	no	`./install.sh NanoSim` (sidecar env)
ART	no	`./install.sh ART` (sidecar env)
wgsim / samtools	no	bioconda, or ART sidecar
R / samovaR	no	`./install.sh R-package`
Kraken2, Kaiju, MetaPhlAn, …	no	own conda env + `tool_envs`

Navigation Menu

Uh oh!

How to install

Installation

Core install (required)

Core flags and environment

Optional extras

OPAL (CAMI HTML profiles)

MultiQC (HTML report)

CAMISIM (optional generate backend)

NanoSim (ONT; sidecar env)

ART (Illumina; sidecar env)

wgsim

R package (`samovaR`)

Annotators (Kraken2, Kaiju, MetaPhlAn, Centrifuge, …)

Config cheat sheet

Co-installed vs optional (summary)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Uh oh!

How to install

Installation

Core install (required)

Core flags and environment

Optional extras

OPAL (CAMI HTML profiles)

MultiQC (HTML report)

CAMISIM (optional generate backend)

NanoSim (ONT; sidecar env)

ART (Illumina; sidecar env)

wgsim

R package (samovaR)

Annotators (Kraken2, Kaiju, MetaPhlAn, Centrifuge, …)

Config cheat sheet

Co-installed vs optional (summary)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

R package (`samovaR`)