Inputs and Reference

Inputs and reference

This page describes the files a run consumes and the validation applied before the first task. Parameter defaults and the full table are in Configuration.

Samplesheet

input.samples_tsv is tab-separated. Blank lines and lines starting with # are ignored. Only the first non-comment line is treated as a possible header (sample_id, sample, sampleid or id in the first column); data rows starting with those words are validated as data.

input.format	input.reads_type	Required columns
fastq	pe	sample_id, R1, R2
fastq	se	sample_id, R1
fastq	mx	sample_id, R1, R2, unpaired (Bowtie2 only)
bam	ignored	sample_id, BAM

Sample ids must be unique and match [A-Za-z0-9][A-Za-z0-9_.-]*. Every row must have exactly the expected number of columns. Relative read paths are resolved from the samplesheet directory; every referenced file must exist. Missing read slots for single-end and BAM input are staged as assets/NO_FILE instead of /dev/null.

Read-group values are validated before mapping:

• mapping.platform (PL, default ILLUMINA)
• mapping.library (LB, defaults to the sample id)

Both accept only letters, digits, _, ., : and -.

Reference genome

• The reference FASTA may be plain or bgzip-compressed. Compression is detected from the file header.
• Plain gzip is rejected because samtools and GATK cannot index or read it directly.
• ref_genome.bgzip from 3.x was removed; do not set it.
• Contigs longer than 2,147,483,647 bp (2^31-1) are rejected from the generated .fai, because BAM/BCF positions and GATK use 32-bit coordinates.
• CREATE_FAI_INDEX generates the .fai; CREATE_SEQ_DICT generates the .dict used by GATK and the BAM/reference guard.

Mapper indexes

Indexes are resolved from input.reference_index_dir, selected by mapper-specific suffixes, and staged as task inputs. They are not read from the host path at task runtime, so mapping works in containers, on cloud executors and with scratch.

Mapper	Required index files
bowtie2	complete .1.bt2….rev.2.bt2 set, or the six .bt2l equivalents
bwa	.amb, .ann, .bwt, .pac, .sa
minimap2	.mmi

input.reference_index_prefix sets the prefix. It must be a plain file name without / or \; null uses the file name of reference_genome, including a .gz suffix. The prefix is resolved from reference_index_dir before staging, and staged indexes are flattened under index/.

An incomplete or missing index aborts before the first task and lists the missing files. Selecting an index set is all-or-nothing: a partial bowtie2 set is not accepted.

A Minimap2 index must be built with minimap2 -x sr -d. The k-mer and window settings stored in the .mmi override -x sr at mapping time.

BAM reference check

BAM input and mapping output are checked against the configured reference:

• @SQ names and lengths must match the generated .fai.
• When the BAM header carries M5 checksums, they are compared with the reference sequence dictionary.

A mismatch aborts before calling instead of producing calls at wrong coordinates. A BAM with no M5 entries is checked by names and lengths only.

BED regions

input.include_bed and input.exclude_bed may be unsorted and may contain track, browser and # comment lines; bin/filter_bed.py removes them before sort-bed.

• Every contig must exist in the reference .fai; unknown contigs abort with the BED file and offending names.
• Coordinates must be non-negative and increasing; sort-bed rejects negative or reversed intervals.
• Intervals extending past the contig end are rejected by consensus; they are not clipped. Keep them within the reference contig lengths.
• include_bed restricts coverage and calling to the listed regions.
• exclude_bed is subtracted from the coverage BED after coverage.min_coverage is applied.

Coverage input

GENERATE_COVERAGE runs mosdepth --no-per-base --quantize on the final BAM, keeps runs at or above coverage.min_coverage, intersects them with the sorted include_bed, subtracts the sorted exclude_bed, and merges contiguous runs into coverage.bed. An empty result fails the sample by default; see Operations and troubleshooting for coverage.on_empty: "skip".

Next steps

• Configuration for all parameter defaults.
• Pipeline overview for how inputs flow through the processes.
• Output structure for the published files.