Data Models

Variant types

vartriage.Variant dataclass

Raw variant record from VCF parsing.

Parameters

chrom : str Chromosome name (e.g., "chr1", "1"). pos : int 1-based genomic position. id : Optional[str] Variant identifier or None if missing. ref : str Reference allele. alt : str Alternate allele (single ALT; multiallelic split upstream). qual : Optional[float] Phred-scaled quality score or None if missing. filter_status : str FILTER field value (e.g., "PASS", ".", "LowQual"). info : dict[str, Any] INFO field key-value pairs.

Source code in vartriage/models/variant.py

@dataclass(frozen=True, slots=True)
class Variant:
    """Raw variant record from VCF parsing.

    Parameters
    ----------
    chrom : str
        Chromosome name (e.g., "chr1", "1").
    pos : int
        1-based genomic position.
    id : Optional[str]
        Variant identifier or None if missing.
    ref : str
        Reference allele.
    alt : str
        Alternate allele (single ALT; multiallelic split upstream).
    qual : Optional[float]
        Phred-scaled quality score or None if missing.
    filter_status : str
        FILTER field value (e.g., "PASS", ".", "LowQual").
    info : dict[str, Any]
        INFO field key-value pairs.
    """

    chrom: str
    pos: int
    id: str | None
    ref: str
    alt: str
    qual: float | None
    filter_status: str
    info: dict[str, Any] = field(default_factory=dict)

vartriage.AnnotatedVariant dataclass

Variant enriched with functional and population annotations.

Parameters

variant : Variant Original variant record. consequence : FunctionalConsequence Most severe predicted functional effect. allele_frequency : Optional[float] gnomAD population frequency (0.0-1.0) or None if unknown. clinvar_assertion : Optional[ClinVarAssertion] ClinVar clinical significance or None if not found. frequency_unknown : bool True if variant was absent from gnomAD. clinvar_unknown : bool True if variant was absent from ClinVar. gene_name : Optional[str] Gene symbol from consequence annotation, or None for intergenic variants. protein_change : Optional[ProteinChange] Amino acid substitution from codon resolution, or None if not a coding SNV or resolution failed.

Source code in vartriage/models/variant.py

@dataclass(frozen=True, slots=True)
class AnnotatedVariant:
    """Variant enriched with functional and population annotations.

    Parameters
    ----------
    variant : Variant
        Original variant record.
    consequence : FunctionalConsequence
        Most severe predicted functional effect.
    allele_frequency : Optional[float]
        gnomAD population frequency (0.0-1.0) or None if unknown.
    clinvar_assertion : Optional[ClinVarAssertion]
        ClinVar clinical significance or None if not found.
    frequency_unknown : bool
        True if variant was absent from gnomAD.
    clinvar_unknown : bool
        True if variant was absent from ClinVar.
    gene_name : Optional[str]
        Gene symbol from consequence annotation, or None for intergenic variants.
    protein_change : Optional[ProteinChange]
        Amino acid substitution from codon resolution, or None if not a
        coding SNV or resolution failed.
    """

    variant: Variant
    consequence: FunctionalConsequence
    allele_frequency: float | None = None
    clinvar_assertion: ClinVarAssertion | None = None
    clinvar_review_status: ClinVarReviewStatus | None = None
    frequency_unknown: bool = False
    clinvar_unknown: bool = False
    gene_name: str | None = None
    population_frequencies: PopulationFrequencies | None = None
    zygosity: Zygosity = Zygosity.UNKNOWN
    quality_metrics: VariantQualityMetrics | None = None
    gene_context: GeneContext | None = None
    protein_change: ProteinChange | None = None

vartriage.ScoredVariant dataclass

Annotated variant with pathogenicity scores attached.

Parameters

annotated : AnnotatedVariant Fully annotated variant. cadd_phred : Optional[float] Raw CADD Phred score (0-99+). cadd_normalized : Optional[float] CADD normalized to 0.0-1.0 scale. revel_score : Optional[float] REVEL score (0.0-1.0). spliceai_score : Optional[float] SpliceAI delta score (0.0-1.0) predicting splice-disrupting effects. None when SpliceAI is not configured or the variant has no lookup match. composite_rank : Optional[float] Weighted composite rank derived from available scores using dynamic proportional weight redistribution.

Source code in vartriage/models/variant.py

