variants.csv

One row is one (locus, genotype) pair plus the prose conclusion for somebody carrying that call. It is the only table a consumer joins directly against a VCF genotype, and the only lead table carrying the general annotation axes — clinical significance, direction, effect size, callability. Its audience is two-sided, which is why it has more columns than anything else here: an author decides zygosity and prose, and a consumer's engine matches sample calls row by row.

The artifact splits it in two, and that asymmetry trips every consumer once. weights.parquet gets the authored surface except gene, phenotype and category; annotations.parquet gets nine columns including those three. So a gene symbol exists in the artifact only in annotations.parquet, and a consumer reading weights.parquet alone cannot see one. The two also disagree on how they store the call: annotations keeps the authored genotype string while weights keeps the alleles as a list plus a phased bool. The list is in authored order and never sorted, so a phased G|A and A|G stay two calls; sort it and you match a larger set than the module states (S30). just_dna_format.alleles.split_genotype is the split to call rather than rewrite.

start is the 1-based VCF position. Never subtract one from it. The bound is ge=0 rather than ge=1 because VCF permits POS 0, not because the column is ever interbase — every check and every minted identity reads it as VCF POS.

The symptom of getting the identity wrong is a silent miss, not an error. A row identified only by rsid matches at position level, so it answers for every allele at that locus; a row identified by chrom+start without ref cannot be checked for a wrong reference base by the compiler at all — only the enricher, holding a reference, can catch that.

Identity

Row model	VariantRow (just_dna_format.spec)
Becomes	weights.parquet, annotations.parquet — lead parquet: weights.parquet
Authored or derived	authored — a person writes it (a drafter may append rows)
Draftable	yes — draft can append rows
Drafted by	civic (civic_draft, judgement, matched on rsid, chrom, start, ref, alts) · clinvar (clinvar_draft, projection, matched on rsid, chrom, start, ref, alts) · mitomap (mitomap_draft, judgement, matched on chrom, start, ref, alts) · pubmind (pubmind_draft, projection, matched on rsid, chrom, start, ref, alts)
Natural key	variant_key, genotype
Fact signature	no
In the attestation binding	yes — manifest.inputs[]
Requires at least one of	rsid or chrom+start

Columns

