just_dna_format.frequency¶
just_dna_format.frequency ¶
The source-independent allele-frequency table (0.5).
frequencies.csv is the variant-level sibling of resolution.csv: a persisted table of
already-fetched population-frequency facts that the compiler consumes instead of querying any
source. Filling it is the job of the separate just-dna-enricher network tier (its gnomAD pass); the
compiler only reads it, materializes frequencies.parquet, and hashes it by facts.
Three parties share the definition, like ResolutionRow: the enricher produces it, the compiler
consumes it, a verify-only client may re-check it. Dependency-light — pydantic + the stdlib
vocab leaf.
One row is one (allele, ancestry group) pair. Frequency is meaningless without saying whose
frequency, and ancestry group, sex, and dataset are three separate axes (Principle 5), so they are
three separate things here rather than one overloaded population label: the group is population,
the release is dataset, and sex-stratified counts are simply not carried in this pass (folding
nfe_XX into population would be exactly the state-overloading mistake 0.3 unwound).
Counts, not a float. allele_count/allele_number are the integers the source reports;
allele_frequency is a derived property, materialized as a real Float64 in the parquet so a
consumer does no arithmetic, but never stored in the CSV. Integers round-trip through CSV exactly,
while a stored float invites formatting drift (0.0482 vs 0.048200000000000004) — a Principle 7
idempotency hazard for the price of duplicating one fact in two columns. faf95 is the one
unavoidable stored float, and it is canonicalized on write and covered by a round-trip test.
FrequencyRow ¶
Bases: BaseModel
One (allele, ancestry group) frequency fact, keyed by the coordinate-derived variant_key.
Standalone (not an AuthoredModel), for the same reason ResolutionRow is: a frequency is a
machine-produced reference fact, not an authored annotation, so it must not inherit the annotation
validators or the reserved-namespace guard's authoring semantics. It does close its namespace with
extra="forbid", so a typo'd column in frequencies.csv is caught rather than silently dropped.
allele_frequency
property
¶
AC/AN — derived, never stored. None when either count is absent, and when AN is 0.
An AN of 0 is a real and common state (a group with no coverage at this site), and it means
"no information", not "frequency zero" — returning None keeps a consumer from reading an
undefined ratio as a confident absence.