just_dna_enricher.events¶
just_dna_enricher.events ¶
Whether two spellings of a position name one event: the one tri-state judge (RM267, RM375).
The class this module closes. An indel can be written at several anchors inside its repeat, and
two releases of one source, or two sources, or an author and a source, routinely pick different ones:
the old Ensembl snapshot wrote NUDT15's rs761191455 as 13:48041104 G>GG, the new one as
13:48041103 T>TG, and a CPIC-drafted haplotypes.csv authored the first. Every place that compared two
such spellings decided the question its own way: by exact start (the compiler's positional fill and
its SNP-core _verify), by len(ref) == 1 read as "substitution" (resolver.coordinate_verdict, which
an insertion's one-base anchor satisfies), or by VRS ids that are absent on every offline indel
(outcome._same_events, which then read "unknown" as "different"). This is where the question is
answered for all of them, three-valued: True (one event), False (two), None (nothing this run
holds can tell). None is never a weak False (@tautology-zero).
Two entry points, one ladder.
same_eventtakes two whole alleles. The spellings are identical; or both are substitutions, which have one spelling once their shared flank is trimmed; or both mint a VRS id (the id is over the fully justified allele, so it needs no tolerance); or both left-align against the reference window. Else undecided.names_eventtakes an authored coordinate, which may be partial — a haplotype row authors astartand perhaps aref, never an ALT — against one allele of a resolved locus. A whole authored allele goes throughsame_event. A partial one names the event when itsstart(and itsref, where it states one) is one of the event's anchors: a substitution's own or trimmed spelling, or every spelling an indel slides through inside its repeat (sequences.indel_spellings, which reads the reference). It is a different event only where that answer is sharp: a substitution, which cannot slide, or an indel whose every spelling the reference showed, with the authored position outside every base those spellings touch. A position inside the event's footprint that is no VCF anchor (an HGVS-style position) and a paddedrefare undecided, as is anything with no reference read.
The enricher alone may call these: the compiler holds no reference (P2), so it reads the verdict the
enricher recorded (ResolutionRow.authored_event) and never judges two spellings itself
(@a-recorded-judgement-is-a-fact, @validation-ceiling).
Allele
dataclass
¶
One allele of one placement, in VCF spelling.
no_mint ¶
The minter of a caller holding no sequence service: every id is unknown, never a guess.
same_event ¶
same_event(
first: Allele,
second: Allele,
*,
mint: Mint,
read_window: ReadWindow | None,
) -> bool | None
Whether two whole spellings are one event — True, False, or None when nothing here can tell.
The module docstring gives the ladder. None is a respelling this run had no sequence to settle,
and it is counted apart.
Source code in enricher/src/just_dna_enricher/events.py
alleles_of ¶
Every nucleotide allele the loci name, one per ALT. A symbolic or empty ALT names no placement.
Source code in enricher/src/just_dna_enricher/events.py
kleene_any ¶
True if any answer is, else None if any is unknown, else False (and False for none).
Source code in enricher/src/just_dna_enricher/events.py
kleene_all ¶
False if any answer is, else None if any is unknown, else True.
names_event ¶
names_event(
chrom: str | None,
start: int,
ref: str | None,
alts: str | None,
event: Allele,
*,
mint: Mint,
read_window: ReadWindow | None,
) -> bool | None
Whether an authored coordinate spells the same event as one resolved allele. See the module note.
chrom may be None (a CPIC-drafted half-coordinate): the authored start is then read on the
event's own contig, which is the only place the compiler would complete it to.
Source code in enricher/src/just_dna_enricher/events.py
authored_event ¶
authored_event(
authored: tuple[
str | None, int | None, str | None, str | None
],
locus: Mapping[str, object],
*,
mint: Mint,
read_window: ReadWindow | None,
) -> tuple[str, str] | None
(authored_event, judged_coordinate) for one locus written for a subject that authored a coordinate.
None (two empty cells) where there is nothing to judge: the subject authored no start, or the
authored cells the compiler compares (chrom, start, and ref where authored) equal the locus's,
so the compiler sees agreement on its own. Otherwise the verdict the compiler reads, over the
locus's ALTs: the authored coordinate names the locus when it spells any of its events (a
multi-allelic site's anchor is shared), and a locus with no nucleotide ALT is undecided. Beside it,
the coordinate it judged (authored_coordinate_key), which binds the verdict: the compiler applies
it only to a row still authoring that coordinate.
Source code in enricher/src/just_dna_enricher/events.py
counterparts ¶
The alleles on the other side a respelling of allele could be: the same contig, within the window
an indel can slide in, the same kind of event (an insertion or deletion of the same length, or a
substitution to the same bases). Shared by the placement witness (RM267) and the drift (RM375).
Source code in enricher/src/just_dna_enricher/events.py
same_allele_sets ¶
same_allele_sets(
before: Sequence[Allele],
after: Sequence[Allele],
*,
mint: Mint,
read_window: ReadWindow | None,
) -> bool | None
Whether two answers for one subject name the same events, allele for allele (RM375).
Every allele on either side is judged against the other side's alleles of its own kind (a
respelling never changes the kind): the same event as one of them, or a different event from all
of them, or undecided. An allele with no counterpart of its kind at all is a change in the answer
when it is a substitution, whose spelling and hosting are both decided without a reference, so
a run with one and a run without would have kept it alike. An unmatched indel is undecided: the
hosting filter settles an indel locus by the reference (RM274) and RM270 splits a locus only when it
can read one, so an offline table and an online one legitimately keep different indel ALTs of the
same source answer (rs746071566's three offline, one online). That costs sharpness, never truth: a
source that really gained or dropped an indel ALT reads undecided rather than moved.
Source code in enricher/src/just_dna_enricher/events.py
covers ¶
covers(
side: Sequence[Allele],
other: Sequence[Allele],
*,
mint: Mint,
read_window: ReadWindow | None,
) -> bool | None
Whether every allele of side is the same event as one of other's: one direction of the judge.
same_allele_sets is both directions; the --rederive drift reads them apart (RM394), because a
source that kept every recorded event and named one more gained an allele, which is neither a
respelling nor a move. The per-allele rule is the one same_allele_sets states: no counterpart is
False for a substitution and undecided for an indel. An empty side is covered.