ampliseq
nf-core/ampliseq
Amplicon sequencing analysis workflow using DADA2 and QIIME2
Key tools
Run it
nfclaw run ampliseq --input samplesheet.csv --outdir results -profile dockernextflow run pipelines/ampliseq/upstream -profile docker --input samplesheet.csv --outdir resultsnfclaw run ampliseq --demo --outdir results # adds the upstream test profile (-profile test,docker)Inputs
| column | type | required | allowed values | constraints |
|---|---|---|---|---|
sample | string | yes | matches ^[a-zA-Z][a-zA-Z0-9_]+$ | |
fastq_1 | string (file path) | yes | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q\.gz$ | |
fastq_2 | string (file path) | no | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q\.gz$ | |
run | string or integer | no | matches ^\S+$ | |
control | string | no | control, sample | |
quant_reading | number | no |
--input must match ^\S+\.(tsv|csv|yml|yaml|txt)$.
For tabular CSV/TSV input, use this header (the columns the schema requires); fill each value per the table above and reference.md (no example value is invented here):
sample,fastq_1Any of the optional columns above may be appended to the header when your data needs them: fastq_2, run, control, quant_reading.
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). Optional columns left out take their schema defaults in the pipeline: run = 1 — set them with --sheet-set where your design differs. Set other columns with --sheet-set COLUMN=VALUE. 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 ampliseq --input samplesheet.csv --outdir results -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 = '!>=26.04.0'.
To pin this release's declared minimum engine — useful when a newer Nextflow has incompatible config parsing:
nfclaw run ampliseq ... --nxf-ver 26.04.0--nxf-ver is recorded in <outdir>/provenance/, so the replay uses the same engine. See known-issues.
Demo
nfclaw run ampliseq --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,fastq_1| Column | Type | Required | Allowed / constraints |
|---|---|---|---|
sample | string | required | matches ^[a-zA-Z][a-zA-Z0-9_]+$ |
fastq_1 | string (file path) | required | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q\.gz$ |
fastq_2 | string (file path) | optional | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q\.gz$ |
run | string or integer | optional | matches ^\S+$ |
control | string | optional | controlsample |
quant_reading | number | optional | — |
Required parameters
--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
178 parameters · 17 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.
159 parameters · 19 hidden
Amplicon Sequence Variants Asv Calculation10
Tool for ASV calculation.
DADA2: The penalty score assigned for each gap introduced during sequence alignment.
DADA2: The score assigned for each matching base pair during sequence alignment.
DADA2: The maximum number of mismatches allowed within the overlapping region for merging reads.
DADA2: The minimum number of overlapping base pairs required to merge forward and reverse reads.
DADA2: The penalty score assigned for each mismatched base pair during sequence alignment.
DADA2: The percentile used to determine a stringent cutoff which will correspond to the minimum observed overlap in the dataset. This ensures that only read pairs with high overlap are merged into consensus sequences. Those with insufficient overlap are concatenated.
DADA2: Strategy to merge paired end reads. When paired end reads are not sufficiently overlapping for merging, you can use "concatenate" (not recommended). When you have a mix of overlapping and non overlapping reads use "consensus"
Mode of sample inference: "independent", "pooled" or "pseudo"
Options for Savont ONT analysis
Asv Filtering3
Comma separated list of unwanted taxa, to skip taxa filtering use "none"
Abundance filtering
Prevalence filtering
Asv Post Processing14
Choose whether decontamination with decontam is applied to features.
Choose the decontamination method for --decontam decontaminate.
Choose the contamination likelihood threshold for --decontam decontaminate.
Choose the non-contaminant likelihood threshold for --decontam notcontaminant.
Filter ASVs based on codon usage
Enable SSU filtering. Comma separated list of kingdoms (domains) in Barrnap, a combination (or one) of "bac", "arc", "mito", and "euk". ASVs that have their lowest evalue in that kingdoms are kept.
Maximum ASV length
Minimal ASV length
Ending position of codon tripletts
Starting position of codon tripletts
Raise stack size when filtering VSEARCH clusters
Define stop codons
Post-cluster ASVs with VSEARCH
Pairwise Identity value used when post-clustering ASVs if --vsearch_cluster option is used (default: 0.97).
Comparison6
Path to file of abundances of expected sequences in tsv format
Path to file of abundances of expected taxnonomies in tsv format
Path to file of expected sequences in fasta format
How to handle multiple sequence matches
Threshold of accepted mismatches and gaps to the expected sequences
What region of the sequence comparison is evaluated
Differential Abundance Analysis10
Perform differential abundance analysis with ANCOM
Minimum sample counts to retain a sample for ANCOM analysis. Any sample below that threshold will be removed.
Perform differential abundance analysis with ANCOMBC
Perform differential abundance analysis with ANCOMBC2
Formula to perform differential abundance analysis with ANCOMBC2
Reference level for --ancombc2_formula
Effect size threshold for differential abundance barplot for --ancombc and --ancombc_formula
Formula to perform differential abundance analysis with ANCOMBC
Reference level for --ancombc_formula
Significance threshold for differential abundance barplot for --ancombc and --ancombc_formula
Downstream Analysis7
Minimum rarefaction depth for diversity analysis. Any sample below that threshold will be removed.
Comma separated list of metadata column headers for statistics.
Comma separated list of metadata column headers for plotting average relative abundance barplots.
If the functional potential of the bacterial community is predicted.
Formula for QIIME2 ADONIS metadata feature importance test for beta diversity distances
Maximum taxonomy agglomeration level for taxonomic classifications
Minimum taxonomy agglomeration level for taxonomic classifications
Generic options5
Display the help message.
Display the full detailed help message.
Custom MultiQC yaml file containing HTML including a methods description.
Specifies the random seed.
Display hidden parameters in the help message (only works when --help or --help_full are provided).
Input Output options10
Email address for completion summary.
Path to tab-separated sample sheet
Path to ASV/OTU fasta file
Path to metadata sheet, when missing most downstream analysis are skipped (barplots, PCoA plots, ...).
Path to multi-region definition sheet, for multi-region analysis with Sidle
The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
Forward primer sequence
Reverse primer sequence
The directory where the reference taxonomy databases will be saved for re-use. Absolute paths to storage on Cloud infrastructure.
Save intermediate results such as QIIME2's qza and qzv files
Multiregion Taxonomic Database7
Path to multiple sequence alignment of reference taxonomy sequences in fasta format
Arguments for qiime sidle reconstruct-taxonomy regarding ad-hoc cleaning
Exclude reference sequences with more than this much degenerates
Path to reference taxonomy sequences in fasta format
Path to reference taxonomy strings (headerless, *.txt)
Name of supported database, and optionally also version number
Path to SIDLE reference taxonomy tree (*.qza)
Pipeline Report5
Path to Markdown file (md) that replaces the 'Abstract' section
Path to style file (css)
Path to logo file (png)
Path to Markdown file (Rmd)
String used as report title
Primer Removal5
Sets the maximum error rate for valid matches of primer sequences with reads for cutadapt (-e).
Sets the minimum overlap for valid matches of primer sequences with reads for cutadapt (-O).
Cutadapt will be run twice to ensure removal of potential double primers
Ignore files with too few reads after trimming.
Cutadapt will retain untrimmed reads, choose only if input reads are not expected to contain primer sequences.
Read Trimming And Quality Filtering10
Ignore files with too few reads after quality filtering.
DADA2 read filtering option
DADA2 read filtering option for reverse reads, overriding --max_ee for reverse reads only (paired-end Illumina data only)
DADA2 read filtering option
DADA2 read filtering option
If --trunclenf and --trunclenr are not set, these values will be automatically determined using this median quality score
Assures that values chosen with --trunc_qmin will retain a fraction of reads.
DADA2 read truncation value for forward strand, set this to 0 for no truncation
DADA2 read truncation value for reverse strand, set this to 0 for no truncation
Truncate each read at the first instance of a quality score less than or equal to --truncq.
Running Specific Steps1
Run phylogenetic placement when reference trees are specified by the selected --dada_ref_taxonomy
Sequencing Input7
Comma separated quality bins for DADA2. If data has binned quality scores.
Ignore warnings about binned quality scores.
Ignore input files with too few reads.
If analyzing Illumina paired end reads of an amplicon with large length variability such as ITS
Set read count threshold for failed samples.
Type of quality scores in raw read data for DADA2
Sequencing technology of the data, determines analyze settings and tools.
Skipping Specific Steps20
Skip producing any relative abundance tables
Skip alpha rarefaction
Skip producing barplot
Skip annotating SSU matches.
Skip quality filtering with Chopper (ONT reads).
Skip primer trimming with cutadapt. This is not recommended! Use only in case primer sequences were removed before and the data does not contain any primer sequences.
Skip species level when using DADA2 for taxonomic classification. This reduces the required memory dramatically under certain conditions.
Skip quality check with DADA2. Can only be skipped when --trunclenf and --trunclenr are set.
Skip taxonomic classification with DADA2
Skip alpha and beta diversity analysis
Skip FastQC
Skip MultiQC reporting
Skip writing summary tables as Parquet, alongside the default gzipped tsv
Skip exporting phyloseq rds object(s)
Skip adapter trimming with porechop_ABI (ONT reads).
Skip all steps that are executed by QIIME2, including QIIME2 software download, taxonomy assignment by QIIME2, barplots, relative abundance tables, diversity analysis, differential abundance testing.
Skip steps that are executed by QIIME2 except for taxonomic classification. Skip steps including barplots, relative abundance tables, diversity analysis, differential abundance testing.
Skip Markdown summary report
Skip taxonomic classification.
Skip exporting TreeSummarizedExperiment rds object(s)
Taxonomic Assignment39
If ASVs should be assigned to UNITE species hypotheses (SHs). Only relevant for ITS data.
How to pick one taxonomy per ASV when several databases or classifiers are used
If the expected amplified sequences are extracted from the DADA2 reference taxonomy database
Part of ITS region to use for taxonomy assignment: "full", "its1", or "its2"
If multiple exact matches against different species are returned
ASV fasta will be subset into chunks of this size for classification
Comma separated list of taxonomic levels used in DADA2's assignTaxonomy function
The minimum bootstrap confidence (out of 100 trials) for assigning a taxonomic level with DADA2. Matches minBoot in DADA2's assignTaxonomy method.
Path to a custom DADA2 reference taxonomy database
Path to a custom DADA2 reference taxonomy database for species assignment
Name of supported database(s), and optionally also version number(s) -- comma-separated for multiple databases
If reverse-complement of each sequences will be also tested for classification
Tool for ITS region extraction: "itsx" or "itsxrust".
Cutoff for partial ITS sequences. Only full sequences by default.
Comma separated list of taxonomic levels used in Kraken2. Will overwrite default values.
Confidence score threshold for taxonomic classification.
Path to a custom Kraken2 reference taxonomy database (*.tar.gz|*.tgz archive or folder)
Name of supported database, and optionally also version number
File with reference sequences. Requires also --pplace_tree and --pplace_model.
Method used for alignment, "clustalo", "hmmer" or "mafft"
Phylogenetic model to use in placement, e.g. 'LG+F' or 'GTR+I+F'. Requires also --pplace_tree and --pplace_aln.
Spreadsheet with phylogenetic placement information. Possible columns: target, alignmethod, hmm, extract_hmm, align_hmm, align_extract_hmm, refseqfile, refphylogeny, model, taxonomy.
Tab-separated file with taxonomy assignments of reference sequences.
Newick file with reference phylogenetic tree. Requires also --pplace_aln and --pplace_model.
Path to QIIME2 trained classifier file (typically *-classifier.qza)
Path to files of a custom QIIME2 reference taxonomy database (tarball, or two comma-separated files)
Name of supported database, and optionally also version number
Comma separated list of taxonomic levels used in SINTAX with a custom reference database
Confidence cutoff for SINTAX taxonomic classification.
Path to a custom SINTAX reference database (fasta)
Name of supported database, and optionally also version number
Comma separated list of taxonomic levels for VSEARCH LCA with a custom reference database
VSEARCH usearch_global identity cutoff (--id) used for VSEARCH LCA.
LCA support threshold for VSEARCH LCA (--lca_cutoff).
Maximum number of target sequences to accept per query for VSEARCH LCA (--maxaccepts).
Maximum number of non-matching target sequences to reject per query for VSEARCH LCA (--maxrejects).
Minimum fraction of the query that must align to a target for VSEARCH LCA (--query_cov).
Path to a custom VSEARCH LCA reference database (SINTAX-compatible FASTA)
Name of built-in VSEARCH LCA reference database, and optionally also version number
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. --skip-multiqc true disables that report. 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/ampliseq/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 ampliseq 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
- fetchngs — fetchngs writes an ampliseq samplesheet (sample, fastq_1, fastq_2, run) with --nf-core-pipeline ampliseq. Its run column is empty, so ampliseq treats every sample as one sequencing run and learns one DADA2 error model for all of them; data from several sequencing runs needs run filled per sequencing run: an inline handoff whose set templates it from a column that identifies the run, or your own samplesheet. ampliseq assumes Illumina reads unless told otherwise: for PacBio or Ion Torrent runs (the instrument_platform column) set --pacbio or --iontorrent in the stage's params.
nfclaw chain edges ampliseq