@dataclass(frozen=True, slots=True)
class ScoredVariant:
    """Annotated variant with pathogenicity scores attached.

    Parameters
    ----------
    annotated : AnnotatedVariant
        Fully annotated variant.
    cadd_phred : Optional[float]
        Raw CADD Phred score (0-99+).
    cadd_normalized : Optional[float]
        CADD normalized to 0.0-1.0 scale.
    revel_score : Optional[float]
        REVEL score (0.0-1.0).
    spliceai_score : Optional[float]
        SpliceAI delta score (0.0-1.0) predicting splice-disrupting
        effects. None when SpliceAI is not configured or the variant
        has no lookup match.
    composite_rank : Optional[float]
        Weighted composite rank derived from available scores using
        dynamic proportional weight redistribution.
    """

    annotated: AnnotatedVariant
    cadd_phred: float | None = None
    cadd_normalized: float | None = None
    revel_score: float | None = None
    spliceai_score: float | None = None
    composite_rank: float | None = None
    prioritization_score: float | None = None

    def __post_init__(self) -> None:
        # Sync: prioritization_score is the canonical field,
        # composite_rank kept for backward compatibility
        if self.prioritization_score is None and self.composite_rank is not None:
            object.__setattr__(self, "prioritization_score", self.composite_rank)
        elif self.composite_rank is None and self.prioritization_score is not None:
            object.__setattr__(self, "composite_rank", self.prioritization_score)

vartriage.ClassifiedVariant dataclass

Scored variant with ACMG/AMP classification.

Parameters

scored : ScoredVariant Scored variant with pathogenicity rank. evidence_tags : frozenset[EvidenceTag] Set of ACMG evidence tags assigned. classification : ACMGClassification Final ACMG/AMP classification result. missing_data_sources : frozenset[str] Names of data sources unavailable for classification.

Source code in vartriage/models/variant.py

@dataclass(frozen=True, slots=True)
class ClassifiedVariant:
    """Scored variant with ACMG/AMP classification.

    Parameters
    ----------
    scored : ScoredVariant
        Scored variant with pathogenicity rank.
    evidence_tags : frozenset[EvidenceTag]
        Set of ACMG evidence tags assigned.
    classification : ACMGClassification
        Final ACMG/AMP classification result.
    missing_data_sources : frozenset[str]
        Names of data sources unavailable for classification.
    """

    scored: ScoredVariant
    evidence_tags: frozenset[EvidenceTag] = field(default_factory=frozenset)
    classification: ACMGClassification = ACMGClassification.VUS
    missing_data_sources: frozenset[str] = field(default_factory=frozenset)
    has_conflicting_evidence: bool = False

Enums

vartriage.FunctionalConsequence

Bases: Enum

Predicted biological effect of a variant on gene function.

Members are ordered by severity (highest first). When a variant overlaps multiple transcripts with different consequences, the pipeline assigns the most severe value according to this ordering.

Attributes

FRAMESHIFT : str Insertion or deletion that shifts the reading frame. NONSENSE : str Premature stop codon introduction. SPLICE_SITE : str Variant within 2 bases of an exon-intron junction. MISSENSE : str Single amino acid substitution. IN_FRAME_INSERTION : str Insertion that preserves the reading frame. IN_FRAME_DELETION : str Deletion that preserves the reading frame. SYNONYMOUS : str Codon change with no amino acid change. INTERGENIC : str Variant falls outside any known coding region.

Source code in vartriage/models/variant.py

class FunctionalConsequence(Enum):
    """Predicted biological effect of a variant on gene function.

    Members are ordered by severity (highest first). When a variant overlaps
    multiple transcripts with different consequences, the pipeline assigns the
    most severe value according to this ordering.

    Attributes
    ----------
    FRAMESHIFT : str
        Insertion or deletion that shifts the reading frame.
    NONSENSE : str
        Premature stop codon introduction.
    SPLICE_SITE : str
        Variant within 2 bases of an exon-intron junction.
    MISSENSE : str
        Single amino acid substitution.
    IN_FRAME_INSERTION : str
        Insertion that preserves the reading frame.
    IN_FRAME_DELETION : str
        Deletion that preserves the reading frame.
    SYNONYMOUS : str
        Codon change with no amino acid change.
    INTERGENIC : str
        Variant falls outside any known coding region.
    """

    FRAMESHIFT = "Frameshift"
    NONSENSE = "Nonsense"
    SPLICE_SITE = "Splice_Site"
    MISSENSE = "Missense"
    IN_FRAME_INSERTION = "In_Frame_Insertion"
    IN_FRAME_DELETION = "In_Frame_Deletion"
    STOP_LOSS = "Stop_Loss"
    SYNONYMOUS = "Synonymous"
    INTERGENIC = "Intergenic"

vartriage.ClinVarAssertion

Bases: Enum

ClinVar clinical significance categories.

Attributes

