Version Compatibility

Reference examples tested with: pandas 2.2+, cyvcf2 0.30+, pyhgvs 0.12+, Exomiser 14.0+ (Smedley 2015), Phen2Gene 1.2+ (Zhao 2020), DeNovoGear 1.1.1+ (Ramu 2013), WhatsHap 2.0+ (Patterson 2015), HPO 2024+ (Human Phenotype Ontology). ACMG Secondary Findings list is v3.2 (Miller 2023): 81 genes.

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• CLI: <tool> --version

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying. Phenotype-driven prioritization REQUIRES high-quality HPO terms; without rich phenotypic input Exomiser/AMELIE degrade significantly.

Rare-Disease Variant Prioritization Pipeline

'Prioritize candidate disease-causing variants from this trio exome' -> Filter to rare + functional + inheritance-consistent variants; rank by phenotype concordance; flag ACMG SF v3.2 incidental findings; report tiers with classification logic deferred to acmg-classification.

• Python (filtering pipeline): pandas + cyvcf2 + myvariant.info aggregation
• CLI (phenotype-driven ranking): exomiser --analysis hiPHIVE-prioritised.yml
• Python (de novo calling): DeNovoGear / Triodenovo / PossibleDeNovo
• CLI (compound het phasing): whatshap phase --indels for singletons; trio-based for families
• Python (HPO concordance): Phen2Gene / AMELIE / Phenolyzer
• VCEP curations: https://cspec.genome.network/cspec/ui/svi/all

Pipeline Architecture: The Standard Rare-Disease Funnel

Typical trio exome enters as 40,000-100,000 variants per individual; reaches diagnostic candidate list of 1-10 variants through cascading filters:

Inheritance-Based Filtering

De Novo Calling: Trio Analysis

Goal: Identify variants present in proband but absent in both parents with high specificity.

Approach: Use specialized DNV callers; supplement with manual IGV inspection.

False-DNV rate: ~10-30% without manual IGV inspection; concentrated in:

• Tandem repeat regions (DNM rate inflated)
• Heterozygous parent with low coverage
• Mosaic parents (parental mosaicism transmitted to >1 offspring)
• Mapping errors in segmental duplications

Phenotype-Driven Prioritization

Critical requirement: all phenotype-driven tools degrade significantly with sparse HPO terms. Capture 5-10 specific HPO terms; avoid generic "intellectual disability" alone.

ClinGen Gene-Disease Validity: Mandatory Gating

Strande et al. 2017 AJHG + ClinGen ongoing curation: Limited / Moderate / Strong / Definitive evidence per gene-disease pair.

Many commercial panels include genes with only Limited validity. ClinGen-curated https://search.clinicalgenome.org/kb/gene-validity is the authoritative directory.

ACMG Secondary Findings v3.2 (Miller 2023 Genet Med 25:100866)

81 genes for opt-in/opt-out reporting on clinical exome/genome. Growth: 56 -> 59 -> 73 -> 78 -> 81. v3.2 additions: CALM1, CALM2, CALM3 (calmodulinopathy; long QT / CPVT; high actionability via beta-blockade + ICD).

Inclusion criteria: ClinGen Strong or Definitive gene-disease validity + ClinGen ADWG actionability scoring.

ACMG_SF_V3_2_GENES = [
    # Cardiomyopathies
    'ACTA2', 'ACTC1', 'BAG3', 'COL3A1', 'DES', 'FBN1', 'FLNC', 'GLA', 'LMNA', 'MYBPC3',
    'MYH11', 'MYH7', 'MYL2', 'MYL3', 'PRKAG2', 'PKP2', 'RBM20', 'SCN5A', 'SMAD3',
    'TGFBR1', 'TGFBR2', 'TMEM43', 'TNNC1', 'TNNI3', 'TNNT2', 'TPM1', 'TTN',
    # CALM v3.2 additions (calmodulinopathies)
    'CALM1', 'CALM2', 'CALM3',
    # Arrhythmias and channelopathies
    'CACNA1S', 'KCNH2', 'KCNQ1', 'RYR1', 'RYR2',
    # Vascular
    'ACVRL1', 'ENG',
    # Cancer predisposition
    'APC', 'ATM', 'BAP1', 'BMPR1A', 'BRCA1', 'BRCA2', 'BRIP1', 'CDH1', 'CDKN2A',
    'CHEK2', 'GREM1', 'HOXB13', 'MAX', 'MEN1', 'MLH1', 'MSH2', 'MSH6', 'MUTYH',
    'NF2', 'PALB2', 'PMS2', 'PTEN', 'RAD51C', 'RAD51D', 'RB1', 'RET', 'SDHAF2',
    'SDHB', 'SDHC', 'SDHD', 'SMAD4', 'STK11', 'TMEM127', 'TP53', 'TSC1', 'TSC2',
    'VHL', 'WT1',
    # Other
    'FH', 'GAA', 'HFE', 'HNF1A', 'LDLR', 'OTC', 'PCSK9', 'TTR'
]
# Note: above list is illustrative; pin to Miller 2023 supplement for exact set.