Column	Type	Required	Values	Meaning
rsid	str | None	optional		dbSNP identifier, e.g. rs1801133
chrom	str | None	optional	one of: 1, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 2, 20, 21, 22, 3, 4, 5, 6, 7, 8, 9, MT, X, Y	Chromosome. A 'chr'/'CHR' prefix is accepted and stripped, and the mitochondrion may be written MT, chrMT, M or chrM — all fold to MT, which is what gets stored
start	int | None	optional		1-based genomic position (VCF POS convention), on the module's genome_build — the same convention as ResolutionRow.start, Ensembl, ClinVar and gnomAD. Do NOT subtract one: every check and every minted identity reads this column as VCF POS
ref	str | None	optional		Reference allele. Always spelled in bases — VCF's REF is a sequence, never symbolic; a structural allele belongs in alts
alts	str | None	optional		Alt allele(s), comma-separated. Bases, or a symbolic/structural allele carrying its length (, ); spell the bases out whenever the sequence is known
genotype	str	required		Slash-separated sorted alleles, e.g. A/G, or a single allele where the contig is hemizygous or haploid (non-PAR X/Y in males, homoplasmic MT). An allele is bases, or a symbolic/structural allele carrying its length — a heterozygous deletion sorts as /A. A pipe (A|G) is also accepted and records that the call was phased; with no phase-set column the order names no homolog, so it is phase recorded but unaddressable — say cis/trans in diplotypes.csv where a module needs it.
weight	float | None	optional		Score (positive=protective)
state	str	required	one of: alt, neutral, protective, ref, risk, significant	Direction of effect for this genotype. Current: risk, protective, neutral. Superseded, still valid and still read: significant — a significance claim rather than a direction, write stat_significance instead; alt/ref — genotype descriptors carrying no direction, which derive to direction=unknown. Prefer the orthogonal direction/stat_significance columns, which this one predates.
conclusion	str	required		Human-readable interpretation for this genotype
negatives	str | None	optional		Optional free-text adverse/antagonistic-pleiotropy counterpart to conclusion (e.g. a protective allele's known trade-off). Consumers ignore it when absent.
priority	str | None	optional		Priority level override
gene	str | None	optional		Gene symbol, e.g. MTHFR
phenotype	str | None	optional		Associated trait or phenotype
category	str | None	optional		Grouping category within the module
clinvar	bool | None	optional		Is this variant in ClinVar?
pathogenic	bool | None	optional		ClinVar pathogenic flag
benign	bool | None	optional		ClinVar benign flag
curator	str | None	optional		Curator override
method	str | None	optional		Annotation method override
direction	str | None	optional	one of: contested, neutral, protective, risk, unknown	Effect direction: one of protective|risk|neutral|unknown|contested. The sign of the reported estimate, whether or not it is established — a non-significant or borderline trend still has a direction, and stat_significance is what says how far to lean on it. unknown and contested are different answers: unknown is an absence, nobody assessed the sign; contested is a finding, the sources were consulted and they disagree about which way the effect runs. Neither is a sign you may not act on. Orthogonal to state, which predates both.
stat_significance	str | None	optional	one of: not_significant, significant, suggestive, unknown	Statistical significance: significant|suggestive|not_significant|unknown.
effect_size	float | None	optional		Published effect magnitude (unit given by effect_measure).
effect_measure	str | None	optional	suggested: HR, NR, OR, RR, beta, log(HR), log(OR)	Unit of effect_size, e.g. OR|HR|beta|RR (recommended; not a closed set).
effect_allele	str | None	optional		The allele that direction/weight/effect_size refer to — bases, or a symbolic/structural allele carrying its length (e.g. ).
flags	list[str] | None	optional	suggested: conditional, phased, pleiotropic	Open, multi-valued tag list (CSV: comma/semicolon/pipe-separated). Reserved tags the tooling acts on: conditional|phased|pleiotropic; other tags are allowed (surfaced as INFO).
trait_efo_id	str | None	optional		EFO/MONDO/OBA/HP trait ontology id(s), e.g. EFO_0004340 (matches just-prs).
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).
requires_callable	bool | None	optional		True when the absence of this variant is the informative call (recessive carrier, 'pathogenic variant absent' reassurance) — a consumer lacking callability data must then withhold the reference/absence conclusion, never assert it (no-call ≠ hom-ref).
acmg_sf	bool | None	optional		True when the gene is on the ACMG secondary-findings list.
actionability	str | None	optional	one of: actionable, descriptive, incurable, modifiable, pharmacogenomic, preventable, reproductive	Annotation-level actionability of the finding (ACTIONABILITY_SEED: actionable|preventable|pharmacogenomic|incurable|reproductive|descriptive|modifiable). A property of the gene–condition–intervention triad a consumer's disclosure policy may read; the format never decides disclosure.
callable_from	str | None	optional		Optional VCF field(s) a consumer establishes callability from, best written with the namespace (e.g. FORMAT/DP, FORMAT/GQ, FORMAT/FT, or FORMAT/DP|FORMAT/GQ). A declarative pointer, never an expression: it names where the evidence for 'this position was actually callable' lives, so a consumer can tell a confirmed negative from an uncovered one instead of reading both as reference. A bare key means unqualified — and INFO/DP is the cohort's combined depth, which says nothing about whether this sample was callable. Reference evidence usually arrives as a gVCF block (one record with END=), so a consumer finds it by interval containment rather than an equality join on position, and the block's floor is FORMAT/MIN_DP — a DP of 25 averaged over 14 bases is compatible with an uncovered base inside them.
quality_from	str | None	optional		Optional VCF field the min_quality floor is stated against, best written with the namespace (e.g. FORMAT/GQ, QUAL, FORMAT/DP). Same pointer grammar as source_field/callable_from; a pointer, never an expression. A bare key means unqualified, and INFO/MQ is a Float where FORMAT/MQ is an Integer. Prefer a per-sample confidence field: QUAL changes sign with the record (VCF 1.6.1.6 — prob(no variant) on a variant record, prob(variant) where ALT is '.'), so on a requires_callable row, whose evidence is the reference record, a high QUAL says the position is probably variant and the floor demands the opposite of what the row is about.
min_quality	float | None	optional		Inclusive floor on quality_from: withhold this row's conclusion where the consumer's value is below it. A consumer that cannot read the field withholds rather than asserting — an unevaluable floor is unknown, never satisfied.

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.