just_dna_compiler.compiler.subjects¶
just_dna_compiler.compiler.subjects ¶
What a module is about: its genes, its loci and its variant identities, answered once (RM362).
"Which genes and loci is this module about" had several answerers that read different tables.
manifest.stats.genes and the enricher's gene scope read variants.csv plus every gene-bearing table
kind; the study-orphan check read variants.csv, haplotypes.csv, pharm_variants.csv and the rows a
meta member reached; and the five derived-row orphan checks read variants.csv alone and returned
nothing when it was absent. A diplotype-scored APOE module was then told its own gene_metrics.csv row
named "a gene this module never mentions" while its manifest listed APOE, and a PGx-only module was never
checked at all.
Every one of them now asks module_subjects, over the rosters below. Each orphan check still reads the
facet it always read (a gene, a chrom:start:ref position, or a variant_key/rsid identity), because
the join is a property of what its sidecar's source publishes; only the tables behind the facet moved.
A position is every spelling the module's own resolution gives a carried identity (2026-11-04). An
indel has several valid spellings, so a row authored at one (CPIC's right-shifted NUDT15 allele) and a
resolution.csv placing the same rsID at another (Ensembl's left-aligned one) are one place written
twice. The frequency pass asks gnomAD about the resolution row, so reading the authored spelling alone
named the pass's own row an orphan. identity_placements is the one lookup, the @membership-union
rule: every usable locus (resolution.usable_loci, the fill's predicate) the injected table files under
the row's variant_key or rsid, on the module's build. Only the injected table counts (Principle 2),
and only where the fill would read it: GRCh38, resolution on. module_subjects takes the union;
row_positions is the per-row answer for a check that attributes a finding to one row.
ModuleSubjects
dataclass
¶
ModuleSubjects(
genes: tuple[str, ...] = (),
positions: frozenset[str] = frozenset(),
identities: frozenset[str] = frozenset(),
placed: frozenset[str] = frozenset(),
genes_unknown: bool = False,
loci_unknown: bool = False,
resolved_positions: frozenset[str] = frozenset(),
)
The answer, in the three facets the checks join on, plus whether each is known at all.
genes is every gene cell, one per gene however it is written (spelling.gene_key, RM363) and in
its first spelling, in first-occurrence order of the tables handed in: the set
manifest.stats.genes publishes (sorted there), composite cells included, because a composite may
name the locus and splitting it would guess (S72, composite_gene_cell). gene_symbols is each cell
split on MULTI_SEP, the symbols a registry is asked about. A gene row matches on either.
genes_unknown / loci_unknown withhold: a roster table that is present and loaded no row makes the
module's subjects unknown, and naming every fact row an orphan would bury the load errors that are
the real report (the study check's carried_unknown, generalized).
gene_symbols
cached
property
¶
Each gene cell split on MULTI_SEP, de-duplicated by gene_key in first-occurrence order (P7).
names_gene ¶
Whether a gene is one this module mentions, as a cell or as a part of one, compared as
spelling.gene_key compares a gene (RM363).
Source code in compiler/src/just_dna_compiler/compiler/subjects.py
sits_at ¶
Whether some module row sits at this chrom:start:ref, alt ignored (a position-level join).
Source code in compiler/src/just_dna_compiler/compiler/subjects.py
carries ¶
Whether any of these identities (variant_key or rsid) is one a module row carries.
position_key ¶
The chrom:start:ref both sides of a position join are keyed by, or None without a start
(a row with no start sits nowhere: 19:None:None would match every unplaced row on 19).
Source code in compiler/src/just_dna_compiler/compiler/subjects.py
identity_placements ¶
identity_placements(
row: Any,
resolution: ResolutionTable | None,
genome_build: str,
) -> frozenset[str]
Every chrom:start:ref the module's own resolution.csv places this row's identity at.
The identity is the row's variant_key and its rsid, both looked up: the table is keyed by the
authored key, which an expanded variants.csv row no longer carries while it keeps the rsID. A
table row that places nothing (not_found, no chrom, another build) contributes nothing, by
usable_loci, the predicate both fills use. Empty with no table and on a non-GRCh38 module, where
the fills decline to join (RM15), so a caller passes None under --no-resolve.
Source code in compiler/src/just_dna_compiler/compiler/subjects.py
row_positions ¶
Where this one row sits, for a check that attributes a finding to a row (BA1, the study join
behind weights.parquet): its own position, plus the table's placement when that is one other place.
- The table places the row where it stands (same
chrom:start, and the samerefwhere the row states one): its own locus only, so one copy of a 1:N expansion is never handed a sibling's evidence. - The table places the identity at exactly one other position: that too. It is the same place in another spelling (an indel left-aligned against a right-shifted authored allele).
- Several other positions, or none: its own only. Which of several the row means is unknown, and
the house algebra withholds rather than hand it all of them.
module_subjectsstill takes the union, because "does the module sit here" asks about the module, not about one row.
Source code in compiler/src/just_dna_compiler/compiler/subjects.py
module_subjects ¶
module_subjects(
rows_by_table: Mapping[str, Sequence[Any]],
*,
unreadable: Iterable[str] = (),
resolution: ResolutionTable | None = None,
genome_build: str = DEFAULT_GENOME_BUILD,
) -> ModuleSubjects
The genes, positions and identities the module's rows name, over the two rosters above.
rows_by_table maps a CSV name to its rows, in the order the caller wants first occurrence read
({"variants.csv": variants, **kind_rows}); a table off the rosters is ignored, which is how a
non-kind table's gene stays out without each caller remembering it. The rows are read as handed
in, so a positional row the resolution fill has placed contributes its filled position: the compile
hands in post-fill rows and resolved variants, the pre-flight its post-fill view.
unreadable names tables that are present and loaded no row; one on a roster withholds that facet.
resolution is the module's injected table, or None where no resolution may be consulted
(--no-resolve): each locus row's identity_placements joins positions (the union, as
@membership-union compares), so a fact row at the table's spelling of a carried identity is not an
orphan. genome_build is the module's.