Decision Tree by Scenario

Standard Pipeline Workflow

Goal: From a trio joint-called VCF, output ranked candidate variants with inheritance pattern, phenotype concordance, and ACMG SF flags.

Approach: Cascading filters with QC, population frequency, functional consequence, inheritance, phenotype.

from cyvcf2 import VCF
import pandas as pd
from pathlib import Path

# Quality + population frequency filter (apply first)
def filter_qc_and_frequency(vcf_path, max_grpmax_faf95=0.0001, min_dp=10, min_gq=20):
    '''Stage 1: QC + frequency filter. Reduces 100k -> ~5-15k variants.'''
    vcf = VCF(vcf_path)
    samples = vcf.samples  # e.g., [proband, mother, father]
    rows = []
    for v in vcf:
        if v.FILTER is not None:
            continue
        if min(v.gt_depths) < min_dp:
            continue
        if v.QUAL is not None and v.QUAL < min_gq:
            continue
        gnomad = (v.INFO.get('grpmax_faf95') or v.INFO.get('AF_grpmax') or
                  v.INFO.get('AF_popmax') or 0)
        if gnomad > max_grpmax_faf95:
            continue
        rows.append({
            'chrom': v.CHROM, 'pos': v.POS, 'ref': v.REF, 'alt': v.ALT[0],
            'genotypes': dict(zip(samples, v.gt_types.tolist())),
            'depth': dict(zip(samples, v.gt_depths.tolist())),
            'gnomad_faf95': gnomad,
            'consequence': v.INFO.get('CSQ', '').split('|')[1] if v.INFO.get('CSQ') else None
        })
    return pd.DataFrame(rows)


def call_de_novo(df, proband, mother, father):
    '''Stage 2: identify DNV candidates: hom-ref both parents, het/hom-alt proband.

    Implements Mendelian-violation logic; supplement with DeNovoGear or DeNovoCNN
    for production (this implementation has 10-30% false-positive rate without IGV).
    '''
    is_dnv = []
    for _, row in df.iterrows():
        gts = row['genotypes']
        if gts[mother] == 0 and gts[father] == 0 and gts[proband] in (1, 3):
            # Mother hom-ref AND father hom-ref AND proband het OR hom-alt
            # Confidence boost: depth at parent sites should be >= 10 to trust hom-ref
            if row['depth'][mother] >= 10 and row['depth'][father] >= 10:
                is_dnv.append(True)
                continue
        is_dnv.append(False)
    df['is_de_novo_candidate'] = is_dnv
    return df


def call_compound_het(df, proband, mother, father, gene_col='gene'):
    '''Stage 3: identify compound het: two het variants in same gene, one from each parent.

    Trio phasing is gold standard; singletons require WhatsHap read-based phasing.
    '''
    het_in_proband = df[df['genotypes'].apply(lambda gts: gts[proband] == 1)]
    candidate_genes = []
    for gene in het_in_proband[gene_col].unique():
        if pd.isna(gene):
            continue
        gene_variants = het_in_proband[het_in_proband[gene_col] == gene]
        # Need >= 2 variants; one inherited from each parent
        maternal_het = gene_variants[gene_variants['genotypes'].apply(
            lambda gts: gts[mother] == 1 and gts[father] == 0)]
        paternal_het = gene_variants[gene_variants['genotypes'].apply(
            lambda gts: gts[father] == 1 and gts[mother] == 0)]
        if len(maternal_het) >= 1 and len(paternal_het) >= 1:
            candidate_genes.append(gene)
    df['is_compound_het_candidate'] = df[gene_col].isin(candidate_genes)
    return df


