Skip to content

studies.csv

One row is one (rsid, pmid) evidence link. Not a description of a study — a link between a variant and a paper, so one study supporting five variants is five rows, and a variant with three citations is three.

Grounding evidence is mandatory, and that is the point of the table. A binning table that states thresholds with no study rows behind them warns in both modes, strict and best-effort: a bin boundary is a claim about the world and an unsourced one is the kind this format refuses to publish quietly.

A row cites when its claim is finer-grained than this table's key. studies.csv is keyed on (rsid, pmid), so when a claim is per-bin or per-genotype rather than per-variant, the citation lives on the claiming row and this table describes the study instead. The two are not alternatives; asking which one a citation belongs in is asking how specific the claim is.

A work PubMed does not index is cited as pmid = NONE, with its DOI in doi. Never the DOI in pmid: its digits read as PubMed ids, so 10.1101/2025.03.01.640000 would cite six unrelated papers, and the cell is refused for it. NONE makes doi mandatory, and the rule is the same on every table that cites with a pmid (the binning kinds, pharm_variants.csv), each of which carries a doi beside it since 0.8. The symptom of skipping it is a refusal naming the DOI you wrote; the fix is moving it one column over. When the preprint is later published, write its PMID instead of NONE (just-dna-enricher hint citation --doi finds it where PubMed has one).

A sample size is a count of something, and the something is a cell (0.8). sample_size is the total analysed, cases included, and sample_unit says whether it counts people or lives: a parental-lifespan study counts two lives per participant, so the same number means half as many genotyped people. A size without its unit is refused, and so is an n_cases larger than the size.

phenotype_class says what was measured; study_design says how. A case-control GWAS of centenarians and a Cox model of parental lifespan are both "GWAS" in study_design, and the class is what separates them. The recommended twelve are v2's; a token outside them is kept and warned about once, because the commonest cause is a second spelling of one of them.

ancestry is a code, population is a description. ancestry takes the 1000 Genomes superpopulation codes and nothing else, listing each one a trans-ethnic study pooled; the cohort's own name (an Ashkenazi study is EUR there) goes in population. An unstated ancestry is unknown, which is why a locus whose evidence is partly unstated is never reported as European-only.

