dada2-nf

Filters, trims, and denoises NGS short reads using dada2. Additional features:

• optionally removes adapters with cutadapt
• filters indexed reads with barcodecop
• generates quality plots for forward and reverse reads
• learns DADA2 error models, denoises reads, merges paired reads, and removes chimeras
• filters off-target reads using cmsearch with covariance models or vsearch with reference libraries
• supports 16S and ITS configurations
• supports dual-index, single-index, and no-index inputs
• can process both forward and reverse orientations when bidirectional output is enabled
• writes sequence variant FASTA files, specimen maps, SV tables, weights, and count/yield summaries
• supports Docker, Singularity, and local execution

Configuration

Pipeline inputs are specified via a params file. Example using test/minimal/params.json:

{
  "sample_information": "test/minimal/sample-information.csv",
  "fastq_list": "test/minimal/fastq-list.txt",
  "manifest": "",
  "output": "output-minimal",
  "index_file_type": "dual",
  "dada_params": "data/dada_params_300.json",
  "bidirectional": false,
  "alignment": {
    "library": "",
    "model": "data/SSU_rRNA_bacteria.cm",
    "strategy": "cmsearch"
  }
}

Key parameters:

Parameter	Description
sample_information	CSV file mapping samples to index sequences
fastq_list	Text file listing FASTQ input paths
index_file_type	One of dual, single, or none
dada_params	data/dada_params_250.json (250 bp reads) or data/dada_params_300.json (300 bp reads)
alignment.strategy	cmsearch for 16S, vsearch for ITS or custom libraries
nproc	Number of CPUs (default: 8)

See test/ for additional input file examples and template.json for the full parameter schema.

The version of dada2 used in this project can be determined with:

docker run --rm ghcr.io/nhoffman/dada2-nf:latest R -q -e 'packageVersion("dada2")'

Execution

Install the Nextflow binary in this directory:

wget -qO- https://get.nextflow.io | bash

Three profiles are available. All profiles resume from previous runs by default (resume = true). Local profiles use all available CPUs by default — see below for details.

standard (default) — runs with Singularity, caches images in singularity/:

./nextflow run main.nf -params-file test/minimal/params.json

docker — runs with Docker:

./nextflow run main.nf -params-file test/minimal/params.json -profile docker

local — runs without a container engine:

./nextflow run main.nf -params-file test/minimal/params.json -profile local

Common overrides:

./nextflow run main.nf \
  -params-file test/minimal/params.json \
  -profile docker \
  --container dada2-nf:local \
  --work_dir work-test \
  --nproc 4

By default, local profiles use all available CPUs on the machine (--cpus 0, the default). CPU-intensive processes (high_cpu label) each consume nproc CPUs, so concurrency scales automatically — e.g. on a 144-core machine with --nproc 8, up to 18 high_cpu tasks run simultaneously.

To limit the total CPUs used, pass --cpus:

./nextflow run main.nf -params-file params.json --cpus 32

Testing

Run all tests:

./test/run_tests.sh

Run selected tests by name:

./test/run_tests.sh minimal single/vsearch

Available tests:

Test	Description
minimal	Dual-index, cmsearch 16S filtering
single/cmsearch	Single-index, cmsearch 16S filtering
single/vsearch	Single-index, vsearch filtering
single/ngs16s	Single-index, NGS16S filtering
noindex	No-index input
its	ITS configuration

Each test runs the pipeline against a test/**/params.json file and verifies top-level output files against test/**/base-files.sha256.

Pass additional Nextflow arguments after --. This is how GitHub Actions runs tests against the freshly built Docker image:

./test/run_tests.sh -- -profile docker --container gha_image

Infernal 16S filtering

The covariance model used for Infernal sequence filtering is obtained from the Rfam database:

• Model: https://rfam.xfam.org/family/RF00177
• Citation: https://rfam.xfam.org/

Docker image

The Docker image is hosted in the GitHub container registry: https://github.com/nhoffman/dada2-nf/pkgs/container/dada2-nf

Singularity can transparently ingest the Docker image and create a locally-cached copy.

Releasing

1. Update CHANGES.md with a new version section summarizing changes since the last release.
2. Commit and push to master.
3. Tag the release:

git tag 2.0.6
git push origin 2.0.6

Pushing a tag triggers the CI workflow, which builds and pushes a Docker image tagged with the version number (e.g., ghcr.io/nhoffman/dada2-nf:2.0.6).

4. After the Docker image CI tag workflow completes create a GitHub Release from the tag (Releases → Draft a new release → choose the tag → Publish). Publishing the release triggers the tag_latest job, which retags the versioned image as ghcr.io/nhoffman/dada2-nf:latest. Since nextflow.config points to :latest, all users pulling the pipeline get the new image automatically.

The manifest.version in nextflow.config is set via git describe --tags --dirty at runtime, so it always reflects the current tag without manual updates.