Data Models Module (biallelic.models)

The models module contains all core data classes and enums for representing genomic data in the biallelic inactivation pipeline.

Data models for genomic aberrations and biallelic inactivation hits.

This module defines the core data structures used throughout the biallelic inactivation analysis pipeline, including enums for aberration types and classes for representing samples, donors, and genomic variations.

class biallelic.models.Aberration(chrom: str, start: int, end: int, aberration_type: AberrationType, aberration_subtype: str, sample_id: str, vaf: float | None = None, n_copy: int | None = None, gene: str = '.', id: str = '.')[source]

Bases: object

A genomic aberration detected in a tumor sample.

Represents a single genomic event (SNV, indel, SV, copy number change, methylation, etc.) in a specific genomic location within a sample.

Attributes:

chrom: Chromosome identifier (e.g., “1”, “X”, “MT”) start: 0-based start coordinate (integer) end: 0-based end coordinate (integer) type: Type of aberration (AberrationType enum name as string) subtype: Functional consequence or specific type (e.g., “missense”, “frameshift”) sample_id: Sample identifier where aberration was detected vaf: Variant allele frequency 0-1 (Optional, None if unavailable) n_copy: Copy number at this location (Optional, None if unavailable) gene: Gene name or symbol (“.” if intergenic) id: Unique identifier for this aberration (“.” if not available)

Example:
>>> from biallelic.models import Aberration, AberrationType
>>> ab = Aberration(
...     chrom="17",
...     start=7577121,
...     end=7577121,
...     aberration_type=AberrationType.SNV,
...     aberration_subtype="missense",
...     sample_id="TCGA-A1-A0SB-01",
...     vaf=0.45,
...     gene="TP53",
...     id="rs1234567"
... )

Initialize an Aberration instance.

Args:

chrom: Chromosome identifier start: 0-based start coordinate end: 0-based end coordinate aberration_type: Type of aberration (AberrationType enum) aberration_subtype: Functional consequence or type detail sample_id: Sample where aberration was detected vaf: Variant allele frequency 0-1 (default: None) n_copy: Copy number at locus (default: None) gene: Gene name/symbol or “.” for intergenic (default: “.”) id: Unique identifier or “.” if unavailable (default: “.”)

class biallelic.models.AberrationType(*values)[source]

Bases: Enum

Types of genomic aberrations detected in cancer samples.

Encompasses somatic mutations, structural variants, copy number changes, germline variants, and epigenetic modifications.

Attributes:

SV: Structural variant (value: 1) SNV: Single nucleotide variant (value: 2) INDEL: Small insertion/deletion (value: 3) CNN_LOH: Copy number neutral loss of heterozygosity (value: 4) GAIN_LOH: Copy number gain with loss of heterozygosity (value: 5) GERM_SNV: Germline single nucleotide variant (value: 6) HOM_LOSS: Homozygous loss (deletion) (value: 7) HET_LOSS: Heterozygous loss (deletion) (value: 8) GERM_HET_LOSS: Germline heterozygous loss (value: 9) GERM_HOM_LOSS: Germline homozygous loss (value: 10) GERM_HOM_SNV: Germline homozygous SNV (value: 11) METHYL: Promoter methylation silencing (value: 12) AMP: High-level copy number amplification (value: 13) GAIN: Low-level copy number gain (value: 14)

AMP = 13
CNN_LOH = 4
GAIN = 14
GAIN_LOH = 5
GERM_HET_LOSS = 9
GERM_HOM_LOSS = 10
GERM_HOM_SNV = 11
GERM_SNV = 6
HET_LOSS = 8
HOM_LOSS = 7
INDEL = 3
METHYL = 12
SNV = 2
SV = 1
class biallelic.models.DoubleHit(gene: str, cytoband: str, first_hit: str, first_hit_type: str, second_hit: str, second_hit_type: str, hit_type: DoubleHitType, sample_id: str, donor_id: str, id: str = '.')[source]

Bases: object

A biallelic inactivation event in a tumor suppressor gene.

Represents two independent mutational hits on both alleles of a gene, following the Knudson two-hit hypothesis for tumor suppressor inactivation. This is the core output of the biallelic discovery analysis.

Attributes:

gene: Gene name or symbol affected by biallelic inactivation cytoband: Cytogenetic band location of the gene (e.g., “17p13.1”) first_hit: Identifier for the first mutational event first_hit_type: Type/category of the first hit (e.g., “SNV”, “HOM_LOSS”) second_hit: Identifier for the second mutational event second_hit_type: Type/category of the second hit hit_type: Classification of hit combination (DoubleHitType enum as string) sample_id: Sample identifier where the biallelic event was detected donor_id: Donor/patient identifier id: Unique identifier for this biallelic hit event (“.” if unavailable)

Example:
>>> from biallelic.models import DoubleHit, DoubleHitType
>>> hit = DoubleHit(
...     gene="TP53",
...     cytoband="17p13.1",
...     first_hit="rs1234567",
...     first_hit_type="SNV",
...     second_hit="LOSS_17p",
...     second_hit_type="HOM_LOSS",
...     hit_type=DoubleHitType.SomLoss_SomSnv,
...     sample_id="TCGA-A1-A0SB-01",
...     donor_id="TCGA-A1-A0SB",
...     id="BH_000001"
... )

Initialize a DoubleHit instance.

Args:

gene: Gene name or symbol affected cytoband: Cytogenetic band location (e.g., “17p13.1”) first_hit: Identifier/description of first mutational event first_hit_type: Functional type of first hit second_hit: Identifier/description of second mutational event second_hit_type: Functional type of second hit hit_type: Classification of hit pair combination (DoubleHitType) sample_id: Sample identifier donor_id: Donor/patient identifier id: Unique identifier or “.” if unavailable (default: “.”)

