CLI Reference

CLI reference

ChoCallate is configured with a Nextflow params YAML file. Start from assets/templates/config.yaml; it contains every parameter, its default and a comment describing accepted values. There is no separate --help output.

cp assets/templates/config.yaml my_run.yaml
nextflow run main.nf -params-file my_run.yaml

Parameters are validated against nextflow_schema.json before the first task. Unknown keys, invalid enums, values below the accepted minimum, missing input files and invalid samplesheets abort with an actionable error naming the offending key or row.

See also

• Inputs and reference: samplesheet, reference FASTA, mapper indexes, BED files and BAM/reference checks.
• Pipeline overview: processes, data flow and stage labels.
• Consensus model: voting, caller normalization, degraded mode and deletions.
• Output structure: published files, header metadata and FORMAT/INFO fields.
• Operations and troubleshooting: resources, retries and common errors.

Minimal configuration

input:
  samples_tsv: /absolute/path/samples.tsv
  reference_genome: /absolute/path/reference.fa.gz
  reference_index_dir: /absolute/path/indexes

output:
  directory: ChoCallate_output

input.reference_index_dir is required only for input.format: "fastq". A BAM-only run does not need mapper indexes.

Input parameters

Parameter	Default	Allowed values	Notes
input.samples_tsv	null (required)	path	Tab-separated samplesheet. See Inputs and reference.
input.reference_genome	null (required)	path	Plain or bgzip-compressed FASTA.
input.reference_index_dir	null	directory	Required for format: "fastq"; unused for format: "bam".
input.reference_index_prefix	null	file name	Must not contain / or \; defaults to the reference file name.
input.include_bed	null	path	Restrict coverage and calling to these regions.
input.exclude_bed	null	path	Remove these regions from the derived coverage BED.
input.format	"fastq"	"fastq", "bam"	Input molecule type.
input.reads_type	"pe"	"se", "pe", "mx"	"mx" is Bowtie2-only.

Output parameters

Parameter	Default	Allowed values	Notes
output.directory	"ChoCallate_output"	path	Published results. Nextflow reports are configured under this directory in nextflow.config; a params-file override does not move them.
output.type	"single"	"single", "sample"	One merged multi-sample file or one file per sample.
output.format	"bcf"	"bcf", "vcf"	VCF is bgzip-compressed. Internals are always BCF.
output.remove_invariant	false	boolean	false keeps monomorphic/reference sites. true drops them at export.
output.split_multiallelic	false	boolean	Keep one record per ALT instead of re-joining multi-allelic sites.
output.compress_reference_blocks	true	boolean	Collapse runs of hom-reference positions into multi-base gVCF blocks with INFO/END.
output.publish_mode	"copy"	"copy", "link"	copy writes independent files; link points into the work directory and requires it to be retained.

EXPORT_OUTPUT is the only stage that applies output.format and output.split_multiallelic. It also applies output.remove_invariant at export; for per-sample output, consensus skips writing reference records earlier because the export would discard them anyway. GENERATE_CONSENSUS and MERGE_OUTPUTS always write internal BCF.

Resource parameters

Parameter	Default	Notes
resources.max_retries	3	Retries after exit status 137 (out-of-memory) or 140 (walltime).
resources.limits.cpus	64	Hard CPU ceiling per task after retry escalation.
resources.limits.memory_mb	262144	Hard memory ceiling per task (MiB).
resources.limits.time	"7d"	Hard runtime ceiling per task.
resources.low.cpus	1	Index creation, decompression and coverage tasks.
resources.low.memory_mb	4096	Low-label memory.
resources.low.time	"4h"	Low-label runtime.
resources.medium.cpus	6	Mapping, calling, scattering and merging tasks.
resources.medium.memory_mb	16384	Medium-label memory.
resources.medium.time	"24h"	Medium-label runtime.
resources.high.cpus	8	GATK HaplotypeCaller tasks.
resources.high.memory_mb	32768	High-label memory.
resources.high.time	"48h"	High-label runtime.

Memory and time are multiplied by the task attempt number. JVM heaps are derived from the resulting task memory. mapping.cpu, calling.cpu and consensus.cpu override the label CPU defaults. See Operations and troubleshooting for retry and mapping-memory behavior.

Mapping parameters

Parameter	Default	Allowed values	Notes
mapping.mapper	"bowtie2"	"bowtie2", "bwa", "minimap2"	Read mapper.
mapping.extra_args	""	string	Passed verbatim to the mapper.
mapping.cpu	10	integer >= 1	Split between the mapper and concurrent BAM post-processing.
mapping.aligner_reserve_mb	0	integer >= 0	Memory reserved for the aligner index and working set while sort runs. 0 estimates staged index size plus 1 GiB.
mapping.platform	"ILLUMINA"	letters, digits, _, ., :, -	Read-group PL.
mapping.library	null	same pattern	Read-group LB; null uses the sample id.

