Transcript models

An effect may carry a MutantTranscript describing edits, retained reference segments, or an observed RNA structure. It can contain cDNA and protein sequence, but it may also be partial or have no resolved sequence.

You usually want the effect's mutant_protein_sequence; a transcript model is useful when you also need the RNA structure or its provenance. Not every effect has a model, even when a predicted protein is available.

Sequence access

Given an annotated effect:

protein = effect.mutant_protein_sequence
model = effect.mutant_transcript
cdna = model.cdna_sequence if model is not None else None
evidence = model.evidence if model is not None else None
baseline = effect.baseline_transcript
baseline_cdna = baseline.cdna_sequence if baseline is not None else None
baseline_protein = effect.original_protein_sequence

None means unavailable. It does not establish an unchanged protein, an absent transcript, or a harmless variant.

For a composed comparison, baseline_transcript and mutant_transcript are the actual products used to classify the effect. original_protein_sequence is then the patient baseline, including inherited changes, and amino-acid offsets refer to that baseline. The annotation reference remains available as effect.reference_transcript. These models and sequences survive JSON and pickle round trips.

The transcript-model annotator assembles selected exon, retained-intron and cryptic-splice intervals through one cDNA/translation path. Unavailable paths have None sequences; they never substitute the canonical transcript. Each candidate exposes its own products through the same effect accessors. Products with different distant sequences remain distinct candidates, even if their local amino-acid changes match.

The default considers supplied germline calls across the whole transcript span. Unknown phase produces alternatives or a hypothesis limit; missing germline calls cannot be recovered. The explicit compatibility selections fast and protein_diff retain their local germline lookup. See annotation choices.

Selenocysteine

Ensembl marks selenocysteine (Sec) as U in the reference protein, encoded by an in-frame UGA. UGA is decoded as Sec only with a SECIS element in the same mRNA's 3′ UTR, whose position isn't annotated. Predicted proteins read an annotated Sec codon as U when the model still maps it (no edit touches it) and keeps some of a selenoprotein's 3′ UTR. Where no selenoprotein 3′ UTR remains, for example a fusion downstream of Sec, UGA is read as a stop. A sequence without reference coordinates, such as an imported RNA assembly, is translated literally. A partly kept 3′ UTR still gets the Sec reading; the SV change flags report such cases as unresolved.

Partial structures

A model with reference segments is not necessarily a complete mutant RNA. For example, a breakend can retain only a transcript's local 5′ prefix or 3′ suffix. That model has evidence["sequence_status"] = "retained_reference_fragment", while full cDNA and protein remain unknown. Concatenating its segments does not reconstruct the missing partner or establish the full allele.

Likewise, a sequence supplied by an RNA assembler may be only a junction fragment. Keep its completeness and source information with the sequence. The RNA import guide explains how observed structures and sequence-predicted proteins are represented; neither alone proves translation.

Related objects

Effects produced by annotator="transcript_model" retain their typed candidates, hypotheses, baseline and mutant products, evidence and ranking through EffectCollection.to_json() / from_json() and individual effect serialization. The versioned graph preserves candidate links to the owning effect and retains unknown probabilities as None. Older effect JSON remains readable. Transcript references still use the existing PyEnsembl serialization contract; the archive is not a replacement for reference annotation data. Extra-ORF effect JSON remains a separate unsupported operation; use its native orf_annotation.to_dict() export.

Object	Contents
MutationEffect	A predicted consequence or an unresolved result
MutantTranscript	Edits or transcript structure, provenance, and optional sequences
MultiOutcomeEffect	Several candidate effects, each with its own consequence and evidence

The API reference lists model fields and construction helpers. The default transcript-model annotator uses baseline and mutant product wrappers; see its result format.

Ambiguous reference codons retain their uniquely determined amino acid, or X when no unique residue is established. X is an unknown residue, including a possible stop for mixed sense/stop codons; it is not a concrete amino acid. The original cDNA remains available. See the translation convention.