createtaxdb
nf-core/createtaxdb
Parallelised and automated creation of metagenomic classifier databases of different tools
Key tools
Run it
nfclaw run createtaxdb --input samplesheet.csv --outdir results --dbname <dbname> -profile dockernextflow run pipelines/createtaxdb/upstream -profile docker --input samplesheet.csv --outdir results --dbname <dbname>nfclaw run createtaxdb --demo --outdir results # adds the upstream test profile (-profile test,docker)Runtime corrections
For this exact commit, nfclaw run applies createtaxdb-sourmash-copy-sort-v1 in a separate verified working copy. Sourmash sorts a copy rather than the shared genome list. The original pinned checkout stays unchanged. The direct Nextflow command omits this correction. The actual corrected bytes, recipe, source archive and executable modes are recorded for replay; resume refuses missing or changed source identity. Use NFCLAW_SOURCE_CACHE to select another writable user cache. Recorded source corrections explains the exact scope and validation.
Inputs
| column | type | required | allowed values | constraints |
|---|---|---|---|---|
id | string | yes | matches ^\S+$ | |
taxid | integer | yes | ||
fasta_dna | string (file path) | no | matches ^\S+\.(fasta|fas|fa|fna)(\.gz)?$ | |
fasta_aa | string (file path) | no | matches ^\S+\.(fasta|fas|fa|faa)(\.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):
id,taxidAny of the optional columns above may be appended to the header when your data needs them: fasta_dna, fasta_aa.
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: id from file names; fasta_dna, fasta_aa 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): taxid (integer). 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 createtaxdb --input samplesheet.csv --outdir results --dbname <dbname> -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 createtaxdb ... --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 createtaxdb --demo --outdir results # adds the upstream test profile (-profile test,docker)This pinned test profile reads its genome sheet and taxonomy files from a moving test-datasets branch. For a bare demo, nfclaw stages the same six-genome sheet with immutable FASTA URLs and supplies the taxonomy files from commit 9248a89ada220333b7bc3c7c07af5eb229c16d5b, every file byte-identical to that branch. The sheet is bundled in provenance, so a replay reads the recorded sheet. Explicit input, taxonomy or MALT map selectors, the test-data base, extra profiles or --config disable the fixture. Other releases retain their own defaults.
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.
id,taxid| Column | Type | Required | Allowed / constraints |
|---|---|---|---|
id | string | required | matches ^\S+$ |
taxid | integer | required | — |
fasta_dna | string (file path) | optional | matches ^\S+\.(fasta|fas|fa|fna)(\.gz)?$ |
fasta_aa | string (file path) | optional | matches ^\S+\.(fasta|fas|fa|faa)(\.gz)?$ |
Required parameters
--inputstring (file path)Path to comma-separated file containing information about the samples in the experiment.
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.
--dbnamestringSpecify name that resulting databases will be prefixed with.
--unzip-batch-sizeintegerHow many files to unzip in parallel in a single job.
Parameter explorer
73 parameters · 6 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.
56 parameters · 17 hidden
Database Building options33
Specify parameters being given to bracken build. Parameters must be supplied in quotes: --<tool>_build_options "--your_param".
Turn on extending of Kraken2 database to include Bracken files. Requires nucleotide FASTA File input.
Turn on building of Centrifuge database. Requires nucleotide FASTA file input.
Turn on building of Centrifuger database. Requires nucleotide FASTA file input.
Turn on building of DIAMOND database. Requires amino-acid FASTA file input.
Turn on building of ganon database. Requires nucleotide FASTA file input.
Turn on building of Kaiju database. Requires amino-acid FASTA file input.
Turn on building of KMCP database. Requires nucleotide FASTA file input.
Turn on building of Kraken2 database. Requires nucleotide FASTA file input.
Turn on building of KrakenUniq database. Requires nucleotide FASTA file input.
Turn on building of MALT database. Requires nucleotide FASTA file input.
Turn on building of MetaCache database. Requires nucleotide FASTA file input.
Whether to build a sourmash reference from the provided nucleotide sequences.
Whether to build a sourmash reference from the provided amino acid sequences.
Turn on building of sylph database. Requires nucleotide FASTA file input.
Specify parameters being given to centrifuge-build. Parameters must be supplied in quotes: --<tool>_build_options "--your_param".
Specify parameters being given to centrifuger-build. Parameters must be supplied in quotes: --<tool>_build_options "--your_param".
Specify parameters being given to diamond makedb. Parameters must be supplied in quotes: --<tool>_build_options "--your_param".
Specify parameters being given to ganon buildcustom. Parameters must be supplied in quotes: --<tool>_build_options "--your_param".
Specify parameters being given to kaiju-mkbwt. Parameters must be supplied in quotes: --<tool>_build_options "--your_param".
Save intermediate files otherwise not required for downstream classification.
Specify parameters being given to kmcp compute. Parameters must be supplied in quotes: --<tool>_build_options "--your_param".
Specify parameters being given to kmcp index. Parameters must be supplied in quotes: --<tool>_build_options "--your_param".
Specify parameters being given to kraken2 build. Parameters must be supplied in quotes: --<tool>_build_options "--your_param".
Retain intermediate Kraken2 build files for inspection.
Specify parameters being given to krakenuniq build. Parameters must be supplied in quotes: --<tool>_build_options "--your_param".
Save intermediate files otherwise not required for downstream classification.
Specify parameters given to malt-build. Must include --sequenceType DNA or --sequenceType Protein. Parameters must be supplied in quotes: `--malt_build_options "--sequenceType DNA --your_param".
Specify parameters being given to metacache build.
Sourmash can perform the main build step in parallel batches. Set the size of the batches.
Specify parameters given to sourmash sketch dna. Must start with sourmash sketch dna's '--param-string'.
Specify parameters given to sourmash sketch protein. Must start with sourmash sketch protein's '--param-string'.
Specify parameters being given to sylph sketch.
Generate Samplesheet options2
Turn on generation of samplesheets for downstream pipelines.
Specify a comma separated string in quotes to specify which pipeline to generate a samplesheet for.
Generic options5
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).
How many files to unzip in parallel in a single job.
Input File Preprocessing3
Save uncompressed concatenated input FASTAs.
Save automatically unzipped input auxiliary files.
Save uncompressed input FASTAs.
Input Output options13
NCBI-style four-column accession to taxonomy ID map file.
Specify name that resulting databases will be prefixed with.
Email address for completion summary.
Path to NCBI or GTDB genome sizes file.
Path to comma-separated file containing information about the samples in the experiment.
Path to MEGAN6/MALT mapping db file.
Specify the type of MALT mapdb provided, based on the corresponding MALT flag.
MultiQC report title. Printed as page header, used for filename if not otherwise specified.
Path to NCBI-style taxonomy names dmp file.
Path to NCBI-style taxonomy node dmp file.
Two column nucleotide sequence accession ID to taxonomy map file.
The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
Two column protein sequence accession ID to taxonomy map file.
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/createtaxdb/blob/3.1.0/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 createtaxdb 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.
Feeds into
- taxprofiler — 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.
nfclaw chain edges createtaxdb