An age-stratified estimate is one row per band. age_min/age_max bound the band in years, an empty bound leaves it open (Timmers 2019's top parental band is 80 and over), and age_of says whose age it is: a parental-lifespan study bands by the parent's age at death, not the participant's.

A stratum is a pair. stratum names the modifier an estimate was measured within and stratum_level the level (sex/male, parent_sex/father); one without the other is refused. One pair holds one modifier, so "hypertensive men" keeps its second modifier in statistical_test.

A study measured on an LD proxy is filed under the lead, with the proxy in proxy_rsid. The effect_allele is then the proxy's allele, and that is what the compiler checks it against; filed under the proxy's own rsID instead, the row would be an orphan. Write only the rsID: r² means nothing without its population, so it is computed rather than typed.

effect_measure is the kind of estimate, effect_unit what one unit of it is. A beta can be in years of parental lifespan per allele, Martingale residuals or a hazard; write the unit as the paper does. A variant's row in weights.parquet carries it only when every study row of that variant that states a unit states the same one, so two units for one variant leave it empty rather than picking one.

The symptom of confusing it with literature.csv is a dropped row. literature.csv is machine-produced and keeps every article it found; the compiler discards an uncited literature row when nothing references it. studies.csv is the authored side and is never dropped. If a citation disappeared from a compile, it was in the wrong one of the two.

Identity

Row model StudyRow (just_dna_format.spec)
Becomes studies.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 variant_key, pmid
Fact signature no
In the attestation binding yes — manifest.inputs[]

Columns

Column Type Required Values Meaning
rsid str | None optional dbSNP identifier or variant key
chrom str | None optional Chromosome (for position-only variants)
start int | None optional 1-based position, VCF POS convention (position-only variants) — do not subtract one
ref str | None optional Reference allele (position-only variants)
pmid str required PubMed ID or reference — free-form, must be non-empty
population str | None optional Study population
p_value str | None optional Raw p-value string (free-form)
conclusion str | None optional Study-specific conclusion
study_design str | None optional e.g. meta-analysis, GWAS
stat_significance str | None optional one of: not_significant, significant, suggestive, unknown Per-study statistical significance: significant|suggestive|not_significant|unknown. The authors' verdict at the threshold of the study's own test, never a grade on a scale this format picks: a pre-specified look-up of one variant in an independent cohort carries no genome-wide multiple-testing burden, so one that passes its test is significant, at P 0.002 as much as at 5e-8. To compare rows on one common scale, threshold p_value_num instead; it keeps the number this level summarises.
effect_size float | None optional Per-study 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, open).
effect_allele str | None optional The allele this study's effect_size is stated relative to — bases, or a symbolic/structural allele carrying its length (e.g. ). Absent means the study did not state one, which is not the same as the reference allele.
trait_efo_id str | None optional EFO/MONDO/OBA/HP trait ontology id(s) for this study.
statistical_test str | None optional Which analysis produced this row's p_value/effect_size — the test or model, and what it was adjusted for, e.g. Fisher's exact (allelic) or logistic regression adjusted for age and sex. Free text. study_design describes the study; this describes the analysis, and one study may report several. Absent means the paper's analysis was not recorded, never that it had only one.
confidence str | None optional How far the citing source stands behind this evidence link, in ITS OWN units and unconverted (CIViC's submitted/accepted, a review-star count). Meaningless without confidence_unit beside it, and refused without one.
confidence_unit str | None optional Which instrument confidence is measured on, e.g. civic_evidence_status. Required whenever confidence is set: a magnitude with no unit beside it is a value nothing can read, and this format has paid for that once already on weight.
doi str | None optional Digital Object Identifier — wider than pmid (covers preprints/books/datasets with no PubMed id). Free-form, kept verbatim; a validator may cross-fill doi↔pmid.
provenance_quote str | None optional Optional keyword phrase / literal passage locating this study's claim in the cited article's fulltext. Human-legible; a validator confirms fulltext-contains, yes/no.
provenance_regex str | None optional Optional regex locating the claim in fulltext — a declarative pattern grammar (Principle 1: data, not code), matched consumer-side by a linear-time/ReDoS-safe engine.
curator str | None optional Who located this row's provenance quote/regex — a name, handle, or model id, resolvable against the manifest's authorship. Row-level because real work is mixed at row granularity: a human may read a review while an agent traverses its citations, in one module, in one pass. Records the distribution of labour so a reviewer can route scrutiny; it does not move responsibility, which the human author holds regardless.
p_value_num float | None optional The p-value as a number, so it can be sorted and thresholded — p_value above is a free-form string and cannot be. In (0, 1]: a p-value of exactly 0 is a source's own underflow, not a probability, so it is rejected rather than stored as a confident zero.
sample_size int | None optional How many were analysed for this row's estimate, cases included, in the unit sample_unit names (required beside it).
sample_unit str | None optional one of: individuals, lives What sample_size counts: individuals, or lives where a study counts each participant's parents (two lives per participant).
n_cases int | None optional How many of the analysed were cases, for a case-control or extreme-phenotype design. Never more than sample_size when both are stated.
phenotype_class str | None optional suggested: BIOMARKER, DISEASE_DEPLETION, EVOLUTIONARY, EXTREME_SURVIVAL_CC, FAMILIAL, HEALTHSPAN, MR, MULTIVARIATE_AGEING, OWN_SURVIVAL, PARENTAL_LIFESPAN, RARE_BURDEN, VIABILITY_AF Which outcome this study measured, e.g. PARENTAL_LIFESPAN, EXTREME_SURVIVAL_CC, HEALTHSPAN (recommended, open; another token warns and is kept). study_design describes the study; this describes what it measured, and one paper may measure several.
ancestry list[str] | None optional one of: AFR, AMR, EAS, EUR, SAS The 1000 Genomes superpopulation(s) this estimate was measured in (AFR, AMR, EAS, EUR, SAS; multi-valued — a trans-ethnic study lists each code). population beside it stays free text for the cohort. Absent means unstated, never 'any'.
age_min float | None optional Lower bound of the age band this estimate covers, in years. Empty: open below.
age_max float | None optional Upper bound of the age band this estimate covers, in years. Empty: open above.
age_of str | None optional one of: parent, participant Whose age the band is: participant, or parent for a parental-lifespan study banded by the parent's age at death.
stratum str | None optional The modifier this estimate was measured within, e.g. sex, parent_sex, smoking. Free text, and only with stratum_level beside it.
stratum_level str | None optional The level of stratum this estimate was measured in, e.g. male, father, never.
proxy_rsid str | None optional The dbSNP id of the variant this study measured, when it is an LD proxy of the row's variant. effect_allele is then an allele of the proxy. r² and its population are computed, never authored.
effect_unit str | None optional The unit of effect_size, verbatim as the paper states it, e.g. years of parental lifespan per allele, -ln HR per allele. Free text. A sign convention is not a unit: effect_allele with direction already says which way.

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.