just_dna_enricher.enrich.subjects¶
just_dna_enricher.enrich.subjects ¶
The subjects a run asks about: collect_subjects over every table that names a variant, the
authored-pair check, and the pseudoautosomal representative (RM260 split this out of the former
single-file enrich.py).
Subject
dataclass
¶
Subject(
variant_key: str,
rsid: str | None,
chrom: str | None,
start: int | None,
ref: str | None,
alts: str | None,
constraint: str | None,
origin: str,
)
One row asking for a coordinate, normalized across the tables allowed to ask.
Resolution used to read variants.csv alone, so a PGx module — which by design carries no
variants.csv (one CSV = one concern) — enriched to an empty resolution.csv and shipped with no
coordinates at all. The chain itself was never variant-specific; only its input was. Normalizing
to a subject lets pharm_variants.csv and haplotypes.csv through the unchanged resolver,
caches, ordering and back-fill.
constraint is whatever the row knows about which alleles must be present at the locus, fed to
the shared hosting_verdict predicate so a one-to-many rsID drops the loci the row cannot be
about (and reports, rather than drops, the ones it cannot decide):
- a
VariantRow/PharmVariantRowsupplies its genotype (C/T); - a
HaplotypeRowsupplies its single defining allele (G) — the same membership question asked of one allele instead of two, which is why it reuses the same predicate rather than a parallel one; None(aPharmVariantRowwith no authored genotype) constrains nothing and keeps every locus.
collect_subjects ¶
collect_subjects(
spec_dir: Path,
variants: list[VariantRow],
genome_build: str = "GRCh38",
*,
include_study_proxies: bool = True,
) -> list[Subject]
Every row in the spec that needs a coordinate, variants.csv first, deduped by variant_key.
Order and precedence are load-bearing. variants.csv goes first so that when the same variant is
named by two tables, the SNP row wins — it is the only one carrying alts, which is a resolution
fact and therefore decides the compiled bytes. Letting a PGx row win would move an already
compiled module's artifact.digest, the same hazard the link ordering in the chain below exists
to avoid. Within that, first occurrence wins, so the emitted order is the authored order.
The PGx tables key without alts: a pharm annotation or a haplotype junction matches a
variant at chrom:start:ref regardless of allele. Mixing that up would mint a VRS allele id for a
row that never named an allele. heteroplasmy.csv is the exception and keys with alts,
because its own variant_key does — see the block below.
All three tables carry variant_key as a stamped field since 0.6 (RM43) — it was a property
on two of them and absent from HaplotypeRow entirely, which is why the block below derives one
inline. The stamped value is the same expression, frozen at load from the authored columns, so
nothing here changes; and PharmVariantRow.alts, added by the same item, is deliberately not read
here because it is compiler-filled data rather than an authored fact.
A study's LD proxy is a subject too, last (RM331, 0.8). StudyRow.proxy_rsid names the variant a
study measured in place of the row's lead, and the compiler checks the row's effect_allele against
the proxy's resolved alleles — which exist only if this asks for them. A proxy is usually not a
module variant, so it is admitted here, after every table above: one that is also a module variant
keeps that row's subject, and the precedence above is untouched. It carries no constraint: the
compile check is what judges the allele, and filtering loci by it here would drop the very loci that
check needs. include_study_proxies=False is for a pass about the module's own variants (the GWAS
Catalog pass), which a proxy is not. The study rows themselves stay out, as before: a study row
references a variant the module already carries.
An invalid study row does not stop the run, unlike the tables above. Those are coordinate
sources, so a run that cannot read one has nothing honest to resolve; studies.csv only adds
proxies. Its valid rows' proxies are asked for and the rest are named in one warning — the compile
refuses those rows anyway, and validate names each.
Source code in enricher/src/just_dna_enricher/enrich/subjects.py
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 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 | |
study_proxy_rsids ¶
The rsIDs this module asks about ONLY as a study's LD proxy (RM331, 0.8).
collect_subjects admits a proxy last and dedupes, so a subject still carrying the studies.csv
origin is one no table naming a module variant asked for. Its resolution.csv row exists for the
compiler's allele check alone, and a pass that reads resolution.csv as the module's own loci (the
frequency and clinical-assertion passes) leaves these rsIDs out, or it would spend requests on loci
the module does not annotate and write fact rows the compile reports as orphans. A proxy's rows are
keyed by the rsID itself (an rsID subject's variant_key), so a pass filters on variant_key, which
never drops a coordinate-authored module variant whose back-filled rsid happens to be the same.
Source code in enricher/src/just_dna_enricher/enrich/subjects.py
meta_member_rsids ¶
Every rsID a meta.csv member names, sorted and de-duplicated (0.8, PT2 §5 B1 step 5).
Read off the variant_key= and rsid= conditions whose value is an rsID. These are asked, never
resolved: the currency pass puts them to dbSNP beside the rows resolution.csv carries, so one
variant written under two keys (IL6R's rs8192284, merged into rs2228145) is caught where NCBI is
the oracle, and no row is written for an id the module does not carry.
Source code in enricher/src/just_dna_enricher/enrich/subjects.py
select_par_representative ¶
select_par_representative(
loci: list[dict], *, build: str = "GRCh38"
) -> tuple[list[dict], list[dict]]
Split a one-to-many expansion into (kept, y_par_twins), preferring the X spelling.
A pseudoautosomal locus is one place on two contigs — PAR1 and PAR2 are the stretches X and Y share, so dbSNP maps one rsID to both and the expansion emits two rows for one finding. Probed 2026-08-04, every annotation source places PAR annotation on X and only the coordinate resolver disagrees: ClinVar has zero records in either PAR on Y (all 677 of its Y records lie outside the PARs), gnomAD v4 excludes the Y PAR from its callset outright (X PAR1 640000-641500 serves 880 variants, the same interval on Y serves none), and the ClinGen Allele Registry does mint a Y allele id but leaves the record a stub — a dbSNP cross-reference and nothing else, no ClinVar, no gnomAD, and a title that degrades to the bare genomic HGVS. Standard GRCh38 analysis sets then hard-mask the Y PAR, so the Y row cannot match a call either.
So keeping it records the sources' own convention, not the consumer's analysis set — which is
the distinction that makes this the enricher's decision to take (Principle 2: this is the only tier
permitted to hold a source convention). The caller keeps both with keep_par_twin.
This selects; it does not repair — the same contract as the allele-aware hosting_verdict
filter beside it. Every authored value is untouched, and the caller reports what was left out.
Two things it deliberately will not do:
- Fuse on geometry alone. A Y locus is dropped only when its
par_partnerX position is present and carries the sameref/alts. Partner coordinates say "same place"; they do not say "same variant", and a same-place different-allele pair is a real finding rather than a duplicate — so it is kept, and both rows survive. - Judge a gene. The verdict is per locus, because a real gene can straddle a PAR boundary: XG runs out of PAR1 (X:2,751,798-2,816,500 crosses the boundary at 2,781,479) and SPRY3 runs into PAR2 (X:155,612,298-155,782,459 crosses 155,701,383). Any module- or gene-scoped policy would be wrong for half of either one.