SAMOVAR

Metagenomic ensemble taxonomic annotation, cross-validation, and ML re-profiling

In metagenomics, we often do not know which tool to use (or, which is much worse - know because they are SOTA). SAMOVAR team try to solve this problem with the automated benchmark based on the real inputed data to include in the model selection process information about the real community properties

Metagenomic classifiers disagree. SAMOVAR treats multiple annotators as an ensemble: it runs them on the same reads, cross-validates calls, regenerates in-silico communities from those calls, and trains a supervised re-profiler (SAMOVAR) that combines the tools.

What does the tool do? It gets the metagenome input & taxonomy profiling tools and SAMOVAR that (regenerate artficial metagenomes, evaluate & combine the tools).

We strongly recommend to understand SAMOVAR main concepts before the installation & usage, because the workflow is large & depends on a lot of other different tools

Installation

Python 3.10+; conda is recommended.

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

install.sh may ask you some questions, like e-mail for the NCBI API.

Some tools are optional but may be useful (R package, SparseDOSSA2, CAMISIM, MultiQC, OPAL, NanoSim, ART, seqtk, Nextflow). Install them all with:

./install.sh full

Already-installed extras are reused and written into the install config. More details: installation wiki.

The tool main config layout is described in config wiki.

Ensemble annotation

Built-in ensemble members (wired through samovar prepare):

Tool	Role in the ensemble
Kraken2	k-mer LCA classifier
Kaiju	protein-level (translated) classifier
Kraken / KrakenUniq	additional k-mer votes
MetaPhlAn	marker-gene profiler
Custom	extra votes; can be easily additionally implemented for the developers

Workflow:

1. Annotate real or ISS-simulated reads with every configured tool.
2. Cross-validate taxIDs across tools (CV heatmaps) and against known truth when available (F1 / R²).
3. Re-simulate a community from the annotation table (annotation2iss).
4. Re-annotate the synthetic reads and train an ML ensemble (workflow/ML.py: RandomForest / AdaBoost) that maps tool votes → corrected taxID.

%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '16px', 'fontFamily': 'arial', 'primaryColor': '#fff', 'primaryTextColor': '#000', 'primaryBorderColor': '#000', 'lineColor': '#000', 'secondaryColor': '#fff', 'tertiaryColor': '#fff'}}}%%
graph TD
    subgraph Input
        A1[FastQ / ISS genomes]
        A3[Annotator configs]
    end

    subgraph Ensemble
        A1 --> C[Initial annotation]
        A3 --> C
        C --> CV[Cross-validation]
        C --> E[Metagenome regeneration]
        E --> F[Re-annotation]
    end

    subgraph Re-profiling
        C --> ML[Train ensemble]
        F --> ML
        F --> R
        ML --> R[SAMOVAR results]
    end

Loading

Each stage have built-in & custom options. Their usage & integration approaches ar described in the tool wiki.

Brief Usage

# Generate metagenome (skip for running SAMOVAR on real data as ensemble)
samovar generate \
    --genome_dir $SAMOVAR/data/test_genomes/meta \
    --host_genome $SAMOVAR/data/test_genomes/host/9606.fna \
    --output_dir samovar_out

# Prepare workflow & scripts, create generation config
samovar prepare \
    --output_dir samovar_out \
    --kraken2-test "kraken2 $DB_KRAKEN2" \
    --kaiju-test "kaiju $DB_KAIJU"

# Do SAMOVARing (resumes from `.log/checkpoints`; `--redo` reruns every step)
samovar exec --output_dir samovar_out

# Apply that trained pipeline to a new sample (no retraining)
samovar apply --input_dir new_fastq --pipeline samovar_out --output_dir apply_out

# Same stages, but regenerate abundance tables and refit the ML reprofiler
samovar apply --input_dir new_fastq --pipeline samovar_out --output_dir apply_full --full

# MultiQC report: optional
# samovar multiqc --output_dir samovar_out -- --export --interactive

samovar apply

Takes one new sample (a FASTQ directory) and a completed pipeline run (--pipeline, the original --output_dir from prepare/exec). Configs, databases, annotators, export/scoring contracts, and the trained reprofiler are loaded from that run.

• Normal (samovar apply): QC → the configured annotators → combine → the saved reprofiled_annotations/trained_model.joblib → export and scoring contracts. The ML component is not fitted again.
• --full: the same prefix, then abundance-table regeneration (the run’s ModDirect analogue under regenerated/.regenerated_abundance) and a refit via samovar.reprofilers.run_reprofiler, then the remaining contracts. Profiles need not match normal apply.

Required source state: .log/configs/config_init.yaml, and for normal mode reprofiled_annotations/trained_model.joblib. --full also needs regenerated_annotations (labeled training tables from the original run). Outputs land in --output_dir (aliases --outdir / --directory); the source run is not overwritten. Provenance is written to .log/apply.yaml.

A generate → apply --full → merge (initial / regenerated) → exec walkthrough is in examples/apply_and_merge.

R package

The optional R generator (samovar_boil) lives on the r-package branch and is not part of this tree. Install it with ./install.sh R-package (requires R + remotes). That writes a small R driver into ~/.config/samovar/ that only calls exported samovaR functions. Then set regeneration_mode: samovar.

References

BibTeX for built-in tools lives in cite/ (cite/*.bib). Refresh after install with ./install.sh --rebuild-citations 1 (default) or python -m samovar.citations rebuild. Also cite every annotator used in the ensemble.