Skip to content

just_dna_format.meta

just_dna_format.meta

The meta-table, meta.csv (0.8): RM28's combinations, RM323's per-locus facts, RM324's tier, RM327's per-trait judgements, RM330's sex and the drug a row is about, in one table.

A row maps a composite statement to a finding and/or the per-locus facts. A composite statement is one or more members, each an item of a single-statement table, written in one grammar:

table[column=value, column=value]

joined by & at bracket depth 0 in one members cell. A concrete row is the selector over its table's full key (variants[variant_key=rs429358, genotype=C/C]), a locus is variants[variant_key=rs10455872], a named allele is allele_function[gene=APOE, allele=ε4] and a tag set is variants[flags=legacy_longevitymap]. The decisions behind every rule here are dated lines under RM28, RM323, RM324, RM327 and RM330 in ROADMAP_0_8.md, fixed in proposals/PROPOSAL_0_8_PT2.md §3 items 1–8.

This module holds what needs no other table: the row model, the parser, the key, and the precedence rank of one member against one row it matches. Expansion — which rows a member matches, and what the compile writes — is the compiler's (just_dna_compiler.compiler.meta), because it needs the module's other tables in hand.

Dependency-light like the rest of the format tier: re, pydantic, and the member tables' models.

MetaSelectorError

Bases: ValueError

A members cell the grammar refuses. A ValueError, so pydantic reports it as a row error.

MetaMember

Bases: NamedTuple

One parsed member: the table it names and its column=value conditions, in authored order.

canonical

canonical() -> str

The member with its conditions sorted by column — one spelling per member, for the key.

Source code in schema/src/just_dna_format/meta.py
def canonical(self) -> str:
    """The member with its conditions sorted by column — one spelling per member, for the key."""
    inner = ", ".join(f"{column}={value}" for column, value in sorted(self.conditions))
    return f"{self.table}[{inner}]"

MetaRow

Bases: CitationPair, AuthoredModel

One row of meta.csv: a composite statement mapped to a finding and/or per-locus facts.

The key is the normalized member set plus trait_efo_id plus sex (§3 item 4) plus drug (the lead, 2026-11-04), so A & B and B & A are one key, refused as a duplicate, while a male row and a female row for one member set are two statements, and so are an azathioprine row and a mercaptopurine row for one TPMT × NUDT15 phenotype pair (CPIC states one recommendation per thiopurine).

Inherits AuthoredModel (reserved-namespace guard, and the shared trait_efo_id/direction validators).

selectable_columns

selectable_columns(table: str) -> frozenset[str]

The columns a member over table may name: the authored ones, plus variant_key.

variant_key is compiler-stamped on every table that carries it, so an authored-only roster would refuse the canonical locus member variants[variant_key=…]. It is the one stamped column admitted; the rest (authored_ident, the expansion marker) describe what the compiler did, not the row.

Source code in schema/src/just_dna_format/meta.py
def selectable_columns(table: str) -> frozenset[str]:
    """The columns a member over `table` may name: the authored ones, plus `variant_key`.

    `variant_key` is compiler-stamped on every table that carries it, so an authored-only roster would
    refuse the canonical locus member `variants[variant_key=…]`. It is the one stamped column admitted;
    the rest (`authored_ident`, the expansion marker) describe what the compiler did, not the row.
    """
    model = META_MEMBER_TABLES[table]
    columns = set(authored_field_names(model))
    if "variant_key" in model.model_fields:
        columns.add("variant_key")
    return frozenset(columns)

parse_members

parse_members(cell: str) -> list[MetaMember]

Parse a members cell into its members, in authored order. Raises MetaSelectorError.

