Skip to content

just_dna_enricher.enrich.rederive_words

just_dna_enricher.enrich.rederive_words

What the --rederive migration tells its operator: one sentence per case, in one place (RM394).

0.8 tells every consumer to run enrich --rederive after the snapshot switch, and the operator acts on what the run prints. Three of its reports had fewer arms than the cases they describe, so the words named a cause that had not happened and a remedy that did not apply:

  • the drift label had respelled / moved / undecided, so an allele the source added (A → A,T, 94 subjects across the reference examples) and an rsID it newly named both read "moved: the source names a different event";
  • the derived-layer currency line always said enrich --rederive, and when the release that is behind is the local snapshot, a re-derivation reads the same snapshot and prints the same line again;
  • the carry-forward said "no source could be asked" about every subject it kept, including ones a link answered and the hosting filter rejected.

Each report is a closed vocabulary of cases (frozenset, P6's idiom) and a map from case to sentence, and a test walks every case: the sentences are pairwise distinct, each case is reachable from the real decision, and each sentence names the remedy its case needs (@answered-is-not-absent: a verdict with several arms owes a reason with the same arms, pairwise distinct; @warning-text-is-api: the phrases are pinned there).

drift_case

drift_case(
    *,
    same_build: bool,
    rsids_before: frozenset[str | None],
    rsids_after: frozenset[str | None],
    kept: bool | None,
    nothing_new: bool | None,
) -> str

The DRIFT_CASES member for one subject, from what the run judged about its two answers.

kept is whether every recorded allele is the same event as a fresh one, and nothing_new the same the other way (events.covers, three-valued each). Another build is another answer. An unknown in the direction that decides the arm is undecided, never a guessed arm; Kleene, so a False either way still decides a move where the other direction is unknown. An rsID or build change whose events are not the same is moved, as it was before the arms split, so respelled reads exactly as in 0.8.

Source code in enricher/src/just_dna_enricher/enrich/rederive_words.py
def drift_case(
    *,
    same_build: bool,
    rsids_before: frozenset[str | None],
    rsids_after: frozenset[str | None],
    kept: bool | None,
    nothing_new: bool | None,
) -> str:
    """The `DRIFT_CASES` member for one subject, from what the run judged about its two answers.

    `kept` is whether every recorded allele is the same event as a fresh one, and `nothing_new` the same
    the other way (`events.covers`, three-valued each). Another build is another answer. An unknown in
    the direction that decides the arm is `undecided`, never a guessed arm; Kleene, so a `False` either
    way still decides a move where the other direction is unknown. An rsID or build change whose events
    are not the same is `moved`, as it was before the arms split, so `respelled` reads exactly as in 0.8.
    """
    if not same_build:
        return "moved"
    events = False if False in (kept, nothing_new) else None if None in (kept, nothing_new) else True
    if rsids_before != rsids_after:
        # The rsID changed, which is known whatever the events: only the same events make it a naming
        # change, and anything else stays the change in the answer it always read as.
        if events is not True:
            return "moved"
        return "gained_rsid" if rsids_before == frozenset({None}) else "renamed"
    if events is True:
        return "respelled"
    if kept is True and nothing_new is False:
        return "gained_allele"
    if kept is False and nothing_new is True:
        return "lost_allele"
    return "undecided" if events is None else "moved"

carry_sentence

carry_sentence(
    reason: str, count: int, examples: str
) -> str

One carried group: its count, its reason's sentence, and the subjects it names.

Source code in enricher/src/just_dna_enricher/enrich/rederive_words.py
def carry_sentence(reason: str, count: int, examples: str) -> str:
    """One carried group: its count, its reason's sentence, and the subjects it names."""
    return f"{count} subject(s): {CARRY_SENTENCES[reason]} ({examples})"

currency_case

currency_case(
    recorded: str,
    current: str,
    local: str | None,
    comparable: bool,
) -> str

The CURRENCY_CASES member for a superseded derived leg (recorded != current).

local is the label of the snapshot this run read for the source, None when it read none, and comparable whether that label is in the form current is written in. Unknown is never guessed into an arm: it names both remedies.

Source code in enricher/src/just_dna_enricher/enrich/rederive_words.py
def currency_case(recorded: str, current: str, local: str | None, comparable: bool) -> str:
    """The `CURRENCY_CASES` member for a superseded derived leg (`recorded != current`).

    `local` is the label of the snapshot this run read for the source, `None` when it read none, and
    `comparable` whether that label is in the form `current` is written in. Unknown is never guessed
    into an arm: it names both remedies.
    """
    if local is None or not comparable:
        return "snapshot_unread"
    if local == current:
        return "table_behind_snapshot"
    if local == recorded:
        return "snapshot_behind"
    return "both_behind"

currency_remedy

currency_remedy(
    case: str, *, lane: str, local: str | None
) -> str

The sentence for one case, with the lane and the snapshot's label filled in.

Source code in enricher/src/just_dna_enricher/enrich/rederive_words.py
def currency_remedy(case: str, *, lane: str, local: str | None) -> str:
    """The sentence for one case, with the lane and the snapshot's label filled in."""
    return CURRENCY_REMEDIES[case].format(lane=lane, local=local or "none read")

by_case

by_case(cases: Mapping[str, str]) -> dict[str, list[str]]

case -> [subject, …] in the registry's sorted order, each list in the order given.

Source code in enricher/src/just_dna_enricher/enrich/rederive_words.py
def by_case(cases: Mapping[str, str]) -> dict[str, list[str]]:
    """`case -> [subject, …]` in the registry's sorted order, each list in the order given."""
    grouped: dict[str, list[str]] = {}
    for subject, case in cases.items():
        grouped.setdefault(case, []).append(subject)
    return {case: grouped[case] for case in sorted(grouped)}