just_dna_enricher.ld_pairs¶
just_dna_enricher.ld_pairs ¶
ld-pairs — the computed LD pair behind a study measured on a proxy (0.8, RM331).
An author writes only StudyRow.proxy_rsid. r² has no meaning without its population, so the pass asks
a reference for r² and D′ between proxy and lead in the study's own ancestry, and writes
ld_pairs.csv, keyed (proxy_rsid, variant_key, ld_population). The reference is Ensembl REST's pairwise
LD endpoint over the 1000 Genomes phase 3 superpopulations (PT2 §4 question 4, accepted 2026-11-04),
probed by hand in docs/probes/LANES_0_8.md §2 before any of this was written. What the probe found, and
what each finding costs here:
- The five superpopulations are not in Ensembl's own LD population listing, yet the endpoint answers
for them. So this pass spells
1000GENOMES:phase_3:<CODE>itself from the closedancestryset, and a400 … population objectis a defect of that spelling (LdError), never a withhold. 200 []is not r² = 0. It comes back for a pair on two chromosomes and for the APOE pair in AFR, and lowering ther2floor does not bring a row back. It is written asnot_reported, r² empty.- A
400 … variation objectis an answer: the reference does not know one of the two rsIDs. It is written asrsid_unknown, and is neither retried nor read as an outage. - The response renames a merged rsID (asking rs1624712 answers as rs646776). The row stays keyed on
what the author wrote and
answered_rsidrecords the reference's name. The proxy goes first in the URL, sovariation1is the proxy; the probe's two orderings both kept the order asked. r2andd_primeare JSON strings, six decimals. Parsed to floats;str(float)writes the same six digits back, so the CSV round trip is exact.- The service flakes: HTML 500 pages and 37-second answers. 5xx, 429 and transport errors are
retried, then arrive as
LdUnavailable(@client-exception-contract); the timeout is long enough for the slow answer. 55,000 calls per hour; the pacing gate stays well under it.
A study naming several superpopulations, or none, gets its row with r² withheld and the reason (the
pm's setting: the lookup never picks a panel). A lead with no rsID (coordinate-authored, and no
back-filled rsID in resolution.csv) gets its row with lead_has_no_rsid: the endpoint takes rsIDs.
Neither consults the reference, so neither writes a licence row (@write-the-sourcerow).
Merge, never clobber (@sidecar-authoritative): a pair already in the file is not asked again; delete
the file to re-ask after a new release. --offline asks nothing and writes nothing: there is no LD
snapshot, and a row for a pair nobody asked about would claim an answer (@unreachable-not-absent).
Could-not-ask writes no row: when Ensembl stays down past the retries, the pairs already answered this
run are committed (each one cost a request, and the gap-fill resumes from them) and LdUnavailable is
raised naming the rest.
LdError ¶
Bases: RuntimeError
The LD pass could not do its work: a local table it cannot read, or an answer it cannot use.
LdUnavailable ¶
Bases: LdError
Ensembl could not be asked: a transport failure, or a 5xx/429 that outlasted the retries.
A subclass so an except LdError keeps catching it, and a caller that must tell a dead source from
bad data can, by type (@client-exception-contract).
LdRetired ¶
Bases: LdUnavailable, EndpointRetired
Ensembl answered HTTP 410: it retired the endpoint asked (RM354).
A fact about the source, not an outage, and not retried. An LdUnavailable so every existing handler
still catches it; the message says the endpoint moved rather than that the service was down.
LdAnswer
dataclass
¶
What the reference said about one pair: its rows, or that it does not know an rsID.
rows is the JSON array as served (possibly empty); unknown is the reference's own message when it
answered 400 for a variation it cannot fetch.
LdClient
dataclass
¶
LdClient(
endpoint: str = DEFAULT_REST_ENDPOINT,
species: str = "human",
timeout: float = LD_TIMEOUT,
client: Client | None = None,
gate: PacingGate | None = None,
)
Ensembl REST pairwise LD, with the four legs of the client contract.
A 200 is an answer (its JSON array); a 400 naming a variation is an answer too (LdAnswer.unknown);
every other 4xx (a 404 is a moved path or a wrong species, which a re-run repeats) and a 200 that is not
a JSON array of pairs is LdError; 5xx (EBI serves its 500 as an HTML page), 429 and transport
failures are retried and then LdUnavailable.
pairwise ¶
r² and D′ between proxy and lead in population, as the reference serves them.
Source code in enricher/src/just_dna_enricher/ld_pairs.py
release ¶
The Ensembl release answering, from /info/data ({"releases": [116]}).
Source code in enricher/src/just_dna_enricher/ld_pairs.py
LdPairsResult
dataclass
¶
LdPairsResult(
rows: list[LdPairRow] = list(),
written: list[LdPairRow] = list(),
unasked: list[PairKey] = list(),
unusable: list[tuple[PairKey, str]] = list(),
dropped: list[PairKey] = list(),
requests: int = 0,
dataset: str | None = None,
skipped_offline: bool = False,
)
What one ld-pairs run did.
enrich_ld_pairs ¶
enrich_ld_pairs(
spec_dir: Path,
*,
offline: bool = False,
write: bool = True,
client: LdClient | None = None,
) -> LdPairsResult
Fill ld_pairs.csv for every study row naming a proxy_rsid.
Source code in enricher/src/just_dna_enricher/ld_pairs.py
446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 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 | |