Pipeline Overview

Pipeline overview

ChoCallate is a Nextflow DSL2 pipeline. main.nf validates the run, prepares the reference, maps or prepares BAMs, derives the covered intervals once per sample, runs the selected callers, writes one consensus BCF per sample, and finally merges and exports the requested output.

Data flow

FASTQ -> MAPPING_BOWTIE2 / MAPPING_BWA / MAPPING_MINIMAP2 ─┐
                                                          ├─> BAM + CSI + raw flagstat
BAM   -> PREPARE_BAM ─────────────────────────────────────┘
          │
          ├─> MAPPING_STATS / MAPPING_SUMMARY
          ▼
   GENERATE_COVERAGE (mosdepth + BED filters)
          ▼
   SCATTER_INTERVALS (once per sample)
          ▼
   CALLING_BCFTOOLS / CALLING_FREEBAYES / CALLING_GATK
          ▼
   GENERATE_CONSENSUS (one BCF per sample)
          │
   REPORT_DROPPED_SAMPLES (independent output)
          │
          ├─ output.type = "single": MERGE_OUTPUTS -> EXPORT_OUTPUT
          └─ output.type = "sample": EXPORT_OUTPUT per sample

Stages

Stage	Processes	Label	Main output
Validation and setup	validateParameters, CLIParamsValidation, parse_samplesheet	—	Validated params, samplesheet and reference/index paths
Reference preparation	DECOMPRESS_ASSEMBLY (BGZF only), CREATE_FAI_INDEX, CREATE_SEQ_DICT	process_low	ref_genome.fasta, .fai, .dict
Mapping	MAPPING_BOWTIE2, MAPPING_BWA, MAPPING_MINIMAP2	process_medium	mapping.bam, mapping.bam.csi, mapping.raw.flagstat
BAM preparation	PREPARE_BAM	process_medium	mapping.bam, CSI, raw flagstat
Mapping statistics	MAPPING_STATS, MAPPING_SUMMARY	process_low	mapping_stats/*
Coverage	GENERATE_COVERAGE	process_low	coverage.bed
Interval scattering	SCATTER_INTERVALS	process_medium	shared BED chunks
Calling	CALLING_BCFTOOLS, CALLING_FREEBAYES, CALLING_GATK	process_medium / process_high	one BCF per caller and sample
Consensus	GENERATE_CONSENSUS	process_medium	<sample>.bcf
Dropped samples	REPORT_DROPPED_SAMPLES	process_low	dropped_samples.txt
Merge	MERGE_OUTPUTS	process_medium	internal consensus.bcf
Export	EXPORT_OUTPUT	process_medium	final BCF or VCF

Major branches

• input.format: "bam" skips mapping and starts at PREPARE_BAM.
• mapping.mapper selects one mapper; exactly one mapping process runs for FASTQ input.
• calling.callers selects any non-empty subset of bcftools, FreeBayes and GATK.
• coverage.on_empty: "skip" removes samples with an empty coverage BED before scattering; "fail" aborts.
• output.type: "single" runs MERGE_OUTPUTS and then one EXPORT_OUTPUT; "sample" exports every per-sample BCF independently.
• Per-sample output with output.remove_invariant: true writes variants only during consensus because the export would discard reference records anyway.

Shared conventions

• Every process declares process_low, process_medium or process_high and receives resources from the resources section.
• Processes that use temporary files export a process-local $TMPDIR. Processes with staged inputs run bin/stage_cleanup.sh after the task; cleanup removes staged inputs and temporary files only after success.
• Process scripts run under bash -euo pipefail.
• Mapper indexes, caller BCFs and BED inputs are staged as task inputs rather than read from host paths at task runtime.
• Caller identity is carried through staged file names (tmp/callers/<caller>.bcf), so a missing caller does not shift positional inputs.

Code map

Path	Purpose
main.nf	Workflow wiring, validation entry points, branch selection
modules/local/*	One Nextflow process per stage
bin/	Python and shell helpers used by processes and tests
lib/CLIParamsValidation.groovy	Schema-adjacent validation, samplesheet parsing, index resolution, ulimit check
lib/ResourceUtils.groovy	JVM heap options derived from task memory
conf/base.config	Process labels, resource limits, retry policy and stage CPU precedence
assets/templates/config.yaml	Documented configuration template
tests/	pytest and nf-test suites

See Developer guide for the repository layout and conventions in detail.