taxprofiler
nf-core/taxprofiler
Taxonomic classification and profiling of shotgun short- and long-read metagenomic data
Key tools
Run it
nfclaw run taxprofiler --input samplesheet.csv --outdir results --databases <databases> -profile dockernextflow run pipelines/taxprofiler/upstream -profile docker --input samplesheet.csv --outdir results --databases <databases>nfclaw run taxprofiler --demo --outdir results # adds the upstream test profile (-profile test,docker)Inputs
| column | type | required | allowed values | constraints |
|---|---|---|---|---|
sample | string or integer | yes | matches ^[^\s]+$ | |
run_accession | string or integer | yes | matches ^[^\s]+$ | |
instrument_platform | string | yes | ABI_SOLID, BGISEQ, CAPILLARY, COMPLETE_GENOMICS, DNBSEQ, HELICOS, ILLUMINA, ION_TORRENT, LS454, OXFORD_NANOPORE, PACBIO_SMRT | |
fastq_1 | string (file path) | no | matches ^\S+\.f(ast)?q\.gz$ | |
fastq_2 | string (file path) | no | matches ^\S+\.f(ast)?q\.gz$ | |
fasta | string (file path) | no | matches ^\S+\.(fasta|fas|fna|fa)\.gz?$ |
--input must match ^\S+\.csv$.
The samplesheet is a CSV with this header (the columns the schema requires); fill each value per the table above and reference.md (no example value is invented here):
sample,run_accession,instrument_platformAny of the optional columns above may be appended to the header when your data needs them: fastq_1, fastq_2, fasta.
From data files. --input may also be the data files — a directory (searched recursively), a quoted glob, or files (--input once per file) — from which nfclaw writes this samplesheet: sample from file names; fastq_1/fastq_2 from FastQ files (mates paired by _R1/_R2, or by _1/_2 when their read names show they are mates); fasta from files matching their patterns, by sample name. Set the required columns no file determines with --sheet-set COLUMN=VALUE (a constant or a {sample}/{lane} template): run_accession (matching ^[^\s]+$); instrument_platform (one of ABI_SOLID, BGISEQ, CAPILLARY, COMPLETE_GENOMICS, DNBSEQ, HELICOS, ILLUMINA, ION_TORRENT, LS454, OXFORD_NANOPORE, PACBIO_SMRT). Preview it with --check; a run records it in <outdir>/provenance/ for replay.
Resources
Resource requests follow the pipeline's configs and selected profiles. nf-core's resource labels often assume a server — a single step can request far more memory than a workstation has, and retry rules can increase requests. If a run fails with Process requirement exceeds available memory (or CPUs), cap every request, and every retry, at what this machine actually has:
nfclaw run taxprofiler --input samplesheet.csv --outdir results --databases <databases> -profile docker \ --limit-cpus 4 --limit-memory 15.GBnfclaw turns those into Nextflow's process.resourceLimits and passes them as a -c config — the mechanism nf-core prescribes for exactly this (docs). Set them to the machine's real capacity. --limit-time DURATION also caps how long any one task may run: a task that needs longer is stopped, and so is every retry, so set it only as a deliberate ceiling, never as a guess at how long the analysis takes. The generated config is kept in <outdir>/provenance/, so commands.sh replays the run under the same ceiling.
Nextflow engine
This release declares nextflowVersion = '!>=25.10.4'.
To pin this release's declared minimum engine — useful when a newer Nextflow has incompatible config parsing:
nfclaw run taxprofiler ... --nxf-ver 25.10.4--nxf-ver is recorded in <outdir>/provenance/, so the replay uses the same engine. See known-issues.
Demo
nfclaw run taxprofiler --demo --outdir results # adds the upstream test profile (-profile test,docker)Samplesheet
A CSV with this header (the columns the schema requires). Fill each value per the constraints below; optional columns from the table may be appended.
sample,run_accession,instrument_platform| Column | Type | Required | Allowed / constraints |
|---|---|---|---|
sample | string or integer | required | matches ^[^\s]+$ |
run_accession | string or integer | required | matches ^[^\s]+$ |
instrument_platform | string | required | ABI_SOLIDBGISEQCAPILLARYCOMPLETE_GENOMICSDNBSEQHELICOSILLUMINAION_TORRENTLS454OXFORD_NANOPOREPACBIO_SMRT |
fastq_1 | string (file path) | optional | matches ^\S+\.f(ast)?q\.gz$ |
fastq_2 | string (file path) | optional | matches ^\S+\.f(ast)?q\.gz$ |
fasta | string (file path) | optional | matches ^\S+\.(fasta|fas|fna|fa)\.gz?$ |
Required parameters
--inputstring (file path)Path to comma-separated file containing information about the samples and libraries/runs.
Constraint · matches ^\S+\.csv$
--databasesstring (file path)Path to comma-separated file containing information about databases and profiling parameters for each taxonomic profiler
Constraint · matches ^\S+\.csv$
--outdirstring (directory path)The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
Parameter explorer
133 parameters · 11 groupsEvery parameter from the pinned nextflow_schema.json. nfclaw checks explicit values before launch; complex rules use the pinned pipeline's runtime validation. Search, filter by group, and expand any parameter for its default, allowed values and constraints.
116 parameters · 17 hidden
Generic options4
Display the help message.
Display the full detailed help message.
Custom MultiQC yaml file containing HTML including a methods description.
Display hidden parameters in the help message (only works when --help or --help_full are provided).
Input Output options6
Path to comma-separated file containing information about databases and profiling parameters for each taxonomic profiler
Email address for completion summary.
Path to comma-separated file containing information about the samples and libraries/runs.
MultiQC report title. Printed as page header, used for filename if not otherwise specified.
The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
Specify to save decompressed user-supplied TAR archives of databases
Postprocessing And Visualisation options12
Specify path to krona taxonomy directories (required for MALT krona plots)
Turn on generation of Krona plots for supported profilers
Turn on standardisation of taxon tables across profilers
Turn on generation of BIOM output (currently only applies to mOTUs)
The desired output format.
Add the taxon's entire ID lineage to the output. Requires --taxpasta_taxonomy_dir.
Add the taxon's entire name lineage to the output. Requires --taxpasta_taxonomy_dir.
Add the taxon name to the output. Requires --taxpasta_taxonomy_dir.
Add the taxon rank to the output. Requires --taxpasta_taxonomy_dir.
Add the taxon's entire rank lineage to the output. Requires --taxpasta_taxonomy_dir.
Ignore individual profiles that cause errors.
The path to a directory containing taxdump files.
Preprocessing General Qc options4
Specify the tool used for quality control of raw sequencing reads
Save only the final reads from all read processing steps (that are sent to classification/profiling) in results directory.
Save reads from samples that went through the adapter clipping, pair-merging, and length filtering steps for both short and long reads
Specify to skip sequencing quality control of raw sequencing reads
Preprocessing Host Removal options8
Specify path to single reference FASTA of host(s) genome(s)
Specify path to a pre-made Minimap2 index file (.mmi) of the host removal reference
Turn on long-read host removal
Turn on short-read host removal
Saved mapped and unmapped reads in BAM format from host removal
Save mapping index of input reference when not already supplied by user
Save reads from samples that went through the host-removal step
Specify path to the directory containing pre-made BowTie2 indexes of the host removal reference
Preprocessing Long Read Qc options11
Specify which tool to use for adapter trimming.
Specify which tool to use for long reads filtering
Path to a custom adapter text file, if you want to manually specify a list of adapters to remove.
This option allows inference of adapters directly from the reads instead of relying on a static database.
Specify the percent of high-quality bases to be retained
Specify the minimum length of reads to be retained
Nanoq only: specify the minimum average read quality filter (Q)
Filtlong only: specify the number of high-quality bases in the library to be retained
Skip long-read trimming
Skip long-read length and quality filtering
Turns on long read quality control steps (adapter clipping, length filtering etc.)
Preprocessing Run Merging options2
Turn on run merging
Save reads from samples that went through the run-merging step
Preprocessing Short Read Qc options19
Turns on nucleotide sequence complexity filtering
Turns on short read quality control steps (adapter clipping, complexity filtering etc.)
Save reads from samples that went through the complexity filtering step
Turn on masking rather than discarding of low complexity reads for BBduk
Specify the window size for BBDuk complexity filtering
Specify the minimum sequence entropy level for complexity filtering
Specify the minimum complexity filter threshold of fastp
Specify the minimum dust score for PRINTSEQ++ complexity filtering
Specify the complexity filter mode for PRINSEQ++
Specify which tool to use for complexity filtering
Specify adapter 1 nucleotide sequence
Specify adapter 2 nucleotide sequence
Specify a list of all possible adapters to trim. Overrides --shortread_qc_adapter1/2. Formats: .txt (AdapterRemoval) or .fasta. (fastp).
Perform deduplication of the input reads (fastp only)
Include unmerged reads from paired-end merging in the downstream analysis
Turn on merging of read pairs for paired-end data
Specify the minimum length of reads to be retained
Skip adapter trimming
Specify which tool to use for short-read QC
Profiling options48
Turn on the saving of the intermediate Kraken2 files used as input to Bracken itself into Kraken2 results folder
Turn on saving of Centrifuge-aligned reads
Specify output format from DIAMOND profiling.
Turn on saving of DIAMOND-aligned reads. Will override --diamond_output_format and no taxon tables will be generated
Specify a maximum number of reads a hit must have to be retained in the ganon report.
Specify a minimum number of reads a hit must have to be retained in the ganon report.
Specify the taxonomic report the ganon report file should display.
Specify a percentile within which hits will be reported in ganon report output..
Specify the type of ganon report to save.
Turn on saving of ganon per-read taxonomic assignment file(s).
Turn on expanding of virus hits to individual viruses rather than aggregating at a taxonomic level.
Specify taxonomic rank to be displayed in Kaiju taxon table
Turn on saving the output of KMCP search
Turn on saving minimizer information in the kraken2 report thus increasing to an eight column layout.
Turn on saving of Kraken2 per-read taxonomic assignment file
Turn on saving of Kraken2-aligned reads
Specify the number of samples for each KrakenUniq run.
Specify a RAM chunk size for all KrakenUniq databases when loading into memory when you want to load via chunks. Specify in --databases for per-database values.
Turn on saving of KrakenUniq per-read taxonomic assignment file.
Turn on saving of KrakenUniq (un-)classified reads as FASTA.
Turn on generation of MEGAN summary file from MALT results
Specify which MALT alignment mode to use
Turn on saving of MALT-aligned reads
Specify kraken2 database for prefiltering of non-prokaryotic reads with melon.
Print all mapping information in separate columns (rank, taxon name, taxon ids).
Turn on saving of MetaPhlAn reads aligned against marker genes in SAM format
Minimum read length, shorter are discarded.
Splitting length for the long reads.
Turn on removing NCBI taxonomic IDs.
Turn on saving the mgc reads count.
Turn on saving the output of synthetic long-reads
Turn on printing relative abundance instead of counts.
Turn on Bracken (and the required Kraken2 prerequisite step).
Turn on profiling with Centrifuge. Requires database to be present CSV file passed to --databases
Turn on profiling with DIAMOND. For unmerged paired-read libraries, only read1 will be used Requires database to be present CSV file passed to --databases
Turn on profiling with ganon. Requires database to be present CSV file passed to --databases.
Turn on profiling with Kaiju. Requires database to be present CSV file passed to --databases
Turn on classification with KMCP.
Turn on profiling with Kraken2. Requires database to be present CSV file passed to --databases
Turn on profiling with KrakenUniq. Requires one or more KrakenUniq databases to be present in the CSV file passed to --databases.
Turn on profiling with MALT. Requires database to be present CSV file passed to --databases
Turn on profiling with Melon. Requires a database to be present in the CSV file passed to --databases.
Turn on profiling with metacache. Requires database to be present CSV file passed to --databases
Turn on profiling with MetaPhlAn. Requires database to be present CSV file passed to --databases
Turn on profiling with mOTUs. Requires database to be present CSV file passed to --databases
Turn on profiling with sylph. Requires database to be present CSV file passed to --databases
Specifies which abundance metric to use
Specify path to sylph taxonomy to add taxonomic path to each hit.
Redundancy Estimation2
Turn on short-read metagenome sequencing redundancy estimation with nonpareil. Warning: only use for shallow short-read sequencing datasets.
Specify mode for identifying redundant reads
Outputs
Results land in --outdir; the files and directory layout depend on the selected workflow, parameters and publication settings. Run metadata is normally placed in <outdir>/pipeline_info/ (execution report, software versions), when those outputs are enabled. The pinned tree includes MultiQC support; a report is produced only when its workflow step runs. nfclaw run also writes <outdir>/provenance/ with the exact params file and the run log, <outdir>/provenance/logs/run.log — the whole launch, whose last line states the outcome (Nextflow's own log is <outdir>/.nextflow.log); unless --no-provenance it adds a run manifest (pinned version, commit and exact command), input/output SHA-256 checksums, and a replayable commands.sh.
The exact output files and directory layout for this release are documented upstream: github.com/nf-core/taxprofiler/blob/2.0.1/docs/output.md
Check a run — in the foreground or the background — with nfclaw status <outdir>: success, still running, how it ended (with the error), or stopped without an outcome; exit 0 success, 3 running, 1 otherwise.
Chaining
Run taxprofiler as one stage of a chain: nfclaw chain run starts each stage only after the one before it succeeded, and prepares its inputs from that stage's outputs. Every rule is checked against both pinned schemas.
Fed by
- createtaxdb — createtaxdb, with --generate-downstream-samplesheets, writes downstream_samplesheets/databases-taxprofiler.csv; it becomes taxprofiler's --databases, minus any database for a tool the pinned taxprofiler does not run (createtaxdb 3.1 also builds sourmash). The reads to profile (--input) and the --run-<tool> switches are the stage's own.
- demultiplex — demultiplex writes samplesheet/taxprofiler_samplesheet.csv without run_accession or instrument_platform; each sample becomes its own run, sequenced on ILLUMINA (bcl2fastq/bclconvert data — use an inline handoff for other platforms).
- detaxizer — detaxizer, with --generate-downstream-samplesheets, writes downstream_samplesheets/taxprofiler.csv for its filtered reads (paths into filter/filtered/).
- fetchngs — fetchngs writes a taxprofiler samplesheet with --nf-core-pipeline taxprofiler; run_accession and instrument_platform come from the ENA metadata. The profiling databases (--databases) are the stage's own.
nfclaw chain edges taxprofiler