Skip to content

just_dna_format.resolution

just_dna_format.resolution

The source-independent resolution table (0.5).

resolution.csv is a persisted table of already-resolved variant facts (rsid ↔ coordinate) that the compiler consumes instead of querying any reference — so the compiler owns no source convention (Ensembl, DuckDB, provisioning) and stays strictly inject-only (CONSTITUTION Principle 2). The table is filled before compilation by anything: an on-disk cache, a live query, or a human. Filling it is the job of the separate just-dna-enricher network tier; the compiler only reads it.

Three parties share this one definition (why it lives in the schema tier, like manifest.FileEntry): the compiler consumes it, the enricher produces it, and a verify-only client may re-check it. It is dependency-light — pydantic + the stdlib vocab leaf, no polars/duckdb/httpx.

A one-to-many rsid (one authored variant_key expanding to several loci) is encoded as several rows sharing variant_key with distinct locus_index, so the compiler reproduces the expansion without any source knowledge. The fact columns feed integrity.resolution_signature; the provenance columns are deliberately excluded from it (a human-filled and an Ensembl-filled table with identical facts must hash equal — see RESOLUTION_FACT_FIELDS).

ResolutionRow

Bases: PairedFields

One resolved (or attempted) locus for an authored variant, keyed by the frozen variant_key.

Standalone (not an AuthoredModel/VariantRow subclass): a resolution fact is not an annotation row and must not inherit VariantRow's annotation validators. It reuses the shared rsid grammar so an rsid here obeys the same rule everywhere, and closes its namespace with extra="forbid" like the authored models so a typo'd column in resolution.csv is caught, not silently dropped.

authored_coordinate_key

authored_coordinate_key(
    chrom: str | None, start: int | None, ref: str | None
) -> str

The authored coordinate an authored_event verdict judged, as one comparable string (RM375).

Written by the enricher beside the verdict and recomputed by the compiler from the row it would apply the verdict to, so the two sides cannot spell it two ways: the contig folded (normalize_chrom), ref uppercased, an absent cell an empty segment (coordinate_key).

Source code in schema/src/just_dna_format/resolution.py
def authored_coordinate_key(chrom: str | None, start: int | None, ref: str | None) -> str:
    """The authored coordinate an `authored_event` verdict judged, as one comparable string (RM375).

    Written by the enricher beside the verdict and recomputed by the compiler from the row it would
    apply the verdict to, so the two sides cannot spell it two ways: the contig folded
    (`normalize_chrom`), `ref` uppercased, an absent cell an empty segment (`coordinate_key`).
    """
    return coordinate_key(normalize_chrom(chrom), start, ref.upper() if ref else None)

source_loci_cell

source_loci_cell(
    places: Iterable[tuple[str | None, int | None]],
) -> str | None

Places as resolution.csv source_loci spells them (RM387): chrom:start, comma-joined, sorted.

The one spelling both tiers use: the enricher writes the cell through it and the compiler reads it back with split_source_loci. The contig is folded (normalize_chrom) and the order is the sort of (chrom, start), so one set of places is one string whatever order the links answered in. A place with no contig or no start places nothing and is left out; nothing left is None.

Source code in schema/src/just_dna_format/resolution.py
def source_loci_cell(places: Iterable[tuple[str | None, int | None]]) -> str | None:
    """Places as `resolution.csv` `source_loci` spells them (RM387): `chrom:start`, comma-joined, sorted.

    The one spelling both tiers use: the enricher writes the cell through it and the compiler reads it
    back with `split_source_loci`. The contig is folded (`normalize_chrom`) and the order is the sort of
    `(chrom, start)`, so one set of places is one string whatever order the links answered in. A place
    with no contig or no start places nothing and is left out; nothing left is `None`.
    """
    folded = {
        (chrom, int(start))
        for raw, start in places
        if start is not None and (chrom := normalize_chrom(raw)) is not None
    }
    return ",".join(f"{chrom}:{start}" for chrom, start in sorted(folded)) or None

split_source_loci

split_source_loci(
    cell: str | None,
) -> frozenset[tuple[str, int]]

The (chrom, start) places a source_loci cell names, or an empty set for an empty cell (RM387).

Raises ValueError on a member that is not chrom:start with a non-negative integer start, which is what the field validator reports at load, so a cell that loaded always parses here.

Source code in schema/src/just_dna_format/resolution.py
def split_source_loci(cell: str | None) -> frozenset[tuple[str, int]]:
    """The `(chrom, start)` places a `source_loci` cell names, or an empty set for an empty cell (RM387).

    Raises `ValueError` on a member that is not `chrom:start` with a non-negative integer start, which is
    what the field validator reports at load, so a cell that loaded always parses here.
    """
    if not cell:
        return frozenset()
    out: set[tuple[str, int]] = set()
    for member in cell.split(","):
        match = _SOURCE_LOCUS.fullmatch(member.strip())
        folded = normalize_chrom(match.group(1)) if match else None
        if match is None or not folded:
            raise ValueError(
                f"source_loci member {member!r} is not `chrom:start` (a contig, a colon, a 1-based "
                f"position); the cell is comma-joined places, e.g. `5:500,6:600`"
            )
        out.add((folded, int(match.group(2))))
    return frozenset(out)