torchcell.datamodels.schema.CopyNumberVariantPerturbation

class CopyNumberVariantPerturbation(*, systematic_gene_name: str, perturbed_gene_name: str, gene_namespace: Literal['scerevisiae_s288c_sgd_systematic', 'scerevisiae_cenpk113_7d_locus_tag', 'scerevisiae_peter2018_pangenome_orf', 'ecoli_k12_mg1655_bnumber', 'ecoli_k12_bw25113_locus_tag', 'pputida_kt2440_locus_tag', 'ecoli_b_rel606_locus_tag', 'ecoli_k12_w3110_refseq_locus_tag'], identifier_mapping: DerivedIdentifierMapping | None = None, provenance: str = 'natural', description: str = 'Copy-number variation (incl. presence/absence) of a pangenome ORF vs S288C', perturbation_type: Literal['copy_number_variant'] = 'copy_number_variant', mechanism_so_id: str = 'SO:0001019', mechanism_so_name: str = 'copy_number_variation', copy_number: float, reference_copy_number: float = 1.0, strain_id: str, pangenome_orf_id: str | None = None, origin: str | None = None, sequence_source: str | None = None, sequence_ref: ArtifactRef | None = None)

Bases: GenePerturbation, ModelStrict

Copy-number variation (CNV) of a PRESENT pangenome ORF relative to S288C.

NATURAL-variation, DOSAGE axis: records the copy number of a gene that IS present (amplification / reduction), NOT its absence. copy_number is strictly > 0 (M2 canonical form – absence has exactly ONE encoding, the presence/absence NaturalGeneAbsencePerturbation leaf; “you don’t copy from zero”). Presence of an accessory ORF is likewise the presence/absence NaturalGenePresencePerturbation leaf, not a CNV. This leaf is for a genuine dosage difference:

• AMPLIFICATION -> copy_number > reference_copy_number;

• REDUCTION (still present) -> reference_copy_number > copy_number > 0.

Contrast the ENGINEERED EngineeredCopyNumberPerturbation (same dosage axis, lab origin). origin annotates an accessory ORF’s provenance with the field’s mechanism vocabulary (ancestral | introgression | hgt). For a non-reference ORF the sequence is an off-graph pointer, never inlined.

systematic_gene_name carries the S288C systematic name for a reference ORF, else the pangenome ORF id – so the native-name validator is relaxed (like GeneAddition). Design: [[torchcell.datasets.scerevisiae.caudal2024]].

classmethod validate_copy_number_positive(v: float) → float

M2: CNV encodes DOSAGE of a present gene, never absence – copy_number > 0.

Absence has one canonical encoding (NaturalGeneAbsencePerturbation); a CNV at 0 copies would be a second, forbidden encoding of the same state.

classmethod validate_sys_gene_name(v: str) → str

Relax: a non-reference accessory ORF has a pangenome id, not a yeast systematic name, so accept any non-empty identifier.

classmethod validate_mechanism_so_id(v: str) → str

Mechanism SO id is well-formed.

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].