heteroplasmy.csv

One row is one mtDNA allele-fraction band, keyed on gene, reference sequence, tissue — and the variant. Every part of that key earned its place by breaking something without it.

The reference sequence is in the key because rCRS/NC_012920 and the legacy NC_001807 disagree on position, and genome_build does not disambiguate them. The variant identity is in the key because one mitochondrial gene carries several pathogenic variants with genuinely different thresholds — MT-TL1 has m.3243A>G and others, and binning them together is not conservative, it is wrong in both directions.

Tissue is optional and load-bearing, which is the uncomfortable combination. Heteroplasmy bins are tissue-conditional: a blood-derived fraction systematically under-represents the burden in affected tissue, and the penetrance threshold itself shifts, so the same fraction bins to different phenotypes across tissues. A heteroplasmy table with no tissue context is quietly unsafe — it will compile, and a consumer cannot tell which tissue its bins assume. State it.

Identity

Row model	HeteroplasmyRow (just_dna_format.binning)
Becomes	heteroplasmy.parquet — lead parquet: heteroplasmy.parquet
Authored or derived	authored — a person writes it (a drafter may append rows)
Draftable	yes — draft can append rows
Drafted by	no drafting provider targets this table — draft writes no row of it
Natural key	gene, reference_sequence, tissue, variant_key
Fact signature	no
In the attestation binding	yes — manifest.inputs[]

Columns

Column	Type	Required	Values	Meaning
measure_kind	str	defaulted	one of: allele_fraction	Fixed: allele_fraction
measure_min	float | None	optional		Inclusive lower bound; None = open below. On a continuous measure this is also the tie-break: a value two bins share belongs to the one with the greater measure_min.
measure_max	float | None	optional		Inclusive upper bound; None = open above. Inclusive on every measure_kind — on a continuous measure the next bin may start on it, and then that bin owns the value. Author the decimal you mean: a VCF Float is 32-bit, so a measured 0.3 reads as just above an authored 0.3 (and a measured 0.9 as just below). The comparison is done in float32 — narrow the bound the same way the measurement was narrowed — never with an epsilon.
measure_tiling	str | None	optional	one of: continuous, quantised	How this measure's axis is divided: quantised (a grid — two bins may not share an endpoint, and a hole narrower than one step is not a hole) or continuous (dense — adjacent bins share an endpoint and the higher one owns it, and any positive hole is reported). Leave empty for the kind's default: quantised for copy_number and repeat_count, continuous for allele_fraction and prs_percentile, neither for activity_score. Constant within a bin group. A group left empty on a kind that defaults to quantised is read as continuous anyway if it carries a fractional bound — nothing on a grid of whole numbers can hold one — and the compiler says when it did that. Note quantised assumes a grid of WHOLE numbers: there is no way to state a finer step, so on a bounded domain like allele_fraction it switches interior gap reporting off entirely.
direction	str | None	optional	one of: contested, neutral, protective, risk, unknown	Effect direction: protective|risk|neutral|unknown
clin_sig	str | None	optional	one of: affects, association, benign, conflicting, drug_response, likely_benign, likely_pathogenic, not_provided, other, pathogenic, protective, risk_factor, uncertain_significance	ClinVar/ACMG clinical significance (VEP CLIN_SIG vocabulary)
phenotype	str | None	optional		Associated trait or phenotype
trait_efo_id	str | None	optional		EFO/MONDO/OBA/HP trait ontology id(s)
conclusion	str	required		Human-readable interpretation for this bin
unresolved	bool	defaulted		True on the sentinel row a consumer selects when the measurement is absent.
source_field	str | None	optional		Optional VCF field the consumer extracts this measure from, best written with its namespace (e.g. FORMAT/REPCN, FORMAT/AF, INFO/CN|FORMAT/DS). A declarative pointer (field-name key, optionally qualified INFO/ or FORMAT/, optionally |-alternated), never an expression — an extraction hint; the measurement still comes from the consumer. A bare key means unqualified, and INFO and FORMAT define different fields under DP, AD, ADF, ADR, MQ, AF and CN.
source_element	str | None	optional	one of: annotated_alt, largest, largest_alt, reference, smallest, smallest_alt, sum, sum_alt	Which of source_field's values this bin is measured against, when the field carries more than one for a record: largest|largest_alt|smallest|smallest_alt|sum|sum_alt|annotated_alt|reference. A named rule, never an index. 'More than one' covers both the spec's multi-valued cardinalities (VCF Number=A/R/G/P/.) and a caller that packs several into one cell — ExpansionHunter's REPCN reports both repeat alleles as 17/42 — since the encoding is the caller's business and which value the annotation means is the module's. On a Number=R field the reference is element zero, which is why each ranging rule comes in a pair: the bare name counts it, the _alt name does not. Leave empty when the field carries a single value.
pmid	str | None	optional		Optional PubMed id grounding THIS boundary — the literature the threshold is drawn from. Free-form like StudyRow.pmid (9545397, [PMID: 9545397], a ;-joined list). The bin row cites; studies.csv describes.
gene	str	required		MT locus/gene, e.g. MT-TL1
rsid	str | None	optional		dbSNP id of the variant these bins are about, when it has one
chrom	str | None	optional		Contig (MT), for a position-only variant
start	int | None	optional		Position of the variant, e.g. 3243 for m.3243A>G
ref	str | None	optional		Reference allele, e.g. A
alts	str | None	optional		Alternate allele(s), e.g. G
reference_sequence	str	required		MT reference accession, part of the key, e.g. NC_012920.1 (rCRS)
tissue	str | None	optional		Tissue the bins assume, e.g. blood, muscle (bins are tissue-conditional)
assay_context	str | None	optional		Optional assay context, e.g. WGS, chip, amplicon

Generated from the row model at build time — reference.authoring_reference(), the same answer describe_table gives an authoring tool. Nothing on this page is hand-kept.