def flag_acmg_sf(df, acmg_sf_genes, gene_col='gene', clnsig_col='clinvar_sig'):
    '''Stage: flag ACMG Secondary Findings (Miller 2023 v3.2; 81 genes).

    Only P/LP variants in SF genes are reportable as secondary findings.
    '''
    df['is_acmg_sf_candidate'] = (
        df[gene_col].isin(acmg_sf_genes) &
        df[clnsig_col].astype(str).str.contains('athogenic', na=False)
    )
    return df


def filter_by_clingen_validity(df, validity_table, gene_col='gene',
                                min_validity='Moderate'):
    '''Gate on ClinGen gene-disease validity. Limited or Disputed -> low confidence.

    validity_table: DataFrame from `https://search.clinicalgenome.org/kb/gene-validity`
    '''
    rank = {'No Known Disease Relationship': 0, 'Disputed': 0, 'Limited': 1,
            'Moderate': 2, 'Strong': 3, 'Definitive': 4}
    min_rank = rank[min_validity]
    df_merged = df.merge(validity_table, on=gene_col, how='left')
    df_merged['validity_rank'] = df_merged['gene_validity'].map(rank).fillna(0)
    df_merged['pass_validity'] = df_merged['validity_rank'] >= min_rank
    return df_merged


def phenotype_score_with_exomiser_yml(yml_path, vcf_path, hpo_terms, output_dir):
    '''Emit Exomiser command for phenotype-driven ranking.

    HPO terms (e.g., HP:0001250 for seizures) must be SPECIFIC.
    Sparse generic HPO degrades Exomiser hiPHIVE accuracy significantly.
    '''
    return (f'java -jar exomiser-cli-14.0.0.jar --analysis {yml_path} '
            f'--vcf {vcf_path} --hpo {",".join(hpo_terms)} '
            f'--output-dir {output_dir}')

Per-Operation Failure Modes

1. De novo with false-positive rate 10-30%

• Trigger: Report DNV candidates from Mendelian-violation analysis without IGV inspection.
• Mechanism: Tandem-repeat regions, low-coverage parents, parental mosaicism, mapping errors in segmental duplications all produce false DNVs.
• Symptom: 10-30% of reported DNVs are artifacts.
• Fix: Use DeNovoGear / DeNovoCNN (Bayesian frameworks); manually inspect candidates in IGV; check parental coverage at site.

2. Compound het without phasing

• Trigger: Report two hets in same gene as compound het without confirming phase.
• Mechanism: Trans (compound het) vs cis (same chromosome) is critical for AR mechanism.
• Symptom: False-positive compound het when both variants are in cis.
• Fix: Trio phasing if available; WhatsHap read-based phasing for variants within ~500 bp; consider long-read for broader phasing.

3. Limited-validity gene reported as diagnostic

• Trigger: Gene appears on commercial panel; variant labeled disease-causing.
• Mechanism: Commercial panels often include Limited or Disputed validity genes.
• Symptom: False-positive diagnostic report.
• Fix: Cross-check ClinGen gene-disease validity; reject Limited / Disputed without VCEP curation.

4. Sparse HPO terms degrading Exomiser

• Trigger: Submit Exomiser with single generic HPO (e.g., HP:0001250 "Seizure" only).
• Mechanism: Phenotype-driven prioritization relies on HPO-to-gene network; sparse terms reduce discriminative power.
• Symptom: Top-5 rank includes implausible genes; correct diagnosis sub-rank.
• Fix: Capture 5-10 specific HPO terms (e.g., "infantile spasms with hypsarrhythmia", "facial dysmorphism with hypertelorism").

5. ACMG SF v3.1 used instead of v3.2

• Trigger: Pipeline reports SF based on 78-gene v3.1 list; misses CALM1/2/3 calmodulinopathies.
• Mechanism: v3.2 (Miller 2023) added CALM1, CALM2, CALM3.
• Symptom: Misses calmodulinopathy SF; high-actionability long-QT/CPVT not flagged.
• Fix: Use Miller 2023 v3.2 list (81 genes); re-run prior cohorts.

6. Mosaic variants below standard VAF threshold

