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. |
|
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.