Installation

pip install sequana-multitax

To upgrade an existing installation:

pip install sequana-multitax --upgrade

Quick Start

Step 1 — prepare the working directory:

sequana_multitax \
    --input-directory /path/to/reads \
    --databases /path/to/krakendb

This creates a multitax/ working directory containing config.yaml and a multitax.sh launch script.

Step 2 — review the configuration (optional but recommended):

cd multitax
cat config.yaml   # adjust parameters as needed

Step 3 — run the pipeline:

sh multitax.sh

Taxonomic database

You will need one or more Kraken2 databases. You can download a toy database for testing:

sequana_taxonomy --download toydb

The pipeline also requires a taxonomy file stored in ~/.config/sequana/taxonomy.dat. Download it once with:

sequana_multitax --update-taxonomy

Call this command again from time to time when unknown taxon IDs appear in the HTML reports.

Multiple databases can be passed to run iterative classification:

sequana_multitax \
    --input-directory /path/to/reads \
    --databases /path/to/virusdb /path/to/bacteriadb

Apptainer / Singularity

Every tool runs inside a pre-built container. Point --apptainer-prefix to a shared directory so images are downloaded once and reused across projects:

sequana_multitax \
    --input-directory /path/to/reads \
    --databases /path/to/krakendb \
    --apptainer-prefix ~/.sequana/apptainers

Pass extra bind mounts with --apptainer-args if your data lives outside $HOME:

--apptainer-args "-B /data:/data"

When running snakemake manually, include the apptainer options:

snakemake -s multitax.rules --configfile config.yaml --cores 4 \
    --use-apptainer \
    --apptainer-prefix ~/.sequana/apptainers \
    --apptainer-args "-B /home:/home"

HPC / SLURM cluster

On a cluster with SLURM, pass --profile slurm:

sequana_multitax \
    --input-directory /path/to/reads \
    --databases /path/to/krakendb \
    --profile slurm \
    --slurm-queue fast \
    --jobs 40 \
    --apptainer-prefix /shared/containers

BLAST on unclassified reads

Reads that remain unclassified after Kraken can optionally be BLASTed against a local database:

sequana_multitax \
    --input-directory /path/to/reads \
    --databases /path/to/krakendb \
    --store-unclassified \
    --do-blast-unclassified

This requires a local BLAST+ installation and a downloaded nt database.

Pipeline overview

1. Kraken2 — classify reads against one or more databases sequentially.

2. Krona — interactive pie charts per sample.

3. [Optional] BLAST — align unclassified reads against a nucleotide DB.

4. MultiQC — aggregated summary report across all samples.

Each sample produces an HTML report with a static pie chart (species distribution; grey = unclassified) that links to an interactive Krona chart.

When multiple databases are provided they are applied sequentially. The order matters: reads classified by the first database are removed before the second database is run.

Configuration file

After running sequana_multitax, a config.yaml is created in the working directory. Key sections:

• sequana_taxonomy — databases, confidence threshold, store_unclassified

• blast — enable/disable BLAST on unclassified reads

• multiqc — aggregated report settings

Full reference: config.yaml

Requirements

• kraken2

• sequana_taxonomy

• krona

Changelog