raredisease
nf-core/raredisease
call and score variants from WGS/WES of rare disease patients
Key tools
Run it
nfclaw run raredisease --input samplesheet.csv --outdir results --fasta <fasta> --intervals-wgs <intervals_wgs> --intervals-y <intervals_y> -profile dockernextflow run pipelines/raredisease/upstream -profile docker --input samplesheet.csv --outdir results --fasta <fasta> --intervals_wgs <intervals_wgs> --intervals_y <intervals_y>nfclaw run raredisease --demo --outdir results # adds the upstream test profile (-profile test,docker)Inputs
| column | type | required | allowed values | constraints |
|---|---|---|---|---|
sample | string | yes | matches ^\S+$ | |
lane | integer or string | no | ||
fastq_1 | string (file path) | no | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q\.gz$ | |
fastq_2 | string (file path) | no | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q\.gz$ | |
spring_1 | string (file path) | no | matches ^\S+.spring$ | |
spring_2 | string (file path) | no | matches ^\S+.spring$ | |
bam | string (file path) | no | matches ^\S+\.bam$ | |
bai | string (file path) | no | matches ^\S+\.bai$ | |
sex | integer or string | yes | ||
phenotype | integer | yes | 0, 1, 2 | |
paternal_id | string | no | ||
maternal_id | string | no | ||
case_id | string | yes | matches ^\S+$ |
--input must match ^\S+\.(csv|tsv|json|yaml|yml)$.
Additional row validation rules from the schema:
- When
fastq_2is set, also providefastq_1. - When
spring_2is set, also providespring_1. - When
bamis set, also providebai. - At least one of these conditional requirements must be satisfied:
fastq_1whenlaneis set;spring_1whenlaneis set.
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,sex,phenotype,case_idAny of the optional columns above may be appended to the header when your data needs them: lane, fastq_1, fastq_2, spring_1, spring_2, bam, bai, paternal_id, maternal_id.
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); lane from Illumina lane numbers (_L002 → 2, else 1); bam, bai from files matching their patterns, by sample name. Optional columns left out take their schema defaults in the pipeline: paternal_id = 0, maternal_id = 0 — set them with --sheet-set where your design differs. Set the required columns no file determines with --sheet-set COLUMN=VALUE (a constant or a {sample}/{lane} template): sex (integer or string); phenotype (one of 0, 1, 2); case_id (matching ^\S+$). Preview it with --check; a run records it in <outdir>/provenance/ for replay.
Reference genome
This release resolves a reference genome remotely by default. --genome defaults to GRCh38; the schema declares AWS iGenomes at s3://ngi-igenomes/igenomes/. The pinned configuration gives that key the FASTA ${params.igenomes_base}/Homo_sapiens/NCBI/GRCh38/Sequence/WholeGenomeFasta/genome.fa. Resolving references through that default needs access to this source. For a self-contained run, pass your own reference instead (e.g. --fasta; the reference_file_options group in reference.md lists every reference option). Set --igenomes-ignore true to disable the lookup entirely. Confirm the selected reference's paths and source in the pinned upstream/nextflow.config and upstream/conf/ before running.
Secrets
This release reads Nextflow secrets: SENTIEON_AUTH_MECH_BASE64 (in conf/test_sentieon.config); SENTIEON_AUTH_DATA_BASE64 (in conf/test_sentieon.config); SENTIEON_LICENSE_BASE64 (in modules/nf-core/sentieon/bwaindex/main.nf, modules/nf-core/sentieon/bwamem/main.nf and 6 more files). Set each one a run needs with nextflow secrets set NAME VALUE before launching; a secret that is not set reaches its tasks as an empty value (Nextflow warns that the variable evaluates to an empty value), and a task that needs it then fails. Secrets are not written to nfclaw's provenance.
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 raredisease --input samplesheet.csv --outdir results --fasta <fasta> --intervals-wgs <intervals_wgs> --intervals-y <intervals_y> -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 = '!>=25.10.4'.
To pin this release's declared minimum engine — useful when a newer Nextflow has incompatible config parsing:
nfclaw run raredisease ... --nxf-ver 25.10.4--nxf-ver is recorded in <outdir>/provenance/, so the replay uses the same engine. See known-issues.
Demo
nfclaw run raredisease --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,sex,phenotype,case_id| Column | Type | Required | Allowed / constraints |
|---|---|---|---|
sample | string | required | matches ^\S+$ |
lane | integer or string | optional | — |
fastq_1 | string (file path) | optional | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q\.gz$ |
fastq_2 | string (file path) | optional | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q\.gz$ |
spring_1 | string (file path) | optional | matches ^\S+.spring$ |
spring_2 | string (file path) | optional | matches ^\S+.spring$ |
bam | string (file path) | optional | matches ^\S+\.bam$ |
bai | string (file path) | optional | matches ^\S+\.bai$ |
sex | integer or string | required | — |
phenotype | integer | required | 012 |
paternal_id | string | optional | — |
maternal_id | string | optional | — |
case_id | string | required | matches ^\S+$ |
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.
--fastastring (file path)Path to FASTA genome file.
Constraint · matches ^\S+\.fn?a(sta)?(\.gz)?$
--intervals-wgsstring (file or directory path)Path to the interval list of the genome (autosomes, sex chromosomes, and mitochondria).
Constraint · matches ^\S+\.intervals?(_list)?$
--intervals-ystring (file or directory path)Path to the interval list of the Y chromosome.
Constraint · matches ^\S+\.intervals?(_list)?$
Parameter explorer
150 parameters · 9 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.
123 parameters · 27 hidden
Alignment options10
Specifies the alignment algorithm to use - available options are 'bwamem2', 'bwa', 'bwameme' and 'sentieon'.
Memory allocated for mbuffer in megabytes (MB) (used by bwameme and bwafastalign)
Discard trimmed reads shorter than the given value
Specifies the alignment algorithm to use - available options are 'bwamem2', 'bwa' and 'sentieon'.
Subsample mitochondria based on fraction of reads or number of reads
Expected coverage to subsample mt alignment to, when mt_subsample_approach is set to fraction
Expected number of reads to subsample mitochondria to, when mt_subsample_approach is set to reads
Subsampling seed used to influence which subset of mitochondrial reads is kept. Used when mt_subsample_approach is set to fraction
Specifies whether duplicates reads should be removed prior to variant calling.
Number of threads allocated for sorting alignment files (used by bwameme and bwafastalign)
Analysis options17
Specifies which analysis type for the pipeline- either 'wgs', 'wes' or 'mito'. This changes resources consumed and tools used.
Specifies whether to generate a concatenated VCF file containing both nuclear & mitochondrial snv calls
After aligning the reads to a reference, remove alignments to alt contigs using samtools view, retaining only primary chromosomes (GRCh37: 1-22,X,Y,MT / GRCh38: chr1-chr22,chrX,chrY,chrM).
After aligning the reads to a reference, extract alignments from specific regions/contigs and restrict the analysis to those regions/contigs.
Allele frequency threshold for mitochondrial variants. Variants with an AF above this threshold will be treated as homoplasmic and assigned a 1/1 genotype. Range 0-1.0.
Method selection for ngs-bits samplegender
Specifies the platform on which the reads were sequenced.
Can be specified as RNAME[:STARTPOS[-ENDPOS]]. Multiple regions should be seperated by space
Specifies whether to run mitochondrial analysis for wes samples
Specifies whether to run rtgtools' vcfeval
Specifies whether to check vcfanno database files for zero records and remove the corresponding annotation blocks from the TOML config before running vcfanno
Specifies whether to generate and publish all (unfiltered) alignment files as cram instead of bam
Specifies whether to generate and publish alt-filtered alignment files as cram instead of bam. Requires exclude_alt to be set to true.
Number of intervals to split your genome into (used to parallelize annotations)
Skip the split multiallelics step in SNV calling.
Disable specified subworkflows.
Disable specified tools.
Annotation options3
File containing list of SO terms listed in the order of severity from most severe to lease severe for annotating genomic and mitochondrial SNVs.
File containing list of SO terms listed in the order of severity from most severe to lease severe for annotating genomic SVs.
Specify the version of the VEP cache provided to the --vep_cache option.
Generic options4
Display the help message.
Display the full detailed help message.
Path to a file containing internal ids and alternative ids in tab separated format. Will replace the internal id with the alternative id in the report. For more info check, docs.seqera.io/multiqc/reports/customisation#sample-name-replacement
Display hidden parameters in the help message (only works when --help or --help_full are provided).
Input Output options2
Path to the samplesheet file containing information about the samples in the experiment.
The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
Mitosalt options27
end of heavy strand origin
start of heavy strand origin
Minimum memory required to build HISAT2 index with splice sites and exons. If available memory is below this threshold, a simpler index is built without splice sites.
end of light strand origin
start of light strand origin
length of mitochondrial genome
minimum number of bases a non-split read must span either side of a breakpoint to be considered in the heteroplasmy count
the maximum deviation a given set of split read breakpoints can have to be considered within the same cluster
minimum number of reads supporting a cluster
the maximum size of the gap between fragments of a split read for the split read to be considered as potentially spanning a deletion
the minimum size of the gap between fragments of a split read for the split read to be considered as potentially spanning a deletion
depth to subsample fastq files to before running mitosalt
alignment e-value cutoff
filter split reads if both fragments fall within the regions at the start and end to avoid pseudo-gapped alignments due to a circular genome
basepairs flanking a deletion
detected heteroplasmy threshold
the maximum distance of a paired read from its split counterpart for paired support to be considered positive
alignment score cutoff
maximum size of deletions tolerated, beyond which they are reclassified as potential duplications in the reverse orientation
the maximum length of unmapped distance between two fragments of a split read
minimum number of bases in a split read fragment for the read to be considered as potentially spanning a deletion
fraction for dominant fraction for saltshaker classification
spatial clustering radius for saltshaker grouping
high heteroplasmy threshold for saltshaker classification
threshold for multiple saltshaker classification
heteroplasmy threshold for background noise
Reference File options55
The amount to pad each end of the target intervals to create bait intervals.
Directory for pre-built bwa index.
Directory for pre-built bwa-fastalign index.
Directory for pre-built bwamem2 index.
Directory for pre-built bwameme's learned index.
Path to the directory containing pre-scored CADD indel annotations.
Path to the directory containing cadd annotations.
Path to FASTA genome index file.
Path to FASTA genome file.
A file containing the path to models produced by GATK4 GermlineCNVCaller cohort.
Name of iGenomes reference.
Path to the gnomad tab file with allele frequencies.
Path to the index file for the gnomad tab file with allele frequencies.
Do not load the iGenomes reference config.
Path to the interval list of the genome (autosomes, sex chromosomes, and mitochondria).
Path to the interval list of the Y chromosome.
Path to known dbSNP file.
Path to known dbSNP file index.
Local directory base for genome references that map to the config.
Path to a bgzipped BED file restricting Manta SV calling to specific regions (e.g. primary chromosomes). Only applied for WGS; for WES, Manta always uses target_bed instead.
Tabix index for the file supplied via --manta_call_regions.
Name of the mitochondrial contig in the reference fasta file
Path to sentieon machine learning model file.
File with mobile element references
File with mobile element allele frequency references
Path to mitochondrial FASTA genome file.
Path to a BED file containing PAR regions (used by deepvariant).
Directory containing the ploidy model files
Interval list file containing the intervals over which read counts are tabulated for CNV calling
File with gene ids that have reduced penetrance. For use with genmod
Vcf used for evaluating variant calls.
A BED file with regions of interest used in sambamba depth.
Path to a file containing internal ids and customer ids in csv format.
If generated by the pipeline save the required indices/references in the results directory.
MT rank model config file for genmod.
SNV rank model config file for genmod.
SV rank model config file for genmod.
Directory for pre-built sdf index. Used by rtg/vcfeval
Path to the genome dictionary file
Databases used for structural variant annotation in chrA-posA-chrB-posB-type-count-frequency format.
Databases used for structural variant annotation in vcf format.
Path to directory for target bed file.
Path to variant catalog file
Path to vcf2cytosure blacklist file
Path to a VCF file containing annotations.
Path to the vcfanno lua file.
Path to a file containing the absolute paths to resources defined within the vcfanno toml file. One line per resource.
Path to the vcfanno toml file.
Path to vep's cache directory.
Path to the file containing HGNC_IDs of interest on separate lines.
Path to a bed-like file exported by scout, which contains HGNC_IDs to be used in filter_vep.
Databases used by both named and custom plugins to annotate variants.
Path to a BED file containing markers used by verifybamid2.
Path to mean matrix file of genotype matrix. Used by verifybamid2.
Path to UD matrix file from SVD result of genotype matrix. Used by verifybamid2.
Variant Calling options5
Interval in the reference that will be used in the software. Used only by sentieon.
Bin size for CNVnator
Option for selecting the PCR indel model used by Sentieon Dnascope.
Specifies the variant caller to use - available options are 'deepvariant' and 'sentieon'.
Specifies the variant types for sentieon variant caller.
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. 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/raredisease/blob/3.1.2/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.