just_dna_compiler.resolution¶
just_dna_compiler.resolution ¶
Pure, source-independent variant resolution from an injected resolution.csv (0.5).
The compiler's preferred resolution path. It consumes a table of already-resolved facts
(just_dna_format.resolution.ResolutionRow) keyed by the frozen variant_key, and reproduces the
DuckDB resolver's fill / expand / verify semantics without any duckdb import, SQL, or Ensembl
convention. All source knowledge (where facts come from) lives in the separate just-dna-enricher
tier; this module knows only "read the facts I was handed" — the strict inject-only end state
(CONSTITUTION Principle 2).
Digest parity with the DuckDB path is deliberate and load-bearing: given the same facts, this
produces byte-identical weights.parquet (hence artifact.digest) as resolver.resolve_variants.
The one place row order could drift — a one-to-many expansion — is pinned by sorting the expanded
rows on (locus_index, chrom, start, ref), matching the resolver's ORDER BY id, chrom, start, ref.
Since 0.8 the parity holds when the table records no vrs_id: the ids it does record reach the parquets
(RM270, compiler/vrs_columns.py), and the DuckDB path has no table to read them from.
ResolutionOutcome
dataclass
¶
ResolutionOutcome(
variants: list[VariantRow],
plain_warnings: list[str] = list(),
ladders: list[LadderFinding] = list(),
errors: list[str] = list(),
expanded_keys: int | None = None,
expanded_rows: int | None = None,
)
What resolution produced, split by how badly each finding bites.
Three channels rather than the usual two, because resolution has three distinct severities and collapsing any pair of them loses a real distinction:
plain_warnings— reported in both modes, never fatal. Thewarningsproperty adds each ladder's own warning to them, which is what every caller reads.ladders— the round-trip contract, asLadderFindings (RM246): conditions under whichcompile → reverse → compilecannot reproduce the injected table, plusambiguous, which is reproducible but rests on a guessed label.best_effortcarries each one's warning;strict, whose contract is a reproducible artifact, refuses with its refusal — a different and longer sentence than the warning, which is why the pairing has to be carried as a pair rather than as two lists that happen to be built together.strict_errorsderives from them and is no longer a field: a field could be set without a matching warning, which is the drift the pairing prevents.errors— fatal in both modes. Onlywithdrawnlands here: every other finding leaves the annotation intact, while a retracted variant may leave it describing nothing.
expanded_keys / expanded_rows are the one-to-many expansion's two counts, carried out for
manifest.compilation (S33). Two numbers rather than one, and never a ratio, for RM44's reason:
one authored key can expand to any number of rows, and a consumer told only "3 rows are expansion
members" cannot tell three keys of one locus each from one key of three. Rows are counted in the
artifact's own unit — a weights.parquet row — so the number is checkable against the file.
They are None on the non-GRCh38 early return and nowhere else: that path resolves nothing, so
0 would say "looked, found no expansion" of a module nothing looked at. Same tri-state as every
other unknown here — withhold rather than negate.
warnings
property
¶
Everything best_effort reports: the findings that never escalate, then each ladder's own.
best_effort's view only. Under strict a ladder's refusal is published instead of its
warning, never beside it (RM359: a finding lives on the one channel its severity under the mode
picks), so a caller that knows its mode reads channels. Derived rather than stored for the
same reason strict_errors is: the pair is the unit, and a stored list could carry one half.
strict_errors
property
¶
What strict refuses with — each ladder's refusal, or its warning where the two agree.
Derived rather than stored since RM246. As a field it could be populated without the matching
warning ever being emitted, which would give strict a sentence best_effort never says and
no way to notice; as a projection of the pairs, a refusal cannot exist without its warning.
channels ¶
(strict refusals, warnings) in one mode — each ladder through route, so on one channel.
The plain warnings are reported in both modes; a ladder is a warning under best_effort and a
refusal under strict, never both. errors (fatal in both modes) is not here: it is not a
ladder and its caller refuses on it before reading either list.
Source code in compiler/src/just_dna_compiler/resolution.py
PositionalFill
dataclass
¶
PositionalFill(
filled: int = 0,
unplaced_ambiguous: int = 0,
unplaced_absent: int = 0,
contradicted: list[str] = list(),
undecided: list[str] = list(),
)
What the positional fill did, per table. Counts, never a line per row.
unplaced_ambiguous and unplaced_absent are separated for the reason every tri-state in this
codebase is: "the table names this key at several loci and the compiler will not pick one" and
"nothing has resolved this key" are different situations with different next moves, and one
number reporting both says neither.
MirroredSettlement
dataclass
¶
MirroredSettlement(
kept: list[ResolutionRow],
sentences: list[str] = list(),
both_ways: list[str] = list(),
unasked: list[str] = list(),
undecided: list[str] = list(),
unplaced: list[str] = list(),
)
What _settle_mirrored_spellings kept of a row's hosting loci, and the sentence for each site it settled.
resolve_from_table ¶
resolve_from_table(
variants: list[VariantRow],
resolution: dict[str, list[ResolutionRow]],
genome_build: str = "GRCh38",
) -> ResolutionOutcome
Fill/expand missing rsid or position from an injected resolution table (no network, no DuckDB).
Mirrors resolver.resolve_variants:
- fill (1:1): a variant_key with exactly one usable row fills the missing coord or rsid,
keeping the frozen key.
- expand (1:N): a variant_key (an rsid) with N usable rows expands to N coord-keyed rows,
ordered by (locus_index, chrom, start, ref) so the parquet byte order matches the DuckDB
path (digest parity). A locus whose alleles cannot host the authored genotype is not
expanded onto — see _hostable_loci.
- verify: a row carrying both an rsid and a coordinate is checked against the table; a
disagreement warns in best_effort and refuses in strict.
GRCh38-bound, like the DuckDB resolver (RM15): a non-GRCh38 module is skipped with a warning, and a
resolution row whose genome_build differs from the module's is ignored.
Returns a ResolutionOutcome — see its docstring for the three severity channels, and
COMPILER.md § Resolution for the full matrix.
Source code in compiler/src/just_dna_compiler/resolution.py
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 | |
recorded_verdicts ¶
recorded_verdicts(
chrom: str | None,
start: int | None,
ref: str | None,
loci: Sequence[ResolutionRow],
) -> set[str]
The authored_event verdicts these loci record about THIS authored coordinate (RM375).
The compiler trusts the record and never judges it (@a-recorded-judgement-is-a-fact). Two
spellings of one indel (NUDT15's 13:48041104 G>GG and 13:48041103 T>TG) differ in start and
ref, and only a reference read can tell them from two events; P2 keeps that read out of this
tier, so the enricher's verdict on the locus's row is the whole answer. One predicate for both
comparers — _verify on the SNP core and _authored_conflict on the positional tables — so the
two cannot read the cell two ways.
Only a verdict about the coordinate the row holds now. The key is the subject's, so a verdict
survives an edit of the coordinate (merge-not-clobber does not re-ask a covered subject) and is
shared with every other table's row under the same rsID. A verdict whose judged_coordinate is not
this row's (authored_coordinate_key, a string compare and no judgement) is no verdict here: the row
reads as never judged, and today's contradiction stands.
Source code in compiler/src/just_dna_compiler/resolution.py
resolve_positional_rows ¶
resolve_positional_rows(
rows: list[object],
resolution: dict[str, list[ResolutionRow]],
genome_build: str = "GRCh38",
) -> PositionalFill
Fill the resolved coordinate into one 0.4-family positional table, in place (RM43).
pharm_variants.csv, haplotypes.csv and heteroplasmy.csv may identify a row by rsID alone —
their own models say so — and until 0.6 the compiler resolved variants.csv and materialized
every other table verbatim. A consumer matching a patient VCF by position therefore matched
nothing, silently, as an empty result rather than an error: the coordinates existed in the
resolution.csv sitting beside the spec and reached the artifact by no path at all.
Four rules, and the last two are what keep this from being the naive repair the roadmap rejected:
- Fill only what the author left empty. A cell the author wrote is never overwritten; that is
enrich's inject-only doctrine (report, never repair) and it is also what makes the fill idempotent. - Fill from exactly one locus, or from none. One usable locus fills. Several are filtered by
hosting_verdictagainst whatever allele the row states — agenotypeon a pharm row, the definingalleleon a haplotype junction, and nothing at all on a heteroplasmy band, which is a measurement over a locus rather than a claim about a genotype. If that leaves one, it fills; otherwise the row stays unplaced and is counted. There is deliberately no expansion: a one-to-many rsID expandsvariants.csvinto N coord-keyed rows, and doing the same here would multiply a pharm annotation's(variant_key, drug, genotype, …)key across loci the author never named. - A row whose own coordinate contradicts the table is left alone.
haplotypes.csvdrafted from CPIC carries astartwith nochrom, so the fill has to complete a half-coordinate — and completing it from a locus whosestartdisagrees would build a coordinate no source ever stated. Reported, never repaired, and never fatal: the same shape asresolve_from_table's_verify, minus the strict escalation, because the row is left exactly as authored. - The row is mutated, not copied, and its identity is frozen.
variant_key/authored_identare stamped at load from the authored subset, so filling cannot re-key the row andreverse_modulere-emits the shape the author wrote (_write_table_csv).
GRCh38-bound for the same reason resolve_from_table is (RM15): the caller skips a non-GRCh38
module rather than joining rows this tier cannot re-derive an identity for.
Source code in compiler/src/just_dna_compiler/resolution.py
521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 | |
usable_loci ¶
Rows that are for this build and record an actual locus (not a not_found sentinel).
The one placement predicate: the SNP-core fill, the positional fill, unresolved_subjects and
subjects.identity_placements (RM362's "does the module sit here") all read a table through it, so
a row that places nothing places nothing for every one of them. Public since that fourth caller.
Source code in compiler/src/just_dna_compiler/resolution.py
withdrawn_refusals ¶
withdrawn_refusals(
variants: list[VariantRow],
resolution: dict[str, list[ResolutionRow]],
genome_build: str,
) -> list[str]
The one resolution refusal that is fatal in both modes, as finished sentences (RM207).
A merged or absent rsID leaves the annotation intact — the module is dated, or the label is
unserved. A withdrawn one is dbSNP repudiating the variant, so the annotation may be describing
something that does not exist; carrying it under best_effort would be publishing a claim its own
source has retracted. Never produced by the automated check (a retraction is indistinguishable
from a never-assigned id through the live API), so it fires only where a curator recorded it.
Sentences rather than names, which is where this differs from unresolved_subjects beside it.
That one returns subjects and lets each caller phrase them, because both phrasings are one short
clause. This message names two things — the subject and the retracted rsID — and the standing
rule is to share the predicate and copy the error; copying a sentence with two interpolations into
a second caller is how the two drift, so the sentence is shared too and there is one of it.
Empty for a non-GRCh38 module, where resolve_from_table skips resolving wholesale.
Source code in compiler/src/just_dna_compiler/resolution.py
ambiguous_refusals ¶
ambiguous_refusals(
variants: list[VariantRow],
resolution: dict[str, list[ResolutionRow]],
genome_build: str,
) -> list[str]
strict-only: the table marks this rsid ambiguous, so the pick is deterministic, not a fact.
Source code in compiler/src/just_dna_compiler/resolution.py
ambiguous_warnings ¶
ambiguous_warnings(
variants: list[VariantRow],
resolution: dict[str, list[ResolutionRow]],
genome_build: str,
) -> list[str]
The best_effort half of the same finding — the pick is carried, and said to be a pick.
Source code in compiler/src/just_dna_compiler/resolution.py
unresolved_subjects ¶
unresolved_subjects(
variants: list[VariantRow],
resolution: dict[str, list[ResolutionRow]],
genome_build: str,
) -> list[str]
Authored rows the injected table cannot place, named by rsID (or variant_key).
The predicate resolve_from_table will apply, factored out so the pre-flight can ask it before
resolution runs and reach the same answer the compile does (S76). A row is unplaceable when it
authors no coordinate of its own and the table holds no usable locus for its key — the same
usable_loci filter the fill uses, so a not_found sentinel and a row recorded under another
build count as no locus here exactly as they do there.
Deliberately not a re-derivation of the compile's check: compile_module runs its refusal over
outcome.variants, the post-expansion list, and the two agree because a subject with no usable
locus is carried through the expansion unchanged. Sharing the predicate is what keeps that true —
a second implementation beside the first is the drift this returns instead of.
Empty for a non-GRCh38 module, where resolve_from_table skips wholesale rather than resolving
less: reporting every row unplaceable there would restate the skip warning once per row and blame
the table for a limit of the tier.
Source code in compiler/src/just_dna_compiler/resolution.py
hosting_verdict ¶
Can a locus spelling {ref} ∪ alts host genotype? Three-valued (RM31).
True it can, False it positively cannot, None this tier cannot tell — the house algebra, and
the third value is the whole point: an indel has several valid spellings, so a string comparison
reporting "does not fit" was asserting a verdict it had not reached.
The ladder, in order, and the order is load-bearing:
- No
ref/altsrecorded →True. Nothing is known about the locus's alleles and rejecting for lack of evidence is worse than accepting. Unchanged. *abstains — on both sides — and the rest is still judged (RM59).*says this sample's allele could not be observed here; it names no allele, so a locus cannot fail to offer it and cannot contradict it, and it belongs in the allele algebra on neither side. Without this the widening that made*/Gauthorable would be self-defeating: no source spells*in an ALT list, so an rsid-authored*/Gresolved against aG>Alocus fell through to step 6 and came back a confidentFalse— the locus dropped from the expansion, the row unresolved, andstrictrefusing over a finding no authored edit could clear. Dropping the member rather than the whole verdict is what keeps the observable half sharp:*/Tat aG>Alocus is stillFalse, because theTreally is a contradiction. Nothing observable on either side isNone.
The locus side is not optional, and the first cut got this wrong on the reasoning that a *
in ref/alts is reachable today, so excluding it might move an existing verdict. It does move
existing verdicts, and it is still right: parsimony_reduce cannot strip a shared flank past a
member that has none, so a * left in the locus stops the set reducing and collapses RM31 —
hosting_verdict('C/CAG', 'AGAG', 'AG') is True while …('C/CAG', 'AGAG', 'AG,*') was
False, refusing a correctly transcribed indel under --strict and telling the author to
"replace it with the alleles the locus actually has". ALT=AG,* is ordinary joint-caller output.
What that costs is measured, and it is not only acceptances. Swept over every star-free
genotype — i.e. everything authorable before RM59 — against loci with and without a *: for a
locus spelled in nucleotides nothing changes at all, and for a locus spelling * verdicts
move in both directions, None → False among them. Those are corrections. * was doing two
things to the arithmetic at once, blocking the flank strip and lending its own single character
to _indel_shaped's length set, so ref=AGAG alts=AG,* stayed unreduced, read as indel-shaped,
and withheld on calls that were decidable all along — a genotype naming an allele the locus does
not have escaped the finding. Same bug class as the RM5 guard's stated reason: characters counted
out of a token that spells no sequence. No reference example carries a *, so the corpus could
not have shown any of this.
3. The raw strings match → True. Checked before any normalization, so this step can only
ever gain acceptances: whatever passed the raw comparison before still passes it, byte for byte.
Step 2 sits above it and costs it nothing, provably rather than nearly — the called side is
stripped first, so * is never on the left of the subset test, and dropping it from the right
therefore cannot change the answer. The guarantee stops here: steps 5–8 are arithmetic over
the reduced sets, and stripping the locus does change those, in both directions (see step 2).
4. Either side names a symbolic allele → None. A <DEL:1500> has no sequence, so it has no
flank for parsimony_reduce and nothing to compare character by character — and a symbolic
allele exists because the exact sequence is not known, so even two stated lengths that differ
are summary information rather than grounds for a contradiction. Undecided, never "no match"
(RM5). Below the raw comparison, so <DEL:1500> against a locus spelling <DEL:1500> still
matches exactly.
5. The reduced allele sets match → True. alleles.parsimony_reduce strips the flank each
collection shares, leaving the event; ClinVar's C/CAG and Ensembl's AGAG>AG both reduce to
{'', 'AG'}, the SHOX 2 bp deletion that used to resolve to not_found.
6. The locus is a substitution or MNV → False. No flank, so no spelling freedom: an A/G
genotype at a C>T locus is a real contradiction, and must stay one (a strand flip is exactly
what that check catches).
7. The genotype names fewer than two distinct alleles → None. A homozygous C/C carries no
frame — one string has nothing to be relative to — so against an indel locus there is genuinely
nothing to compare. Reported as undecided, never as a contradiction. A */C reaches this too
once the * has abstained, and for the same reason: one string has nothing to be relative to.
8. An event length the locus does not offer → False. The confident negative:
left-alignment moves an indel, it never changes how many bases the event adds or removes, so a
1 bp insertion cannot be a 2 bp deletion however it is spelled.
9. Otherwise → None. Same lengths, different content: one variant rotated inside a repeat, or
two different variants, and only the reference sequence can say which. The enricher can settle
it (seqrepo); the compiler holds no reference by charter (P2), so it withholds.
Public because both resolvers must agree on it: this module's injected-table path and the
deprecated DuckDB path in just-dna-enricher. Digest parity between the two is a documented
guarantee, so a filter applied on one side only would silently break it.
Source code in compiler/src/just_dna_compiler/resolution.py
841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 | |
undecided_reason ¶
Why hosting_verdict withheld — the clause a caller appends when the answer was None.
None has five causes and the message asserted one of them. Both reporting sites — this
module's expansion warning and the enricher's twin — said "the two spellings describe events of
the same size but different content, either one indel re-anchored inside a repeat or two different
variants", which is step 9's cause and false for the other four: a symbolic allele was never
compared at all (RM5), an all-* call observed nothing and an all-* locus offers nothing (RM59),
and a homozygous call carries no frame. Stating a cause the tier did not establish is the same
defect as the ([], None) collapse S20 was filed for — two ways of returning nothing rendered as
one sentence — and here it sends the reader to check a reference sequence for a row where no
reference could help.
Mirrors hosting_verdict's withholding branches in its order, so the two answer the same
question the same way; a test walks every None-producing shape and asserts the pairing, which is
what keeps a sixth branch from quietly inheriting a fifth's explanation.
The sets are built exactly as the predicate builds them — including dropping an empty ref rather
than folding "" in, which would put a member in locus that is neither observable nor an allele
and quietly defeat the branch below it. Keeping the two constructions identical is the entire point
of the pair.
Source code in compiler/src/just_dna_compiler/resolution.py
contradiction_reason ¶
Why hosting_verdict was a confident False — undecided_reason's twin, same contract (S85).
False has two causes and the enricher's message asserted one of them for both. Step 8 is the
event-length arm — a 1 bp insertion cannot be a 2 bp deletion however it is spelled — and "the
event sizes differ, which re-anchoring cannot change" is its reason. Step 6 is the substitution/MNV
arm, where the sizes are identical and what makes the verdict confident is the absence of a flank:
same-length alleles have no spelling freedom, so a genotype naming alleles the locus does not offer
is a real contradiction. Saying "the event sizes differ" there is a false claim about two 1 bp
substitutions, and it sends the author hunting a second variant sharing the rsID.
The case that made this worth splitting is a strand flip: a paper's supplementary published against
hg19 spells the submitted strand, so an authored A/G meets GRCh38's C>T. The verdict is correct
— on the strand it is written on, that genotype really cannot be hosted — and the remedy is a
column the old sentence never mentioned. So the flip is named where it is established, and the
step-6 fallback stays honest about what it did not establish rather than inventing a cause.
Mirrors hosting_verdict's False branches in its order, for the reason its twin does: a test
walks every False-producing shape and asserts the pairing, so a third arm cannot silently inherit
a second's explanation.
Source code in compiler/src/just_dna_compiler/resolution.py
genotype_fits ¶
Whether a locus can host genotype, collapsing "cannot tell" into "keep it".
The boolean face of hosting_verdict, kept because both resolvers and three call sites read it, and
because the collapse it performs is the module's existing doctrine: only a positive contradiction
rejects. An undecidable spelling is therefore kept, exactly as a locus with no recorded alleles is.
A caller that needs to report the difference asks hosting_verdict instead.
Source code in compiler/src/just_dna_compiler/resolution.py
frame_reading ¶
Which of a key's loci a genotype names, read in the frame of one of their refs (RM381), or None.
A source can spell every ALT of a site against one shared padded ref (the split Ensembl repo's
16:23635706 GTT>G / GT / GTTT), and a genotype authored from such a record keeps that frame
(G/GTTT, the 2 bp deletion and the 1 bp insertion). The readers hand each ALT on in its own
spelling (G>GT, GT>G, GTT>G), so a genotype must be read the same way: each allele is trimmed
against a candidate frame with alleles.trim_allele, the one trim the readers use, and the frame
names the loci whose own spelling each allele trims to. Pure string work, so it is offline too, and
the padded and the trimmed spelling of one event name the same locus (@one-normalizer-two-spellings).
The candidate frames are the loci's own refs (the padded site ref is one of them when the site has
the ALT that pads it; GTT>G does here). A frame the genotype's own allele equals is a ref/ALT
reading (G/GT in G is the insertion, in GT the deletion: both are kept, RM270's either-reading
rule); a frame in which every allele is an ALT is a compound het, and is read only when no ref/ALT
reading exists, so G/GT is never the two deletions of the frame GTT. None when no frame names
every allele: the caller asks hosting_verdict per locus, as before.
Source code in compiler/src/just_dna_compiler/resolution.py
1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 | |
site_verdicts ¶
hosting_verdict for each of a key's loci, the genotype read in its site's frame where it needs one (RM381).
Per locus first, as always. frame_reading then decides two cases the per-locus strings cannot:
- A padded genotype (its two alleles share a flank past the anchor,
GTT/GTTT,AGA/AGAGA): it names one record's ALT in that record's frame, so the loci the reading names host it and the other loci at the same site (chrom,start) do not. Per locus, the direction-blind string algebra would also accept the sibling it does not name (AGA/AGAGAreduces like the deletion). - No locus hosts it alone (a compound het spelled in a padded frame,
G/GTTTonGTT>G,GT,GTTT): the loci the reading names host it, one allele each.
Otherwise nothing moves: a caller-spelled G/GT keeps RM270's either reading, and a homozygote keeps
the one-to-many expansion (@membership-union, COMPILER.md § Resolution). A locus at another site
(a paralog, a PAR partner) always keeps its own verdict. Both resolvers and the compiler's expansion
and membership ask this, so the tiers read one genotype one way.
Source code in compiler/src/just_dna_compiler/resolution.py
spelling_caveat ¶
The clause to append when a "cannot host" verdict is really about allele spelling.
Empty for a locus spelled in nucleotides, which is nearly all of them, so a caller can append it unconditionally.
hosting_verdict reaches False for a substitution locus by set difference, and it is right to: a
substitution has no shared flank, so no spelling freedom, so A/G at a C>T locus is a real
contradiction and must stay one — that is what makes the strand-flip check sharp. But it reaches the
same False when the locus is spelled T>Y, and there the mismatch is between the cell and the
nucleotide alphabet, not between the genotype and the variant. Reporting the generic message there
sends the author to re-examine a genotype that was correct all along.
Three reasons reach this caveat, kept apart because what the author does next differs: an ambiguity
code is an uncertainty that can never be expanded into definite alleles (expanding N to A,C,G,T
asserts four alleles nobody stated), a well-formed symbolic allele is held by the grammar since
RM5 and so is never a spelling defect at all, and everything else non-nucleotide is a grammar gap.
None is repaired here — this tier reports.
* is the fourth classification and is excluded here (RM59), because hosting_verdict strips
it from both sides before comparing, so it can no longer contribute to the False this sentence
explains. Left in, it inverted the caveat's whole point: genotype=C/G at ref=A alts="T,*" is a
real genotype error, and the author was told to read it as a spelling problem instead.
Source code in compiler/src/just_dna_compiler/resolution.py
row_release ¶
The snapshot release a resolution row records as having answered it, or None when it records none.
Read by name rather than as a field: the column (source_release, RM373) is an optional derived one,
and a row written before it existed answers None, which is "not recorded", never "no release".
Source code in compiler/src/just_dna_compiler/resolution.py
placement_disagreements ¶
One rsID placed in two ways that do not agree, within one resolution.csv (RM374).
What one answer is. A variant_key is one subject, and a re-run of the enricher replaces a
subject's rows whole (ResolutionRow._KEY_RULE = "subject"), so the rows under one key are one answer
and locus_index only orders the loci inside it. An rsID mapping to several loci within that one
answer is the ordinary one-to-many case (@membership-union), never this finding. Two answers about
one rsID are two KEYS whose rows carry it: the rsID's own key, which is the full answer (every locus
the source placed it at that the authored allele can sit on), and a positional key whose rsID was
back-filled, which answers for the one locus its row was authored at. The rsID's own key holds the
loci the authored genotype can sit on, while the back-fill reads the source's unfiltered answer, so the
full answer is those loci plus the source_loci its rows record: every place the links offered in the
run that wrote them (RM387). Read without it, a positional row at a sibling locus the hosting filter
left out was a second placement, and --rederive wrote the same table again.
The finding. A positional answer whose locus is not among the full answer's loci: the table then
holds one identity at two placements, which is what merge-not-clobber leaves behind when the source
moved between runs (the 0.8 migration probe's rs761191455, 13:48041104 G>GG from the old Ensembl
release beside 13:48041103 T>TG from the new). A pseudoautosomal Y locus is compared as its X
partner, since the enricher keeps one contig of a PAR locus by default.
Where the table cannot tell, it withholds rather than refuse:
- no answer is keyed by the rsID itself — two positional rows labelled with one rsID may be two loci of a one-to-many rsID or one event spelled twice, and nothing here says which;
- one key is never reported against itself, even holding two rows at one
locus_index— a hand-filled table leaveslocus_indexat 0 for every locus of a one-to-many rsID, which looks exactly like two answers merged under one key; such a key is still the full answer the other keys are compared with; - an
ambiguousrow, whose rsID is a deterministic pick among candidates rather than a fact, and a row with nostart, which places nothing; - two answers whose spellings the enricher judged, one
left_aligned=trueand the otherfalse: within 0.8 a filled coordinate is written left-aligned, so a stale answer re-filled now would agree with the fresh one, and a true/false pair is one event spelled two ways in one release (an authored or snapshot spelling beside the respelled fill).--rederivewould rewrite the same table, so that is the spelling question, not this one.
Compared on (chrom, start), not alleles: a stale allele SET under one key is the membership check's
axis (_check_allele_membership), not a placement. GRCh38-bound like the rest of resolution (RM15).
A ladder: a warning in best_effort, a refusal under strict.
Source code in compiler/src/just_dna_compiler/resolution.py
1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 | |