• Trigger: Filter at VAF >= 30% on standard pipeline.
• Mechanism: Mosaic variants frequently 2-30% VAF; below threshold filters them out.
• Symptom: Mosaic disease missed (e.g., Proteus syndrome PIK3CA, McCune-Albright GNAS).
• Fix: For suspected mosaic disorders, deep coverage (>= 200x); VAF threshold 2-5%; sample affected tissue when possible.

7. ClinVar P variant in Limited-validity gene

• Trigger: Variant labeled P in ClinVar; gene-disease validity is Limited.
• Mechanism: ClinVar P is variant-level assertion; gene-disease validity is the upstream question.
• Symptom: Reported P variant in non-disease-associated gene.
• Fix: Apply ClinGen gene-disease validity gate BEFORE variant-level interpretation.

8. VUS reclassification gaps

• Trigger: VUS labeled 2017 still in active diagnostic report 2025.
• Mechanism: VUS are reclassified as evidence accrues in actively-curated genes; a one-time classification has an expiry date.
• Symptom: Stale classifications drive incorrect clinical decisions.
• Fix: Annual VUS re-review for active diagnostic variants; tools like Genome Alert! (Yauy 2022) automate detection of monthly ClinVar changes.

9. Inheritance pattern assumed wrong

• Trigger: Assume AD inheritance for a gene with variable expressivity / incomplete penetrance.
• Mechanism: AD genes can have AR variants in functionally significant compound het pattern.
• Symptom: Miss AR mechanism in mostly-AD gene.
• Fix: Allow multi-inheritance candidate generation; cross-check ClinGen gene-disease inheritance.

Reconciliation: When Sources Disagree

Quantitative Thresholds and Conventions

Common Errors

Anticipated Reviewer Pushback

References

• Richards S et al. 2015. Standards and guidelines for the interpretation of sequence variants. Genet Med 17:405. (ACMG/AMP)
• Miller DT et al. 2023. ACMG SF v3.2 list for reporting of secondary findings in clinical exome and genome sequencing. Genet Med 25:100866.
• Smedley D et al. 2015. Next-generation diagnostics and disease-gene discovery with the Exomiser. Nat Protoc 10:2004.
• Zhao M et al. 2020. Phen2Gene: rapid phenotype-driven gene prioritization for rare diseases. NARGAB 2:lqaa032.
• Birgmeier J et al. 2020. AMELIE speeds Mendelian diagnosis by matching patient phenotype and genotype to primary literature. Sci Transl Med 12:eaau9113.
• Cipriani V et al. 2020. An improved phenotype-driven tool for rare Mendelian variant prioritization. Genes 11:460.
• Ramu A et al. 2013. DeNovoGear: de novo indel and point mutation discovery and phasing. Nat Methods 10:985.
• Patterson M et al. 2015. WhatsHap: weighted haplotype assembly for future-generation sequencing reads. J Comput Biol 22:498.
• Strande NT et al. 2017. Evaluating the clinical validity of gene-disease associations: an evidence-based framework developed by ClinGen. AJHG 100:895.
• Whiffin N et al. 2017. Using high-resolution variant frequencies to empower clinical genome interpretation. Genet Med 19:1151.
• Lunke S et al. 2025. Feasibility, acceptability and clinical outcomes of the BabyScreen+ genomic newborn screening study. Nat Med 31:4236.
• Yauy K et al. 2022. Genome Alert! Genet Med 24:1316. (VUS reclassification monitoring)
• ClinGen gene-disease validity: https://search.clinicalgenome.org/kb/gene-validity
• HPO: https://hpo.jax.org/
• ACMG SF v3.2 supplement: https://www.gimjournal.org/article/S1098-3600(23)00879-1/fulltext

Related Skills

• clinical-databases/acmg-classification - PVS1 / PP3 / BS1 / PM2 calibration and Tavtigian point system
• clinical-databases/clinvar-lookup - Variant pathogenicity database query
• clinical-databases/gnomad-frequencies - Population frequency filtering
• clinical-databases/myvariant-queries - Aggregated annotation
• clinical-databases/pharmacogenomics - PGx variant handling
• variant-calling/clinical-interpretation - Clinical reporting workflow
• variant-calling/filtering-best-practices - Upstream QC