CLI Parameters¶

Complete reference for all TaxTriage parameters, organized by category. Parameters prefixed with -- are pipeline parameters (double hyphen); Nextflow-native flags use a single hyphen (e.g., -resume, -profile).

Input and Sample Information¶

SRA / ENA Download¶

Applies whenever --fastq_1 or a samplesheet fastq_1 cell holds an accession.

Pre-Aligned Input (BAM / CRAM / SAM)¶

Start from reads you have already aligned. Pre-aligned samples skip QC, trimming, host removal, classification and reference download. See Pre-Aligned Input for the full guide.

Supply --reference_fasta (the reference the alignment was made against) whenever you have it. A consensus derived from the alignment overstates similarity between related organisms and makes conflict-based read removal more aggressive.

Workflow Control and Execution¶

process {
    resourceLimits = [ cpus: 16, memory: '64.GB', time: '24.h' ]
}

Air-gapped / no-internet runs: The pipeline pins nf-tower@1.17.3 in nextflow.config so Nextflow uses the locally cached plugin without fetching remote metadata. If you hit a Conversion = '4' error on a machine that has never run the pipeline before, the plugin cache is empty - run once with internet access to populate it, or use NXF_OFFLINE=false temporarily. You can also pass Nextflow's native -offline flag (single hyphen) to fully suppress all network calls once plugins are cached:

nextflow run . -offline [other params]

Preprocessing and Read Filtering¶

Taxonomic Classification and Databases¶

Supported Downloadable Databases¶

Additional Kraken2 databases: benlangmead.github.io/aws-indexes/k2

Reference Selection and Assemblies¶

⚠️ The --reference_fasta FASTA header must follow NCBI's format: >NC_003663.2 Cowpox virus, complete genome. The accession is followed by a space and then the organism description.

Taxid Resolution Order¶

For every genome pulled into the pipeline, TaxTriage needs to resolve the sequence accession to a numeric NCBI taxid. It works through the following steps in order, stopping as soon as a match is found:

1. RefSeq assembly summary - The primary source. The GCF/GCA assembly accession is looked up against the #assembly_accession column in assembly_summary_refseq.txt (downloaded live, or supplied via --assembly). This resolves the vast majority of standard reference genomes.

2. GenBank assembly summary - If --enable_genbank is set (or --assembly_summary_genbank is provided alongside --assembly), the same lookup is repeated against assembly_summary_genbank.txt. GenBank contains a much larger set of GCA-prefixed assemblies that are not mirrored in RefSeq; enabling this catches those genomes at the cost of a larger download and slightly longer startup.