class biallelic.models.DoubleHitType(*values)[source]

Bases: Enum

Types of biallelic inactivation patterns detected.

Represents the combination of two independent hits on both alleles of a gene, following the Knudson two-hit hypothesis for tumor suppressor inactivation.

Attributes:

SomLoss_SomLoss: Two somatic copy number losses SomLoss_SomSnv: Somatic loss + somatic SNV SomCnLoh_SomSnv: Somatic CNN-LOH + somatic SNV SomGainLoh_SomSnv: Somatic gain-LOH + somatic SNV SomLoss_SomSv: Somatic loss + somatic structural variant SomSnv_SomSnv: Two somatic SNVs SomLoss_SomIndel: Somatic loss + somatic indel GermLoss_SomLoss: Germline loss + somatic loss GermLoss_GermLoss: Two germline losses GermLoss_GermSnp: Germline loss + germline SNP GermLoss_GermSv: Germline loss + germline structural variant GermSnp_SomLoss: Germline SNP + somatic loss GermSv_SomLoss: Germline SV + somatic loss GermSnp_GermSnp: Two germline SNPs SomLoss_Methyl: Somatic loss + promoter methylation SubclonalLoss_SomSnv: Subclonal loss + somatic SNV SomLoss_SubclonalSnv: Somatic loss + subclonal SNV

GermLoss_GermLoss = 9
GermLoss_GermSnp = 10
GermLoss_GermSv = 11
GermLoss_SomLoss = 8
GermSnp_GermSnp = 14
GermSnp_SomLoss = 12
GermSv_SomLoss = 13
SomCnLoh_SomSnv = 3
SomGainLoh_SomSnv = 4
SomLoss_Methyl = 15
SomLoss_SomIndel = 7
SomLoss_SomLoss = 1
SomLoss_SomSnv = 2
SomLoss_SomSv = 5
SomLoss_SubclonalSnv = 17
SomSnv_SomSnv = 6
SubclonalLoss_SomSnv = 16
class biallelic.models.Gender(*values)[source]

Bases: Enum

Biological sex classification for donor samples.

Attributes:

Unknown: Sex not specified or unknown (value: 0) Male: Male donor (value: 1) Female: Female donor (value: 2)

Female = 2
Male = 1
Unknown = 0
class biallelic.models.OmicsType(*values)[source]

Bases: Enum

Data type for genomic analysis.

Represents the type of omics data being analyzed (genomic mutations, epigenetic modifications, or gene expression).

Attributes:

Genomics: DNA sequence variants and structural changes (value: 1) Methylomics: DNA methylation status (value: 2) Transcriptomics: Gene expression data (value: 3)

Genomics = 1
Methylomics = 2
Transcriptomics = 3
class biallelic.models.SampleDonor(sample_id: str, donor_id: str, gender: Gender, omics: OmicsType = OmicsType.Genomics, cellularity: float = 0, ploidy: float = 2, matching_sample_id: str = '')[source]

Bases: object

Metadata for a donor sample in the analysis cohort.

Represents information about a biological sample and its source donor, including gender, data type, tumor purity, and ploidy.

Attributes:

sample_id: Unique identifier for the sample donor_id: Unique identifier for the donor gender: Biological sex of the donor (from Gender enum) omics: Type of omics data for this sample (from OmicsType enum) cellularity: Tumor purity as fraction 0-1 (default: 0) ploidy: Average ploidy of sample (default: 2 for diploid) matching_sample_id: ID of matched normal sample if available (default: “”)

Example:
>>> from biallelic.models import SampleDonor, Gender, OmicsType
>>> donor = SampleDonor(
...     sample_id="TCGA-A1-A0SB-01",
...     donor_id="TCGA-A1-A0SB",
...     gender=Gender.Female,
...     omics=OmicsType.Genomics,
...     cellularity=0.8,
...     ploidy=2.0,
...     matching_sample_id="TCGA-A1-A0SB-10"
... )

Initialize a SampleDonor instance.

Args:

sample_id: Unique identifier for the sample donor_id: Unique identifier for the donor gender: Biological sex classification (Gender enum) omics: Type of omics data (OmicsType enum, default: Genomics) cellularity: Tumor purity fraction 0-1 (default: 0) ploidy: Average ploidy level (default: 2.0) matching_sample_id: Matched normal sample ID if available (default: “”)

Overview

This module defines:

  • Enums for categorical data types (Gender, OmicsType, AberrationType, DoubleHitType)

  • Classes for representing genomic events (SampleDonor, Aberration, DoubleHit)

All classes are designed to work with the Aberrations orchestrator and discovery analyses.

Usage Examples

Creating a Sample Donor:

from biallelic.models import SampleDonor, Gender

donor = SampleDonor(
    sample_id="TCGA-BL-A0C8-01A",
    donor_id="TCGA-BL-A0C8",
    gender=Gender.Female,
    cellularity=0.95,
    ploidy=2.0
)

Creating an Aberration:

from biallelic.models import Aberration, AberrationType

snv = Aberration(
    chrom="17",
    start=41196312,
    end=41196313,
    aberration_type=AberrationType.SNV,
    aberration_subtype="missense_variant",
    sample_id="TCGA-BL-A0C8-01A",
    gene="TP53",
    vaf=0.45
)

Creating a Double Hit (Biallelic Event):

from biallelic.models import DoubleHit, DoubleHitType

biallelic_hit = DoubleHit(
    gene="TP53",
    sample_id="TCGA-BL-A0C8-01A",
    hit_type=DoubleHitType.SOM_SNV_SOM_LOSS,
    hit_details="SNV at codon 248 + loss of chr17"
)

See Also