Bracket-aware: an & or | inside a value is data (RM253's DPYD names, a phased genotype). The shared MULTI_SEP splitter is never used on this cell. At depth 0, | and the words OR/NOT are refused by name, as the maintainer's bounds (no OR, no negation): rows are already a disjunction.

Source code in schema/src/just_dna_format/meta.py
def parse_members(cell: str) -> list[MetaMember]:
    """Parse a `members` cell into its members, in authored order. Raises `MetaSelectorError`.

    Bracket-aware: an `&` or `|` inside a value is data (RM253's DPYD names, a phased genotype). The
    shared `MULTI_SEP` splitter is never used on this cell. At depth 0, `|` and the words `OR`/`NOT` are
    refused by name, as the maintainer's bounds (no OR, no negation): rows are already a disjunction.
    """
    outside = _depth0_text(cell)
    if "|" in outside or _DEPTH0_OR.search(outside):
        raise MetaSelectorError(
            f"members {cell!r}: OR is out of bounds — rows are already a disjunction, so write one row "
            f"per alternative"
        )
    if _DEPTH0_NOT.search(outside) or "!" in outside:
        raise MetaSelectorError(
            f"members {cell!r}: negation is out of bounds, because negation over an open set cannot be "
            f"checked"
        )
    members = [_parse_member(part) for part in _split_depth0(cell)]
    canon = [member.canonical() for member in members]
    if len(set(canon)) != len(canon):
        raise MetaSelectorError(f"members {cell!r} names one member twice")
    return members

split_members

split_members(cell: str) -> list[str]

The members of a members cell, each verbatim as authored (stripped), in authored order.

The texts a finding or the manifest quotes back to the author. Call parse_members first (or hold a row that validated): this splits without judging.

Source code in schema/src/just_dna_format/meta.py
def split_members(cell: str) -> list[str]:
    """The members of a `members` cell, each verbatim as authored (stripped), in authored order.

    The texts a finding or the manifest quotes back to the author. Call `parse_members` first (or hold
    a row that validated): this splits without judging.
    """
    return [part.strip() for part in _split_depth0(cell)]

normalize_members

normalize_members(cell: str) -> str

The row key's member half: members sorted, conditions sorted within each, joined by &.

A & B and B & A are one key, as are [gene=X, allele=Y] and [allele=Y, gene=X]. The authored cell is kept verbatim on the row (P7: reverse writes back what the author wrote); this is a stamped column beside it.

Source code in schema/src/just_dna_format/meta.py
def normalize_members(cell: str) -> str:
    """The row key's member half: members sorted, conditions sorted within each, joined by ` & `.

    `A & B` and `B & A` are one key, as are `[gene=X, allele=Y]` and `[allele=Y, gene=X]`. The authored
    cell is kept verbatim on the row (P7: `reverse` writes back what the author wrote); this is a stamped
    column beside it.
    """
    return " & ".join(sorted(member.canonical() for member in parse_members(cell)))

allele_bearing

allele_bearing(member: MetaMember) -> bool | None

Does this member fix an allele, so a direction on its row says which allele it is about?

Three-valued (§3 item 6). True: a variants/pharm_variants member with a genotype condition, a diplotypes member naming either haplotype, or any allele_function member. None: a bare variants[variant_key=…] locus, which bears an allele only when every row of that locus states the same effect_allele — a fact of the module's data, decided at compile. False: anything else (a tag selector, a gene, a phenotype), which a direction row refuses.

Source code in schema/src/just_dna_format/meta.py
def allele_bearing(member: MetaMember) -> bool | None:
    """Does this member fix an allele, so a `direction` on its row says which allele it is about?

    Three-valued (§3 item 6). `True`: a `variants`/`pharm_variants` member with a `genotype` condition,
    a `diplotypes` member naming either haplotype, or any `allele_function` member. `None`: a bare
    `variants[variant_key=…]` locus, which bears an allele only when every row of that locus states the
    same `effect_allele` — a fact of the module's data, decided at compile. `False`: anything else (a tag
    selector, a gene, a phenotype), which a `direction` row refuses.
    """
    columns = member.columns()
    if member.table == "allele_function":
        return True
    if member.table == "diplotypes":
        return bool(columns & {"haplotype_a", "haplotype_b"})
    if "genotype" in columns:
        return True
    if member.table == "variants" and columns == {"variant_key"}:
        return None
    return False

member_rank

member_rank(
    member: MetaMember, target: Mapping[str, Any]
) -> tuple[int, int]

How specific member is about target, a row of its own table it matches (its key cells).

(3, 0) a concrete row key: the conditions name every key column the row fills (an empty drug or clinical_context on a diplotype need not be named). (2, 0) a locus: variant_key alone, on a table that carries one. (1, n) a selector with n conditions. Compared as tuples, which is the maintainer's order: a concrete key, then a locus, then more conditions, then fewer. Equal ranks are incomparable, never ordered by anything else.

Source code in schema/src/just_dna_format/meta.py
def member_rank(member: MetaMember, target: Mapping[str, Any]) -> tuple[int, int]:
    """How specific `member` is about `target`, a row of its own table it matches (its key cells).

    `(3, 0)` a **concrete row key**: the conditions name every key column the row fills (an empty
    `drug` or `clinical_context` on a diplotype need not be named). `(2, 0)` a **locus**: `variant_key`
    alone, on a table that carries one. `(1, n)` a **selector** with `n` conditions. Compared as tuples,
    which is the maintainer's order: a concrete key, then a locus, then more conditions, then fewer.
    Equal ranks are incomparable, never ordered by anything else.
    """
    model = META_MEMBER_TABLES[member.table]
    key_fields: tuple[str, ...] = model._KEY_FIELDS  # type: ignore[attr-defined]
    filled = {name for name in key_fields if target.get(name) is not None}
    columns = member.columns()
    if filled and filled <= columns:
        return (3, 0)
    if member.table in LOCUS_TABLES and columns == {"variant_key"}:
        return (2, 0)
    return (1, len(columns))