The raredisease template follows an nf-core/raredisease run on a family, usually a trio, from the alignment to the ranked variants:
- Overview: the run in four key figures, live findings and a leaderboard of the best-ranked variants, each linked to the tab that explains it
- Data & QC: the MultiQC report, the alignment and coverage numbers per sample, and whether the samples are the family the pedigree says
- Variants: the callset per sample, the GENMOD-ranked variants with their inheritance models, and the optional mitochondrial and repeat branches
- Locus: the ranked variants on the genome, with a browser on the calls and alignments
A pick on a sample, a role (proband, father, mother, sibling) or a family in the left panel narrows every per-sample collection, the MultiQC report and the genome browser's tracks.
Roles come from the pedigree
The pipeline publishes its pedigree as a .ped file, so the group the filters
use is the role, read from it, and the affected status colours the
pedigree figure. A run without the pedigree keys the sample hub on the QC and
callset samples, and every role reads Other.
Quick start¶
The results directory is the only required value. The run's reference decides the one variable you may need to set:
depictio ingest /path/to/raredisease_results \
--template nf-core/raredisease/latest \
--var GENOME=hg38
| Variable | Default | Role |
|---|---|---|
GENOME |
hg19 |
assembly of the navigator, the karyotype and the browser's tracks: hg19 is the GRCh37 naming, hg38 that of GRCh38 |
TRACKS_URI |
unset | s3:// or https:// folder holding the run's results: the browser reads the alignments and signal tracks in place instead of uploading them from DATA_ROOT |
depictio config nextflow --install # once per machine
nextflow run nf-core/raredisease -r 3.1.2 -profile docker --outdir results
No depictio ingest, and no template named: the pipeline ingests its own
output directory when it finishes and resolves this template from its own
manifest. See Nextflow trigger. The
trigger passes no --var, so a GRCh38 run reads on the hg19 axis; ingest it
by hand with GENOME=hg38 instead.
Reference¶
The template reads the pedigree, the Picard and mosdepth QC, the family callset, the VEP-annotated and GENMOD-ranked VCFs (the clinical set is a subset of the research set and is flagged, so no variant is counted twice), the optional mitochondrial, repeat expansion, mobile element and SMN outputs, the MultiQC report and the run parameters. The alignments, the ranked and repeat VCFs and the signal tracks are never loaded as tables: the genome browser opens them through their indexes. peddy, GENS, the germline CNV caller and structural variant calling are not read.
The callset summary, the substitution spectrum and the FILTER breakdown count the calls a sample carries (a genotype with an alternate allele), not the sites of the joint file. A target capture (exome) run fills the hybrid-selection coverage columns instead of the whole-genome ones, and the tiles that read the latter draw a dash.
Self-adapting layout
The dashboard adapts to whatever the run actually produced: components bound to pruned or unparsed data collections are hidden, tabs left with no real visualizations are dropped entirely, and the remaining components are re-packed so there are no empty rows. A run that skipped the mitochondrial branch loses the Mitochondria tab, one without repeat expansion or mobile element calling loses their cards and tables.
Template variables¶
Variables you provide when running the template: DATA_ROOT is the results directory given to depictio ingest, the others are set with --var NAME=value:
| Variable | Required | Description |
|---|---|---|
DATA_ROOT |
✓ | Root directory of one raredisease run (alignment/, call_snv/, rank_and_filter/, qc_bam/, pedigree/, pipeline_info/). |
GENOME |
— | UCSC name of the assembly the run was aligned to (hg19 for GRCh37, hg38 for GRCh38): the axis of the Locus tab and the gene track of the browser. |
TRACKS_URI |
— | s3:// or https:// folder holding the run's results (the one that holds alignment/, rank_and_filter/ and qc_bam/), to read the genome-browser tracks (the ranked VCFs and the alignments) in place instead of uploading them from DATA_ROOT. Without it the tracks collection uploads whichever of those files DATA_ROOT holds. |
Data collections¶
17 data collections — 12 required 5 optional · 11 direct 6 derived.
Origin tells you whether a collection is real pipeline data or a reshape of it: direct = a pipeline output (scanned, or a recipe that reads raw files); derived = a recipe that reshapes one or more direct collections into the layout a visualization needs (no new measurement). Reads shows what produces it: a recipe .py transform, or a raw file scanned off disk. (A direct collection can still have a recipe — one that merely parses/cleans the raw file; derived means the recipe reshapes another collection.)
| Tag | Origin | Type | Reads | Status |
|---|---|---|---|---|
multiqc_data |
direct |  MultiQC |
file |
required |
alignment_qc |
direct | Table | recipe |
required |
contig_depth |
direct | Table | recipe |
required |
vcf_variants |
direct | Table | recipe |
required |
vcf_callset_summary |
derived | Table | recipe |
required |
vcf_substitution_spectrum |
derived | Table | recipe |
required |
vcf_filter_breakdown |
derived | Table | recipe |
required |
vcf_variant_density |
derived | Table | recipe |
required |
ranked_variants |
direct | Table | recipe |
required |
ranked_genotypes |
derived | Table | recipe |
required |
family_checks |
direct | Table | recipe |
required |
mt_variants |
direct | Table | recipe |
optional |
repeat_expansions |
direct | Table | recipe |
optional |
mobile_elements |
direct | Table | recipe |
optional |
smn |
direct | Table | recipe |
optional |
tracks |
direct | genomic_tracks | recipe |
optional |
samples |
derived | Table | recipe |
required |
Conditional routes¶
Rows are data collections; columns are the variables you set or params.json flags auto-detected from the run. Each filled cell is the effect of setting that variable; an empty cell means that variable leaves the collection unchanged. (16 collections are unaffected by any variable — present on every run.)
+ included− removed⇄ repointed
| Data collection | TRACKS_URI |
|---|---|
tracks |
⇄ |
Cross-DC links¶
24 links — selecting a value in the source collection filters the target. The join column is shown after the source.
| Source · column | Target | Filters | |
|---|---|---|---|
samples · sample |
→ | multiqc_data |
Filter every MultiQC panel by the samples picked in the left panel |
samples · sample |
→ | alignment_qc |
Filter the alignment QC by the samples picked in the left panel |
samples · sample |
→ | contig_depth |
Filter the depth per contig by the samples picked in the left panel |
samples · sample |
→ | vcf_variants |
Filter the calls by the samples picked in the left panel |
samples · sample |
→ | vcf_callset_summary |
Filter the callset summary by the samples picked in the left panel |
samples · sample |
→ | vcf_substitution_spectrum |
Filter the substitution spectrum by the samples picked in the left panel |
samples · sample |
→ | vcf_filter_breakdown |
Filter the FILTER breakdown by the samples picked in the left panel |
samples · sample |
→ | vcf_variant_density |
Filter the variant karyotype by the samples picked in the left panel |
samples · sample |
→ | ranked_genotypes |
Filter the ranked genotypes by the samples picked in the left panel |
samples · sample |
→ | family_checks |
Filter the family checks by the samples picked in the left panel |
samples · sample |
→ | mt_variants |
Filter the mitochondrial variants by the samples picked in the left panel |
samples · sample |
→ | repeat_expansions |
Filter the repeat expansions by the samples picked in the left panel |
samples · sample |
→ | mobile_elements |
Filter the mobile element insertions by the samples picked in the left panel |
samples · sample |
→ | smn |
Filter the SMN copy numbers by the samples picked in the left panel |
ranked_genotypes · variant_key |
→ | ranked_variants |
Narrow the ranked variants to the ones the picked samples carry |
ranked_variants · variant_key |
→ | ranked_genotypes |
Narrow the carrying genotypes by the filters picked on the Ranked tab |
vcf_filter_breakdown · filter_label |
→ | vcf_variants |
Carry the FILTER value picked on the Callset tab over to the calls |
ranked_variants · chrom |
→ | vcf_variants |
A region typed or brushed on the navigator narrows the calls and the region cards |
ranked_variants · chrom |
→ | repeat_expansions |
A region typed or brushed on the navigator narrows the repeat loci |
ranked_variants · chrom |
→ | mobile_elements |
A region typed or brushed on the navigator narrows the mobile element insertions |
vcf_variant_density · chrom |
→ | vcf_variants |
A region brushed on the karyotype narrows the calls |
vcf_variant_density · chrom |
→ | ranked_variants |
A region brushed on the karyotype narrows the ranked variants |
samples · family_id |
→ | tracks |
Show the genome tracks of the families picked |
tracks · sample |
→ | samples |
Narrow the sample hub to the samples picked in the genome browser |
Recipes¶
Each recipe reshapes raw pipeline output into a tidy table. The name links to its source; Output lists the validated OUTPUT_SCHEMA columns.
| Recipe | Transforms | Output |
|---|---|---|
nf-core/raredisease/alignment_qc.py |
nf-core/raredisease alignment QC, one row per sample, from the Picard and mosdepth reports. | sample, total_reads, aligned_pct, mismatch_rate_pct, mean_read_length, chimera_pct, softclip_pct, duplication_pct, median_insert, mean_insert, insert_sd, mean_coverage, median_coverage, bases_1x_pct, bases_10x_pct, bases_20x_pct, bases_30x_pct, excluded_pct, nuclear_depth, mito_depth, mito_to_nuclear, hs_fold_enrichment, hs_mean_target_coverage, hs_target_20x_pct |
nf-core/raredisease/contig_depth.py |
nf-core/raredisease mean depth per contig and sample, from the mosdepth summary. | sample, contig, contig_class, class_order, length, bases, mean_depth, min_depth, max_depth, relative_depth |
nf-core/raredisease/family_checks.py |
nf-core/raredisease family checks: one row per ordered pair of samples of a family. | sample, partner, relation, shared_sites, ibs0, ibs0_pct, identical_pct, relatedness, check_status |
nf-core/raredisease/mobile_elements.py |
nf-core/raredisease mobile element insertions: one row per insertion and carrying sample. | variant_key, chrom, pos, end, me_type, sample, gt, qual, gq, flag, spanning_pairs, clipped_5p, clipped_3p, filter_status, samples_sharing |
nf-core/raredisease/mt_variants.py |
nf-core/raredisease mitochondrial variants: one row per variant and sample with a call. | variant_key, sample, chrom, pos, end, ref, alt, variant_type, filter_status, gt, heteroplasmy, heteroplasmy_class, dp, alt_depth, gene, consequence, impact, rank_score, model_class, mitotip_score, mitotip_prediction, gnomad_mt_het, gnomad_mt_hom, is_clinical, call_label |
nf-core/raredisease/ranked_genotypes.py |
nf-core/raredisease ranked genotypes: one row per ranked variant and carrying sample. | variant_key, sample, gt, gt_class, dp, gq, vaf, gene, call_label, rank_score, model_class, de_novo, impact, is_clinical |
nf-core/raredisease/ranked_variants.py |
nf-core/raredisease ranked small variants: one row per variant, from the GENMOD-ranked VCFs. | variant_key, chrom, pos, end, ref, alt, variant_type, variant_set, is_clinical, qual, filter_status, rank_score, rank_score_norm, rank_score_min, rank_score_max, genetic_models, model_class, de_novo, gene, genes, consequence, impact, hgvs_c, hgvs_p, sift, polyphen, pli, cadd, gnomad_af, gnomad_af_popmax, score_allele_frequency, score_protein, score_gene_intolerance, score_inheritance, score_consequence, score_conservation, score_call_quality, score_deleteriousness, score_clinical, score_splicing, n_carriers, carriers, calls, genotypes, call_label |
nf-core/raredisease/repeat_expansions.py |
nf-core/raredisease repeat expansions: one row per catalog locus and sample. | variant_key, locus, chrom, start, end, repeat_unit, disease, inheritance, sample, gt, repeat_count, repeat_counts, spanning_reads, locus_coverage, filter_status, str_status, normal_max, pathologic_min, repeat_status, rank_score, pop_mean, pop_sd |
nf-core/raredisease/samples.py |
nf-core/raredisease sample hub: one row per sample, from the pedigree to the ranked calls. | sample, family_id, father, mother, role, status, sex, inferred_sex, sex_check, total_reads, aligned_pct, mismatch_rate_pct, duplication_pct, median_insert, mean_coverage, bases_10x_pct, bases_20x_pct, mito_depth, pass_calls, snvs, indels, ts_tv, het_hom_ratio, median_dp, ranked_carried, clinical_carried, de_novo_carried, high_impact_carried, parent_check |
nf-core/raredisease/smn.py |
nf-core/raredisease SMN copy numbers: one row per sample, from SMNCopyNumberCaller. | sample, smn_status, smn1_cn, smn2_cn, smn2_delta78_cn, total_cn_raw, full_length_cn_raw |
nf-core/raredisease/substitution_spectrum.py |
Substitution spectrum per sample, with the sample's role in the family. | sample, caller, callset, substitution_class, mutation_class, count, fraction, role |
nf-core/raredisease/tracks.py |
Genome-browser track manifest: one row per track file the run published. | track_id, sample, family_id, format, uri, name, category, order |
nf-core/raredisease/variants.py |
nf-core/raredisease small-variant calls: one row per carried call, from the family callset. | sample, caller, chrom, pos, variant_key, ref, alt, variant_type, qual, filter_status, is_pass, gt, dp, vaf |
vcf/callset_summary.py |
One row per callset (sample and caller): what a germline callset is judged on. | sample, caller, calls, pass_calls, pass_pct, snvs, indels, mnps, multiallelic, transitions, transversions, ts_tv, het, hom_alt, het_hom_ratio, median_qual, median_dp, median_het_vaf |
vcf/filter_breakdown.py |
How each caller's own FILTER column partitions its calls, per callset. | sample, caller, filter_label, is_pass, failed_filters, calls, calls_pct, snvs, indels |
vcf/variant_density.py |
PASS variant density along the genome: calls per fixed window, per sample. | chrom, start, end, value, sample |
Dashboard tabs¶
One dashboard: the Overview, then eight child tabs in two groups, read as a funnel from the reads to what the calls and alignments show at one locus. Each tab below carries the same icon and colour the dashboard gives it, so the page and the app read alike.
| Group | Tabs |
|---|---|
| Data & QC | MultiQC, Alignment, Family |
| Variants | Callset, Ranked, Mitochondria, Repeats, Locus |
Each child tab opens with a short intro and a strip of four cards, then at most three open sections; tables follow, collapsed.
Rare disease analysis of a family, from the alignment to the ranked variants.
Hero, About and run cards (genome, analysis type, aligner, caller, VEP cache, skipped tools) and six steps (Align, Call, Rank, Mitochondria, Repeats, Report), each with its settings and its tab. Four key figures: the clinical variants by inheritance model, the top rank score, the samples by role and the mean coverage. The findings are led by the top candidate, then a leaderboard of the eight best-ranked variants and the pedigree.
Data & QC · What does the MultiQC report say about reads and alignments?
General statistics, FastQC counts and fastp filtered reads, then the Picard alignment summary, duplicates, insert size and the coverage histogram. Base quality, adapter content and the mosdepth curves are collapsed.
Data & QC · What do the alignment, coverage and call numbers say, sample by sample?
Reads, aligned share, mean coverage, duplication and the mitochondrial to nuclear depth ratio, and one table of the samples with the record of the picked sample beside it. The contig depth and the full tables are collapsed.
Data & QC · Are the samples the family the pedigree says they are?
The samples by affected status, the parent-child IBS0 share and the sex check. The pedigree figure from the sample sheet (squares male, circles female, filled marks affected) sits beside the opposite homozygous share of every pair of samples, one bar each, coloured by the verdict. The pair table is collapsed.
Variants · How many calls does each sample yield, and how clean are they?
PASS calls, Ts/Tv, het/hom ratio and calls by FILTER value. Ts/Tv and het/hom per sample as two sorted bars with the usual range shaded (a click narrows the dashboard to that sample), and the substitution spectrum folded onto six classes. Ts/Tv is about 2.0 to 2.1 for a genome and 2.8 to 3.0 for an exome. The karyotype of one sample and the allele fraction per sample are collapsed.
Variants · Which variants rank first, and which inheritance model do they fit?
The 50 best candidates as a leaderboard, best first, with the gene and protein change, the inheritance model and impact as badges and the rank score as a bar. Hover for the consequence, frequency, CADD and carriers; a click picks the variant for the record beside it and opens the pedigree filled by genotype. Then the rank score of the 50 best variants, why the 20 best rank (one segment per GENMOD score component) and the genotype of every individual at those variants.
Variants · How heteroplasmic are the mitochondrial calls, and how rare?
Optional branch. Calls by heteroplasmy class, median heteroplasmy, impact and depth, then heteroplasmy along the mitochondrial genome and against the gnomAD frequency. The mitochondrion is not on the navigator's axis, so this tab has no genome view.
Variants · Do any repeat expansions or mobile element insertions stand out?
Optional branches. Repeat calls by status, pathogenic-range calls by inheritance, mobile element insertions by family and SMN calls. One row per repeat locus, each call placed by its repeat count as a multiple of the pathogenic threshold over shaded normal, intermediate and pathogenic zones; insertions per sample by element family. The tables are collapsed.
Variants · What do the calls and alignments show at one locus?
A navigator draws every ranked variant at its position, higher for a higher rank score and coloured by the inheritance model it fits, linked to a genome browser. The browser opens on the span of the 20 best-ranked variants (else the top-ranked one), showing the research VCF, the proband alignment and coverage, the parents' alignments and the ClinVar and dbSNP tracks; the rest is in its track menu. A brush or a typed locus moves the browser, a rank score slider in the left panel narrows the points to the top, and the ranked variants of the region are listed below.
Tables and leaderboards select rows, and a pick narrows the other tiles of its collection and follows the project links to the rest.
Running the pipeline¶
Depictio reads the output of nf-core/raredisease, it does not run the pipeline. Run the pipeline first:
nextflow run nf-core/raredisease -r 3.1.2 \
--input samplesheet.csv \
--outdir results \
-profile docker
The mitochondrial, repeat expansion, mobile element and SMN branches are optional, and the template adapts to the ones that ran. Then point Depictio at the results, naming the assembly the run used if it is GRCh38:
See nf-co.re/raredisease/usage for full pipeline documentation.
Required data structure¶
Point depictio ingest at the directory holding the pipeline output. Depictio scans
recursively and matches on file name.
<DATA_ROOT>/
├── pedigree/<family>.ped # family, parents, sex, phenotype
├── pipeline_info/
│ ├── params_*.json
│ └── *software*versions*.yml
├── multiqc/multiqc_data/multiqc.parquet
├── alignment/<sample>_sorted_md.metrics.txt # MarkDuplicates (+ BAM and index for the browser)
├── qc_bam/<sample>_{multiplemetrics,wgsmetrics,hsmetrics,mosdepth.mosdepth}.*
├── call_snv/genome/<family>_snv.vcf.gz # joint callset
├── rank_and_filter/<family>_{snv,mt}_ranked_*.vcf.gz # mt: optional
├── repeat_expansions/<family>_repeat_expansion_stranger.vcf.gz # optional
├── call_mobile_elements/<family>_mobile_elements.vcf.gz # optional
└── smncopynumbercaller/out/<family>_smncopynumbercaller.tsv # optional
Validation runs¶
There is no AWS megatest behind this template, so the repository ships no download
script for it. It was built on a real test_full run of nf-core/raredisease 3.1.2
executed on the EMBL cluster: a trio on a reduced GRCh37 reference restricted to one
autosome and the mitochondrion, at about 1.4x mean coverage. Every route the
template reads is present in it.
That depth is far too low for the numbers to mean anything biological: the relatedness estimate is unreliable, the repeat and SMN calls are mostly No call, and there is no X or Y contig, so the sex check reads Not tested. peddy, GENS, the germline CNV caller and structural variant calling were skipped by the run.
Additional resources¶
- nf-co.re/raredisease: official pipeline documentation
- Template System Reference: YAML format, variables, conditionals
- Recipes: how to read, test, and write recipes
Authorship¶
weber8thomas
Reviewing a template on your own data, or taking over a role here, is a contribution in itself: the contributing guide says what each one involves.