BAM filtering and duplicate handling

Parameter	Default	Allowed values	Notes
bam_filter.min_map_qual	10	integer >= 0	Alignments below this MAPQ are discarded.
rmdup.mode	"mark"	"none", "mark", "remove"	samtools markdup handling. mark flags duplicates without removing them.
left_align_indels.enabled	true	boolean	Run GATK LeftAlignIndels on the final BAM.

Callers, mosdepth coverage and the consensus pileup skip duplicate-flagged reads, so rmdup.mode: "mark" is sufficient for calling while keeping duplicates available for inspection.

Coverage parameters

Parameter	Default	Allowed values	Notes
coverage.min_coverage	5	integer >= 1	Minimum depth for a base to enter the coverage BED and consensus.
coverage.on_empty	"fail"	"fail", "skip"	Action when no base of a sample reaches the threshold.

With on_empty: "skip", the sample is dropped with a warning and listed in dropped_samples.txt and in the merged SamplesDropped header field.

Calling parameters

Parameter	Default	Allowed values	Notes
calling.callers	"bcftools,gatk,freebayes"	non-empty subset of bcftools, freebayes, gatk	Trimmed and deduplicated. Order matters only for consensus.tie_policy: "first".
calling.cpu	4	integer >= 1	CPUs per calling task.
calling.allow_caller_failure	false	boolean	true continues with surviving callers; false terminates the run.
calling.bcftools.min_snp_qual	20	number >= 0	SNP QUAL threshold.
calling.bcftools.min_indel_qual	20	number >= 0	Indel/other QUAL threshold.
calling.bcftools.call.extra_args	""	string	Passed to bcftools call.
calling.bcftools.mpileup.max_depth	100000	integer >= 1	Overrides the bcftools default of 250.
calling.bcftools.mpileup.max_idepth	100000	integer >= 1	Overrides the bcftools default of 250.
calling.bcftools.mpileup.extra_args	""	string	Passed to bcftools mpileup.
calling.freebayes.min_snp_qual	20	number >= 0	SNP QUAL threshold.
calling.freebayes.min_indel_qual	20	number >= 0	Indel/other QUAL threshold.
calling.freebayes.use_best_n_alleles	4	integer >= 0	0 evaluates all alleles.
calling.freebayes.limit_coverage	100000	integer >= 1	Per-sample coverage cap.
calling.freebayes.extra_args	""	string	Passed to FreeBayes.
calling.gatk.min_snp_qual	20	number >= 0	SNP QUAL threshold.
calling.gatk.min_indel_qual	20	number >= 0	Indel/other QUAL threshold.
calling.gatk.interval_padding	150	integer >= 0	Padding around calling intervals for indels near covered-island edges.
calling.gatk.extra_args	""	string	Passed to GATK HaplotypeCaller.

Every configured caller requires both min_snp_qual and min_indel_qual. Caller records are normalised with bcftools norm -f ref -m -any --atomize; low-QUAL records are kept with FILTER=LowQual and their vote is controlled by consensus.filtered_vote. GATK receives --standard-min-confidence-threshold-for-calling min(min_snp_qual, min_indel_qual). Caller extra_args that request non-diploid ploidy, a copy-number map or custom ploidy regions are rejected because consensus genotypes are diploid.

Caller retries, degraded mode and dropped samples are described in Operations and troubleshooting.

Consensus parameters

Parameter	Default	Allowed values	Notes
consensus.threshold	2	integer >= 1	Minimum number of callers supporting an ALT or the reference.
consensus.cpu	4	integer >= 1	CPUs for consensus, merge and export tasks.
consensus.absent_vote	"ref"	"ref", "abstain"	Vote of a caller without a record. abstain requires at least coverage.min_coverage reads.
consensus.filtered_vote	"abstain"	"abstain", "ref"	Vote of a caller record whose FILTER is not PASS/.
consensus.tie_policy	"nocall"	"nocall", "first"	Zygosity tie-breaker. first uses the earliest configured caller.

The voting model is described in Consensus model.

Cleanup parameter

Parameter	Default	Allowed values	Notes
boost.cleanup	"v2"	"v1", "v2", false	nf-boost work-directory cleanup. false keeps work files so -resume can reuse completed tasks.

With cleanup enabled, deleted files cannot be reused and a resumed run re-executes the affected tasks. Do not combine output.publish_mode: "link" with work-directory cleanup, because linked results depend on the files in the work directory.

Removed or renamed keys

The following 3.x keys are no longer accepted:

• ref_genome.bgzip: compression is detected automatically.
• rmdup.enabled: use rmdup.mode (none, mark or remove).
• calling.min_snp_qual: use calling.<caller>.min_snp_qual and calling.<caller>.min_indel_qual.

Unknown keys abort validation rather than being ignored.