PATHOGENIC : str Variant is pathogenic. LIKELY_PATHOGENIC : str Variant is likely pathogenic. VUS : str Variant of uncertain significance. LIKELY_BENIGN : str Variant is likely benign. BENIGN : str Variant is benign.

Source code in vartriage/models/variant.py

class ClinVarAssertion(Enum):
    """ClinVar clinical significance categories.

    Attributes
    ----------
    PATHOGENIC : str
        Variant is pathogenic.
    LIKELY_PATHOGENIC : str
        Variant is likely pathogenic.
    VUS : str
        Variant of uncertain significance.
    LIKELY_BENIGN : str
        Variant is likely benign.
    BENIGN : str
        Variant is benign.
    """

    PATHOGENIC = "Pathogenic"
    LIKELY_PATHOGENIC = "Likely_Pathogenic"
    VUS = "VUS"
    LIKELY_BENIGN = "Likely_Benign"
    BENIGN = "Benign"

vartriage.ACMGClassification

Bases: Enum

Final ACMG/AMP 2015 classification for a variant.

In v0.x, only PATHOGENIC, LIKELY_PATHOGENIC, and VUS are produced. LIKELY_BENIGN and BENIGN exist for forward compatibility but the current rules don't assign benign evidence tags yet.

Source code in vartriage/models/variant.py

class ACMGClassification(Enum):
    """Final ACMG/AMP 2015 classification for a variant.

    In v0.x, only PATHOGENIC, LIKELY_PATHOGENIC, and VUS are produced.
    LIKELY_BENIGN and BENIGN exist for forward compatibility but the
    current rules don't assign benign evidence tags yet.
    """

    PATHOGENIC = "Pathogenic"
    LIKELY_PATHOGENIC = "Likely_Pathogenic"
    VUS = "VUS"
    LIKELY_BENIGN = "Likely_Benign"
    BENIGN = "Benign"

vartriage.EvidenceTag

Bases: Enum

ACMG/AMP evidence tags assigned during classification.

Each tag corresponds to a specific criterion from the ACMG/AMP 2015 guidelines, with an associated strength tier defined in EVIDENCE_STRENGTH_MAP.

Attributes

PVS1 : str Very Strong evidence: null variant (nonsense or frameshift). PM2 : str Moderate evidence: absent from population controls. PP3 : str Supporting evidence: computational pathogenicity prediction. PP5 : str Supporting evidence: reputable clinical source (ClinVar).

Source code in vartriage/models/variant.py

class EvidenceTag(Enum):
    """ACMG/AMP evidence tags assigned during classification.

    Each tag corresponds to a specific criterion from the ACMG/AMP 2015
    guidelines, with an associated strength tier defined in
    ``EVIDENCE_STRENGTH_MAP``.

    Attributes
    ----------
    PVS1 : str
        Very Strong evidence: null variant (nonsense or frameshift).
    PM2 : str
        Moderate evidence: absent from population controls.
    PP3 : str
        Supporting evidence: computational pathogenicity prediction.
    PP5 : str
        Supporting evidence: reputable clinical source (ClinVar).
    """

    # Pathogenic evidence
    PVS1 = "PVS1"
    PVS1_STRONG = "PVS1_Strong"
    PS1 = "PS1"
    PM1 = "PM1"
    PM2 = "PM2"
    PM4 = "PM4"
    PM5 = "PM5"
    PP3 = "PP3"
    PP3_MODERATE = "PP3_Moderate"
    PP3_STRONG = "PP3_Strong"
    PP5 = "PP5"
    PP5_STRONG = "PP5_Strong"

    # Benign evidence
    BA1 = "BA1"
    BS1 = "BS1"
    BS2 = "BS2"
    BP4 = "BP4"
    BP4_MODERATE = "BP4_Moderate"
    BP7 = "BP7"

vartriage.EvidenceStrength

Bases: Enum

ACMG evidence strength tiers used in combining rules.

Attributes

VERY_STRONG : str Very strong level of evidence. STRONG : str Strong level of evidence. MODERATE : str Moderate level of evidence. SUPPORTING : str Supporting level of evidence.

Source code in vartriage/models/variant.py

class EvidenceStrength(Enum):
    """ACMG evidence strength tiers used in combining rules.

    Attributes
    ----------
    VERY_STRONG : str
        Very strong level of evidence.
    STRONG : str
        Strong level of evidence.
    MODERATE : str
        Moderate level of evidence.
    SUPPORTING : str
        Supporting level of evidence.
    """

    STANDALONE = "Standalone"
    VERY_STRONG = "Very_Strong"
    STRONG = "Strong"
    MODERATE = "Moderate"
    SUPPORTING = "Supporting"