Skip to content

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/PharmVariantRow supplies its genotype (C/T);
  • a HaplotypeRow supplies 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 (a PharmVariantRow with 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
def 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.
    """
    subjects: list[Subject] = [_subject_of_variant(v, genome_build) for v in variants]

    pharm_path = spec_dir / "pharm_variants.csv"
    if pharm_path.exists():
        rows, errors, _ = load_csv_rows(pharm_path, PharmVariantRow, "pharm_variants.csv")
        if errors:
            raise EnrichmentError(f"pharm_variants.csv is invalid: {errors[0]}")
        subjects.extend(
            Subject(r.variant_key, r.rsid, r.chrom, r.start, r.ref, None, r.genotype, "pharm_variants.csv")
            for r in rows
        )

    hap_path = spec_dir / "haplotypes.csv"
    if hap_path.exists():
        rows, errors, _ = load_csv_rows(hap_path, HaplotypeRow, "haplotypes.csv")
        if errors:
            raise EnrichmentError(f"haplotypes.csv is invalid: {errors[0]}")
        subjects.extend(
            Subject(
                derive_variant_key(r.rsid, r.chrom, r.start, r.ref),
                r.rsid,
                r.chrom,
                r.start,
                r.ref,
                None,
                r.allele,
                "haplotypes.csv",
            )
            for r in rows
        )

    # `heteroplasmy.csv` is the third table that can ask, and it was left out of the 0.5 round for no
    # reason anyone recorded: its coordinates are optional exactly like the PGx ones, so an
    # rsid-authored heteroplasmy module resolved to nothing and the compiler's positional-joinability
    # warning would have named a gap no tool could close.
    #
    # Two differences from the blocks above, both load-bearing. It **passes `alts`**, because
    # `HeteroplasmyRow.variant_key` mints one the same way `VariantRow` does (verified equal for both
    # the rsid and the coordinate shape), and a subject whose key carries an allele must carry the
    # allele. That makes the key **build-dependent**, so the load takes `genome_build` — the RM36
    # trap, and the reason the two blocks above rightly do not. Its `constraint` is `None`: a
    # heteroplasmy row is a measurement band over a locus, not a claim about a genotype, so it
    # constrains no locus out of a one-to-many expansion.
    het_path = spec_dir / "heteroplasmy.csv"
    if het_path.exists():
        rows, errors, _ = load_csv_rows(
            het_path, HeteroplasmyRow, "heteroplasmy.csv", genome_build=genome_build
        )
        if errors:
            raise EnrichmentError(f"heteroplasmy.csv is invalid: {errors[0]}")
        subjects.extend(
            Subject(
                r.variant_key
                or derive_variant_key(r.rsid, r.chrom, r.start, r.ref, r.alts, build=genome_build),
                r.rsid,
                r.chrom,
                r.start,
                r.ref,
                r.alts,
                None,
                "heteroplasmy.csv",
            )
            for r in rows
        )

    studies_path = spec_dir / "studies.csv"
    if include_study_proxies and studies_path.exists():
        rows, errors, _ = load_csv_rows(studies_path, StudyRow, "studies.csv")
        if errors:
            logger.warning(
                "studies.csv has %d invalid row(s), and any LD proxy on them is not asked for (first: %s); "
                "`just-dna-compiler validate` names each.",
                len(errors),
                errors[0],
            )
        subjects.extend(
            Subject(r.proxy_rsid, r.proxy_rsid, None, None, None, None, None, "studies.csv")
            for r in rows
            if r.proxy_rsid is not None
        )

    deduped: dict[str, Subject] = {}
    for s in subjects:
        deduped.setdefault(s.variant_key, s)
    return list(deduped.values())

study_proxy_rsids

study_proxy_rsids(spec_dir: Path) -> frozenset[str]

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
def study_proxy_rsids(spec_dir: Path) -> frozenset[str]:
    """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.
    """
    variants, _errors, _warnings = load_spec_variants(spec_dir)
    subjects = collect_subjects(spec_dir, variants, spec_genome_build(spec_dir))
    return frozenset(s.rsid for s in subjects if s.origin == "studies.csv" and s.rsid)

meta_member_rsids

meta_member_rsids(spec_dir: Path) -> list[str]

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
def meta_member_rsids(spec_dir: Path) -> list[str]:
    """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.
    """
    path = Path(spec_dir) / META_CSV
    if not path.is_file():
        return []
    rows, errors, _ = load_csv_rows(path, MetaRow, META_CSV)
    if errors:
        raise EnrichmentError(f"{META_CSV} is invalid: {errors[0]}")
    named = {
        value
        for row in rows
        for member in parse_members(row.members)
        for column, value in member.conditions
        if column in ("variant_key", "rsid") and _RSID_VALUE.match(value)
    }
    return sorted(named)

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_partner X position is present and carries the same ref/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.
Source code in enricher/src/just_dna_enricher/enrich/subjects.py
def 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_partner` X position is present
      *and* carries the same `ref`/`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.
    """
    by_place: dict[tuple[str, int, str, frozenset[str]], dict] = {}
    for locus in loci:
        chrom, start = normalize_chrom(locus.get("chrom")), locus.get("start")
        if chrom is None or start is None:
            continue
        ref, alts = _locus_alleles(locus)
        by_place[(chrom, int(start), ref, alts)] = locus

    kept: list[dict] = []
    twins: list[dict] = []
    for locus in loci:
        chrom, start = normalize_chrom(locus.get("chrom")), locus.get("start")
        partner = par_partner(chrom, int(start), build=build) if chrom == "Y" and start is not None else None
        ref, alts = _locus_alleles(locus)
        if partner is not None and (partner[0], partner[1], ref, alts) in by_place:
            twins.append(locus)
        else:
            kept.append(locus)
    return kept, twins