just_dna_enricher.grch37¶
just_dna_enricher.grch37 ¶
The old assembly: rs-number recovery and a wrong-build diagnosis (RM48).
An author curating from older literature has hg19/GRCh37 coordinates and the module must be GRCh38. Nothing in these four packages converts, so the conversion happens off-tool and lands as an ordinary authored coordinate carrying no provenance at all. This module is the online half of the answer; the offline half (a position past the end of its contig, a contig only one build names) lives in the compiler, where it needs neither network nor sequence.
Recovery, never liftover — and the reporter argued their own request down. If the paper gives an
rs-number, liftover is unnecessary and strictly worse: authoring the rs-number produces the
independent second value resolution._verify cross-examines. So liftover is only reachable where
there is no rs-number and only an old coordinate — and in exactly that case the lifted coordinate
becomes the row's sole identity with nothing to check it against, which is a generator of
unverifiable-by-construction identities: the hazard class behind the 3,038-variant off-by-one this
tree has already paid for once. Recovering the rs-number converts an unverifiable coordinate into a
verifiable one, using machinery the enricher already has.
No chain file, no provisioned asset, no new licence. The roadmap's stated blocker was that
rs-number recovery needs "either an hg19-keyed dbSNP surface or a chain file … i.e. the whole
snapshot apparatus for one authoring convenience". Probed 2026-08-13 and false: Ensembl runs a
permanent GRCh37 REST service at grch37.rest.ensembl.org, same API shape, serving both dbSNP
variants (/overlap/region) and reference bases (/sequence/region). The same request that answers
"which rs-numbers sit here on GRCh37" also discriminates the builds outright — 7:140453135..140453137
is CAC on GRCh37 and GTT on GRCh38.
Live-only, skipped offline. This is an authoring-time convenience; nothing in a compile depends
on it, and a second whole-genome variant snapshot in the old assembly is exactly the apparatus worth
not building. --offline reports skipped_offline, which is a first-class answer and never a pass.
It reports; it writes nothing. Filling the recovered rs-number would make resolution verify a
value against the very service that produced it (hints.REDUNDANCY_BEARING, and rsid is
identity_bearing in lookup._REFUSAL_BY_COLUMN). The author types the rs-number; a later enrich
resolves it through the ordinary chain and resolution.csv's source column records which link
answered. Provenance goes there, never into an authored coordinate.
Grch37Client
dataclass
¶
Grch37Client(
settings: Grch37Settings = Grch37Settings(),
gate: PacingGate | None = None,
_client: Client | None = None,
)
Bases: Withholding
Paced, retrying access to the GRCh37 REST service. Every read is three-valued.
Hold one per session, the way LookupClients says to: the PacingGate state and the connection
pool are both thrown away by a client built per question, and the gate is what keeps a panel-sized
run inside Ensembl's published budget.
variants_at ¶
dbSNP variants overlapping chrom:start on GRCh37, or None for could-not-ask.
[] is an answer — the service was reached and records nothing there — while None means the
question never completed. A 400 counts as an answer: this service 400s on a contig it does not
have and on a position past the end of one, and both of those really are "GRCh37 has nothing
for you here", stated by the service rather than guessed at by us. Any other status — a 429, a
403, a 404, a 410 — answered nothing, and is None (RM361: every 4xx was [] before).
Only dbSNP features with an rs id are returned. The endpoint also serves HGMD-PUBLIC records
(CM112509 at 7:140453136), and an id that is not an rs-number is not what this recovers.
Source code in enricher/src/just_dna_enricher/grch37.py
reference_bases ¶
The GRCh37 bases over the 1-based inclusive span chrom:start..end. Three-valued.
Bases are an answer; "" is also an answer — the service was reached and has no sequence
there — and None means the question never completed. Collapsing the middle case into None
is precisely the S20 inversion this module's docstring cites as its design rule, and it is
reachable with ordinary data rather than only under an outage: 20:63500000 sits inside
GRCh38's chromosome 20 and past the end of GRCh37's, so the wrong-build case itself 400s
here. Reported as "could not be asked", it would tell an author to re-run for an answer the
service had already given.
start/end are the 1-based VCF convention this whole codebase stores, passed through
unconverted — the instinctive -1 is the off-by-one that cost 3,038 rows once already.
Source code in enricher/src/just_dna_enricher/grch37.py
RsidRecovery
dataclass
¶
RsidRecovery(
chrom: str,
start: int,
outcome: str,
ref: str | None = None,
alts: str | None = None,
rsids: list[str] = list(),
candidates: list[dict] = list(),
note: str = "",
_overlapping: int = 0,
)
What the GRCh37 service said about one old coordinate. Advisory; nothing is written.
BuildDiagnosis
dataclass
¶
BuildDiagnosis(
variant_key: str,
chrom: str,
start: int,
claimed: str,
reason: str,
grch37_bases: str | None = None,
rsids: list[str] = list(),
shift_claimed: int | None = None,
)
One ref-mismatched row, and what GRCh37 says about the same coordinate.
Only produced for rows that already failed the reference-base check, which is what bounds the
cost: verify_reference_alleles is the filter, and a module whose refs all agree with GRCh38
makes no request here at all.
BuildDiagnosisResult
dataclass
¶
BuildDiagnosisResult(
diagnoses: list[BuildDiagnosis] = list(),
not_checked: str | None = None,
examined: int = 0,
total: int = 0,
)
The wrong-build pass's answer, with a reason when it did not run and what it looked at.
An empty diagnoses list otherwise says two opposite things — "asked, and nothing pointed at
another build" and "never asked" — which is the same defect clin_sig_not_checked exists to
prevent. not_checked is None exactly when the pass ran.
examined/total are the denominator, published for the reason RM44 states: a finding that
quantifies over a subset has to say what the subset was, or a reader takes it for the whole.
recover_rsid ¶
recover_rsid(
chrom: str,
start: int,
*,
ref: str | None = None,
alts: str | None = None,
client: Grch37Client | None = None,
offline: bool = False,
) -> RsidRecovery
Which rs-number GRCh37 dbSNP records at this old coordinate.
The match is anchored on the authored position: a candidate must start exactly at start, and
must carry the authored ref (and every authored alt) when those are given. Anchoring is what
keeps this honest — a variant that merely overlaps the position is a different event, and
accepting one would hand back an rs-number for a variant the author never meant.
The consequence to know: an indel is recorded at one anchor, Ensembl's, and that anchor may be
neither VCF's left-aligned spelling nor HGVS's first changed base. Ensembl pads a record whose
alleles mix a deletion and an insertion at its own anchor: CFTR F508del (rs113993960) is
TCTT/T/TCTTCTT at GRCh37 7:117199645, one base right of VCF's ATCT>A at 117199644 and one left of
HGVS's 117199646. Asked at either of those, it comes back none rather than wrong. A none whose
note counts overlapping records is therefore a reason to retry at a neighbouring anchor, never a
statement that dbSNP records nothing. And without ref, a padded indel's VCF position recovers
whatever record starts there, which is the anchor base's (rs1801178 under F508del): the text says
so. That is RM31's one-indel-several-spellings problem, and this reports the shorter search rather
than reconciling frames it was not given (RM444).
Source code in enricher/src/just_dna_enricher/grch37.py
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 | |
diagnose_wrong_build ¶
diagnose_wrong_build(
mismatches: Sequence[RefMismatch],
*,
client: Grch37Client | None = None,
offline: bool = False,
limit: int = DEFAULT_DIAGNOSIS_LIMIT,
) -> BuildDiagnosisResult
Do these ref-mismatched rows read as GRCh37 coordinates in a GRCh38 module?
Runs only on rows the reference-base check already rejected, which is the whole cost control: the expensive question is asked of a set someone else has already narrowed to the suspicious rows.
The asymmetry is worth stating rather than implying generality: verify_reference_alleles skips
any build refget_accession has no table for, so a RefMismatch only ever exists for a GRCh38
module — which makes "the other assembly" always GRCh37 here, not a parameter.
Three tiers of evidence, and the message says which one it has. Neither the mismatch nor this
diagnosis is repaired: an authored ref and an authored coordinate are the evidence that
something upstream went wrong, and rewriting either destroys it.
Source code in enricher/src/just_dna_enricher/grch37.py
summarize_build_diagnoses ¶
summarize_build_diagnoses(
diagnoses: Sequence[BuildDiagnosis],
*,
examples: int = 3,
) -> list[str]
One line per reason class, with a count, a few named rows, and which reading wins.
Grouped by reason and never by row: a panel authored from pre-GRCh38 literature produces one of these per variant, and the shared cause is the only actionable thing in the pile.