3. Custom accession map (--custom_accession_map) - A user-supplied file with accession and taxid columns (optional name/organism; tab, comma or semicolon delimited; # comments allowed). Entries are authoritative: a listed accession takes the map's taxid even if steps 1-2 matched it (local FASTA headers are matched to assemblies by fuzzy organism name, which can pick the wrong one), and a name also replaces the organism name. Keys match with or without the version suffix (OR833055 covers OR833055.1). The same map is used for in-silico simulation (via merged.taxid.tsv) and for spike-in references (--spikein_sheet). This is the right tool for local reference FASTAs that use non-standard or private accessions (e.g. CUSTOM_SEQ_001), or for nuccore accessions (like OR833055.1) that exist in NCBI's sequence databases but have no corresponding assembly summary entry. The accession column must match the nuccore accession in the FASTA header (not the GCF/GCA assembly ID).

Example TSV:

accession    taxid   name
OR833055.1   2697049 Severe acute respiratory syndrome coronavirus 2
CUSTOM_SEQ_001   12345

1. NCBI E-utilities fallback - Always active when internet access is available. For any accession still unresolved after steps 1 - 3, TaxTriage queries NCBI's esearch + esummary E-utilities APIs by nuccore accession to retrieve the taxid directly. Providing --email (your registered NCBI email) increases the rate limit from 3 to 10 requests/second. Failures are non-fatal - the taxid is left blank and a warning is printed rather than aborting the run. On air-gapped systems this step silently produces no results; use --custom_accession_map as a substitute.

Air-gapped tip: Use --assembly + --assembly_summary_genbank (if needed) to supply pre-downloaded summary files, and --custom_accession_map for any accessions not covered by those summaries. This fully replaces all network-dependent taxid resolution.

Assembly Selection Order¶

The Taxid Resolution Order above runs accession → taxid. This section is the reverse direction - taxid → assembly - i.e. deciding which genome to download for each top-hit organism (download_fastas.py, used by the DOWNLOAD_ASSEMBLY module). TaxTriage picks an assembly in this order, stopping at the first that resolves:

1. Curated accession (accession-first) - If the organism's row in the pathogen sheet (assets/pathogen_sheet.csv, or your --pathogens sheet) has a non-empty assembly_accession, that exact assembly (GCF_* / GCA_*) is used, provided it exists in the supplied assembly summary. This lets you pin a specific, validated genome per organism and bypass the heuristic ranking below. Matching is keyed by both taxid and organism name, so it works in taxid mode and in --fuzzy (name) mode.

2. Local taxid match with priority tiers - Otherwise, every assembly whose taxid matches is ranked and the best is chosen, highest priority first:

Ties - and equal-tier candidates - are broken by source order: the RefSeq summary (assembly_summary_refseq.txt) is consulted before GenBank (assembly_summary_genbank.txt), so a RefSeq assembly is preferred over an equivalent GenBank one. (--enable_genbank only adds GenBank as a lower-priority source; it never overrides a RefSeq match.)

1. NCBI E-utilities fallback (--ncbi_fallback) - For any organism still unresolved after the local summary lookup, download_fastas.py can query NCBI's esearch + esummary APIs - by accession first, then by taxid - to locate an assembly. This is used by the offline database build; provide --email to raise the NCBI rate limit. It is left off inside the pipeline containers by default so runs stay offline-safe; the local taxid match (step 2) is the in-pipeline fallback.

The assembly_accession column is populated automatically when the curated database is (re)built (add_assembly_column.py), and is appended as the last column so the sheet's other columns keep their positions. Rows with no downloaded assembly are left blank and simply fall through to step 2.

Alignment and Mapping¶

Automatic RAM back-off. When --mmap2_I / --mmap2_K are not set, minimap2 scales both down on each retry so out-of-memory failures (e.g. exit code 143) succeed on a later attempt without manual tuning:

Attempt	-I (index)	-K (query)	Memory request
1	8G	500M	24 GB
2	4G	200M	40 GB
3	2G	100M	56 GB
4	1G	50M	72 GB

MINIMAP2_ALIGN / FILTER_MINIMAP2 retry up to 3 times (4 attempts total). User-supplied --mmap2_I / --mmap2_K always take priority over these defaults.

Host Removal¶

Named host targets¶

Defined in conf/hosts.config, selected with --genome <name>. Each target carries the RefSeq assemblies to align against and the taxids that go with them; the genomes are fetched from NCBI the first time a target is used and cached in --host_reference_dir, so later runs re-use the download.

Because read-level removal is never complete, a target's taxids are also merged into --remove_taxids (dropped from the classification report) and --report_flag_exclude_taxids (never counted as a detection). Pass either parameter as an empty string to opt out of that merge for it.

To add a host, add an entry to conf/hosts.config with taxids, accessions and a description - no code change is needed.

Pathogen Discovery and Reporting Filters¶

Primary pathogens are always shown; the --show_* flags only reveal the lower-severity categories. See Microbial Categories for what each category means and how it is resolved per body site.

TASS Scoring and Threshold Parameters¶

See TASS Scoring for a full explanation of how each metric contributes.

On the two rep_breadth_* parameters. These guard against scaffold-level draft assemblies, where the reference is thousands of ~1 kb contigs rather than a few chromosomes. Without them, a single read covering one small scaffold sets the coverage for the entire species - inflating both the breadth and minhash terms at once. The defaults comfortably admit any chromosome-level reference; raise them if your panel contains large scaffolds that still act as noise magnets, or set both to 0 to restore the previous behaviour. See TASS Scoring 11.3.

Novelty Detection (Reference-Free / Open-Set)¶

The novelty branch classifies the de novo assembly (all post-QC reads, aligned or not) with a pluggable backend against a broad database, surfacing organisms the reference panel never aligned. By default it predicts genes with Pyrodigal first and classifies those (--disable_gene classifies the whole contigs). It is additive and never alters TASS scores. See Novelty Detection for the full walkthrough and the per-backend database table.

Candidate-gate. Whether a genus+ taxon is reported as a candidate is controlled by novelty_score.py, whose effective cutoff is max(--novelty_min_reads, ceil(min_cand_frac × placeable_hits)). The floor is the top-level --novelty_min_reads (default 2). The depth-scaling fraction min_cand_frac (default 0.002) is a script default, not a pipeline flag; the NOVELTY_SCORE module forces it to 0 when --novelty_min_reads ≤ 1. For very shallow residuals, set --novelty_min_reads 1.

--novelty requires de novo contigs, so pair it with --use_denovo. It works well alongside a sparse --reference_fasta/--organisms panel, where the closed-set table is intentionally limited and the novelty branch recovers higher-rank genera. Report-side, the Detection Rescue toggles can re-surface sub-threshold and novelty-supported detections without changing any score.

Annotation and Functional Analysis¶

VF/AMR annotation runs on each sample's de novo contigs. Samples that assembled contigs but aligned no reference now carry their annotation into the comparison report's Summary and VF/AMR views (previously only the Novelty tab showed signal for them). This is automatic when --annotate is set - see Detection Rescue → Annotation of unaligned samples.

MicroBERT and AI/ML Predictions¶

See Pipeline Modules → MicroBERT for setup details.

When --microbert is supplied, the pipeline clusters each sample's aligned reads (MMSEQS_EASYCLUSTER), runs the model over the cluster representatives (MICROBERT_PREDICT), and produces a per-accession confidence profile (MICROBERT_PARSE → *.microbert.accession.tsv). The model's per-sequence top-1 probability is aggregated by the reference accession each read aligned to (read-support-weighted), so the score attaches to the detected organism rather than to the model's own predicted-taxid namespace. match_paths.py then joins this profile to each organism via its reference accession(s) and stores it as mmbert / mmbert_model.

This surfaces two columns in the reports:

They appear in the Interactive Report Table tab (visible by default) and the mmbert% column of the Organism Discovery Report PDF.

Model domain matters. The probability reflects what the chosen model was trained to recognise. A viral model (e.g. VHDB) scores every organism's reads on a "virus-likeness" basis, so a bacterium may receive a moderate score and a virus a high one - interpret the value relative to the model, not as an absolute identity confidence.

Output, Reporting, and Visualization¶

Combined Data Export¶

Writes the interactive report's tables to spreadsheets during the run, so nobody has to open all.odr.html and export them one at a time. Same catalog, same column headers as the report's Export Data panel - see Interactive Report → Export Data. Output lands in <outdir>/report/export_data/.

Datasets¶

Run export_data.py --list-datasets for the live catalog, and export_data.py -i <report> --list-columns all for each table's column names (the strings --export_data_columns expects).

Pivot: counting detections against metadata¶

--export_data_formats pivot crosses the detections with a run-metadata field, which is how you answer "how many hits to this organism came from each collection site / host type / run". It writes both a .csv and an .xlsx (with the axes recorded on the Export Info sheet).

# hits per organism per collection site, as a crosstab
nextflow run . --export_data xlsx,pivot --export_data_pivot location --export_data_level Strain

# the same counted by specimen, in tidy long form
export_data.py -i results/report/all.odr.html -o export/ --formats pivot \
    --pivot-field host_disease --pivot-measure specimens --pivot-shape long

export_data.py -i <report> --list-fields prints the metadata fields a given run carries, with how many distinct values each has. Samples with nothing recorded for the chosen field are grouped under (not recorded) rather than dropped, so the totals still add up.

Re-exporting an existing report¶

bin/export_data.py also runs standalone against any report the pipeline already built, so an old run can be exported without re-running anything:

export_data.py -i results/report/all.odr.html -o export/ --formats xlsx,wide --level Strain

Whole-sample QC verdicts are evaluated live in the report (the pipeline only seeds the default rules), so the QC Flag column in a pipeline-side sample_summary export is present for header parity but left blank. Export from the report itself to get the verdicts.

Report Sample-QC Flags¶

Whole-sample criteria that seed the interactive report's Sample QC / Flags rule set. These are report defaults only: every sample still runs through the full workflow and appears in every output. A sample that matches is marked in the Heatmap, Table, Metadata & Mapping and Summary tabs and, with --report_flag_action hide, also removed from those views (reversibly - the report keeps a one-click toggle). Users can edit, add to or delete every rule live in the report.

Example - flag anything shallow, uninformative, or missing its collection site:

nextflow run . -profile docker \
    --input samplesheet.csv \
    --report_flag_min_reads 500000 \
    --report_flag_min_organisms 1 --report_flag_organism_tass 75 \
    --report_flag_metadata "environmental_site:empty:;host_disease:contains:influenza"

Report Organism-QC Flags¶

Per-detection criteria (one organism in one sample) that seed the interactive report's Organism QC / Flags rule set. Report defaults only - nothing is removed from any run output. A matching row is highlighted in the Summary, Table and Heatmap or, with --report_org_flag_action hide, removed from the report's views (reversible from the sidebar dropdown). Every rule can be edited live in the report.

Each of --report_org_flag_min_reads, --report_org_flag_min_tass and --report_org_flag_ani becomes its own rule (a row is flagged when any matches). --report_org_flag_genus scopes all of them to the listed genera; given on its own, it flags every organism in those genera.

A --report_flag_rules JSON file may also carry an "organism_rules" block - {"view": "hide", "rules": [{"action": "hide", "conds": [{"field": "Genus", "op": "in", "value": "Streptococcus"}, {"field": "# Reads Aligned", "op": "<", "value": 50}]}]} - which replaces the parameters above.

Example - hide low-read Streptococcus / Staphylococcus hits, the weaker of any pair sharing ≥ 99 % ANI, and minor members of a genus (--report_org_flag_genus scopes only the min-reads / min-TASS / ANI parameters, not --report_org_flag_criteria):

nextflow run . -profile docker \
    --input samplesheet.csv --enable_matrix \
    --report_org_flag_genus "Streptococcus,Staphylococcus" --report_org_flag_min_reads 50 \
    --report_org_flag_criteria "ani_max:>=:99; genus_rank:>:1 & genus_share:<:5" \
    --report_org_flag_action hide

Classifier vs alignment¶

Three of the derived fields compare what Kraken2/Centrifuge assigned (the K2 Reads column) against what the aligner corroborated (# Reads Aligned) - the gap between the two is the usual signature of a database artefact or a conserved-region pile-up, and neither column shows it alone:

unsupported_k2_organisms is usually the more actionable of the three: the sample-level ratio tells you something is off, this tells you how many organisms are responsible. Both honour --report_flag_exclude_taxids, which matters here - host is often the loudest classifier call in the sample.

nextflow run . -profile docker \
    --input samplesheet.csv \
    --report_flag_rules classifier_qc.json     # unsupported_k2_organisms >= 1

Rules file format¶

--report_flag_rules takes either a bare list of rule objects or an object with logic, missing_fails, view, exclude_taxids and rules (the two report-wide settings may also be given here instead of on the command line):

{
  "logic": "any",
  "missing_fails": false,
  "view": "all",
  "exclude_taxids": ["9606"],
  "rules": [
    { "source": "meta", "field": "total_reads", "op": "<", "value": 500000, "action": "hide" },
    { "source": "derived", "field": "unique_taxids_above_tass", "op": "<", "value": 1, "tass": 75, "action": "flag" },
    { "source": "runmeta", "field": "sample_origin_country", "op": "empty", "value": "", "action": "flag" },
    { "source": "data", "field": "Coverage", "agg": "max", "op": "<", "value": 10, "action": "flag" },
    { "source": "derived", "field": "unsupported_k2_organisms", "op": ">=", "value": 1, "k2min": 50, "action": "flag" }
  ]
}

source is one of:

A malformed rule is reported on stderr and skipped rather than failing the run. See Interactive Report → Sample QC flags.

Deprecated Parameters¶

These parameters are no longer actively supported:

Nextflow Core Arguments¶

These are Nextflow-native flags (single hyphen):