Skip to content

just_dna_format.derive

just_dna_format.derive

Legacy → 0.3 column derivations (the "upgrade" back-population) and the read-time aliases that let a consumer see the orthogonal 0.3 axes even on a 0.1/0.2 module that only set state.

Kept as a leaf module (it imports nothing from spec) so both spec — for its effective_* accessors and upgraded() — and external consumers (the marketplace revalidate/needs_upgrade flow) can import these pure functions without an import cycle.

state and the ClinVar booleans stay required/authoritative for 0.2 backward-compat (CONSTITUTION Principle 3 forbids making a required field optional inside a major); the new axes are optional, with these derivations as their fallback. Every function here is total and idempotent: applying it to an already-derived value is a no-op (CONSTITUTION Principle 7). See the "Upgrade derivation" section of docs/COMPILER.md.

direction_from_state 

direction_from_state(
    state: str, weight: float | None = None
) -> str

Derive direction from the legacy state (plus the weight sign when informative).

significant carries no direction on its own, so it is refined from the weight sign when present (positive → protective, negative → risk); otherwise it, and the retired alt/ref descriptors, map to the honest unknown the old enum lacked.

Source code in schema/src/just_dna_format/derive.py 
63
64
65
66
67
68
69
70
71
72
73
74
def direction_from_state(state: str, weight: float | None = None) -> str:
    """Derive `direction` from the legacy `state` (plus the `weight` sign when informative).

    `significant` carries no direction on its own, so it is refined from the weight sign when present
    (positive → protective, negative → risk); otherwise it, and the retired `alt`/`ref` descriptors,
    map to the honest `unknown` the old enum lacked."""
    if state == "significant" and weight is not None:
        if weight > 0:
            return "protective"
        if weight < 0:
            return "risk"
    return _STATE_TO_DIRECTION.get(state, "unknown")

stat_significance_from_state 

stat_significance_from_state(state: str) -> str

Derive stat_significance from the legacy state (only significant is informative).

Source code in schema/src/just_dna_format/derive.py 
77
78
79
def stat_significance_from_state(state: str) -> str:
    """Derive `stat_significance` from the legacy `state` (only `significant` is informative)."""
    return _STATE_TO_STAT_SIGNIFICANCE.get(state, "unknown")

trimmed_state 

trimmed_state(direction: str) -> str

Project a direction back into the trimmed legacy state set {protective, risk, neutral}.

unknown and contested both collapse to neutral — the legacy set has no member for either. This is the derived, deprecated state an upgraded module emits. See _DIRECTION_TO_STATE for why every vocabulary member needs an explicit entry there rather than relying on the default.

Source code in schema/src/just_dna_format/derive.py 
82
83
84
85
86
87
88
89
def trimmed_state(direction: str) -> str:
    """Project a `direction` back into the trimmed legacy `state` set {protective, risk, neutral}.

    `unknown` and `contested` both collapse to `neutral` — the legacy set has no member for either.
    This is the derived, deprecated `state` an upgraded module emits. See `_DIRECTION_TO_STATE` for
    why every vocabulary member needs an explicit entry there rather than relying on the default.
    """
    return _DIRECTION_TO_STATE.get(direction, "neutral")

clin_sig_from_booleans 

clin_sig_from_booleans(
    pathogenic: bool | None,
    benign: bool | None,
    clinvar: bool | None,
) -> str | None

Derive a clin_sig tier from the lossy legacy ClinVar booleans.

pathogenic → pathogenic; benign → benign; in-ClinVar with neither flag → uncertain_significance; otherwise None (nothing to say). Lossy by construction — legacy cannot recover likely_pathogenic/likely_benign.

Source code in schema/src/just_dna_format/derive.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
def clin_sig_from_booleans(pathogenic: bool | None, benign: bool | None, clinvar: bool | None) -> str | None:
    """Derive a `clin_sig` tier from the lossy legacy ClinVar booleans.

    `pathogenic` → pathogenic; `benign` → benign; in-ClinVar with neither flag →
    uncertain_significance; otherwise None (nothing to say). Lossy by construction — legacy cannot
    recover `likely_pathogenic`/`likely_benign`."""
    if pathogenic:
        return "pathogenic"
    if benign:
        return "benign"
    if clinvar:
        return "uncertain_significance"
    return None

pathogenic_from_clin_sig 

pathogenic_from_clin_sig(
    clin_sig: str | None,
) -> bool | None

The pathogenic boolean implied by a clin_sig tier: True for the pathogenic tiers, else None (the tier is silent on the boolean — we never fabricate a False a curator did not state).

Source code in schema/src/just_dna_format/derive.py 
107
108
109
110
111
112
def pathogenic_from_clin_sig(clin_sig: str | None) -> bool | None:
    """The `pathogenic` boolean implied by a `clin_sig` tier: True for the pathogenic tiers, else
    None (the tier is silent on the boolean — we never fabricate a `False` a curator did not state)."""
    if clin_sig in {"pathogenic", "likely_pathogenic"}:
        return True
    return None

benign_from_clin_sig 

benign_from_clin_sig(clin_sig: str | None) -> bool | None

The benign boolean implied by a clin_sig tier: True for the benign tiers, else None.

Source code in schema/src/just_dna_format/derive.py 
115
116
117
118
119
def benign_from_clin_sig(clin_sig: str | None) -> bool | None:
    """The `benign` boolean implied by a `clin_sig` tier: True for the benign tiers, else None."""
    if clin_sig in {"benign", "likely_benign"}:
        return True
    return None