A1/A2 conventions for plink output

[jeromekelleher]

Compatibility report — A1/A2 convention for plink-1 output

Question

vcztools currently writes .bed/.bim using plink 1.9's minor-allele convention (A2 = REF, A1 = the most-frequent non-REF allele) computed by Writer._compute_alleles in vcztools/plink.py:106–143. Computing this requires a full pass over call_genotype per variant.

The plink-2-style REF/ALT ordering (A1 = ALT, A2 = REF) as the desired default. This report addresses the deeper question: can we drop the minor-allele path entirely, or must we keep it as an opt-in for some consumers?

TL;DR

Yes — minor-allele can be dropped entirely. None of the consumers in the IO study (admixture, bolt, flashpca, gcta, king, regenie, plink 1.9, plink 2) require A1 to be the minor allele as a semantic precondition. The convention is plink 1.9's historical default, not a correctness assumption. Three caveats — see "Risks" below.

Per-consumer findings

For each tool, the question is: does the tool produce wrong output if A1 is the ALT allele rather than the minor allele?

plink 1.9

• Built-in default: re-orders A1/A2 in memory by frequency on every load unless --keep-allele-order (or --real-ref-alleles). The on-disk bytes never change — only the in-memory association.
• Output files (--freq, --assoc, --logistic, etc.) reflect the in-memory ordering, so an unflagged plink 1.9 run on our output gets minor-allele A1 in its outputs regardless of what we wrote on disk.
• Verdict: insensitive. Pipelines that pass --keep-allele-order see exactly the labelling we wrote; pipelines that don't get plink-1.9's frequency-reordered view. Both are correct interpretations of the same .bed bytes.

plink 2

• REF/ALT-aware throughout. .bim format spec (cog-genomics) literally defines A1 = ALT, A2 = REF.
• Verdict: prefers REF/ALT ordering — minor-allele is the legacy choice it actively documents away from.

REGENIE

• Default for .bed input: A2 is treated as the reference allele (so A1 is the effect/ALT). Confirmed by REGENIE docs: --ref-first exists to opt out into "first allele = reference".
• Effect sizes are always reported for "allele 1" (the effect/non-reference allele). Sign flips with allele labelling but the analysis is correct.
• Verdict: insensitive to minor-vs-major, prefers A1 = ALT (which is the new default) — that's its own default expectation.

BOLT-LMM

• Manual (v2.5, §9.1): "ALLELE1: first allele in bim file (usually the minor allele), used as the effect allele". The parenthetical is descriptive, not normative.
• Effect sizes are always for ALLELE1. Sign reflects whichever allele is in column 5 of .bim.
• Verdict: insensitive. Reading the manual carefully: BOLT reports an effect size relative to whatever ALLELE1 is. It does not internally check or assume that ALLELE1 is the minor allele.

GCTA

• Core pipelines (--make-grm, --reml, --pca, --make-grm-bin, etc.) standardise genotypes per-variant before use. Standardisation is invariant to allele labelling (the variance is the same whether you count copies of A1 or A2).
• Verdict: insensitive for the analyses the IO study covers. (--cojo and friends consume summary statistics with explicit allele columns — orthogonal to .bed encoding.)

KING

• Designed as an allele-frequency-free kinship estimator (Manichaikul et al. 2010). Explicitly engineered not to rely on population allele frequencies — that's its headline feature versus plink's IBD estimator.
• Verdict: insensitive by construction.

flashpca

• Standardises genotypes per-variant before SVD. PCA has inherent sign ambiguity (eigenvectors are determined up to sign), so the choice of which allele is "counted" is irrelevant to the partition of variance.
• Cross-dataset projection (--project) requires consistent allele coding between training and projection sets — but any consistent coding works; REF/ALT is in fact more stable across cohorts than minor-allele (the latter can flip between cohorts if a variant sits near 50% MAF).
• Verdict: insensitive for self-contained PCA; REF/ALT-favourable for cross-cohort.

ADMIXTURE

• Computes ancestry proportions from genotype dosages via a symmetric likelihood (the model has no inherent direction — swapping allele labels relabels the population-frequency parameters but yields the same ancestry assignments).
• Verdict: insensitive.

Cross-cutting observations

• The minor-allele convention is a labelling preference, not a correctness invariant. Every tool in the IO study either re-derives frequencies internally or operates symmetrically on allele labels.
• plink 1.9 itself doesn't preserve our on-disk labelling by default — it reorders unless --keep-allele-order. So even the "stay compatible with plink 1.9" framing dissolves: under default plink 1.9 invocations, the minor-allele relabelling happens at plink load time regardless of what we wrote.
• REF/ALT is the cohort-stable choice. A variant at 49.8% MAF in cohort A and 50.2% in cohort B has different "minor" alleles in the two cohorts but the same REF/ALT. Meta-analysis pipelines routinely have to "harmonise" minor-allele labels back to REF/ALT before merging — REF/ALT-only output sidesteps this.

Argument for dropping minor-allele entirely

1. Performance. Eliminates the per-variant bincount over 2 × num_samples haploid calls. For the streaming source this collapses init time from O(N × S) to O(N); for write_plink it's a smaller win (genotypes are read for encoding anyway) but still a non-trivial reduction in arithmetic.
2. Streaming-source simplification. Drops _a12_filled, the per-chunk write-through cache, eager_a12 parameter ambiguity, and the §7 "internal design notes" complexity in the streaming spec. The a12 array becomes a static (N, 2) int8 derived from variant_allele at construction.
3. Modern toolchain alignment. plink 2, REGENIE, BOLT-LMM-by-effect-labelling, and the meta-analysis ecosystem already favour REF/ALT.
4. Reproducibility across cohorts. REF/ALT is stable; minor-allele isn't.
5. Maintenance burden. Keeping compute_a12_minor_allele as an opt-in means: two code paths, two test classes (TestComputeAlleles covers the algorithm), divergent benchmarks, mode plumbing through write_plink, the streaming source, and view-plink1's eventual flag set.

Argument for keeping minor-allele as opt-in

1. Bit-for-bit reproduction of legacy plink 1.9 outputs. Some archived analysis pipeline may produce a .bed whose bytes encode minor-allele homozygotes as 00. Re-running our pipeline on the same source VCF should ideally produce the same bytes. Counter: this kind of byte-level reproduction is brittle anyway (depends on plink 1.9's tie-breaking, dataset-specific frequencies, and same-cohort assumption). A semantically equivalent output is achievable via plink1.9 --bfile our_out --keep-allele-order --recode bed followed by re-running plink 1.9 without that flag, which yields the legacy bytes.
2. User surprise. Existing vcztools users running write_plink may have downstream comparisons assuming the current bytes. Counter: document the change in release notes and bump a minor version.

Risks if we drop it

1. Legacy reproduction. Anyone whose downstream pipeline compares vcztools' .bed bytes to a stored plink-1.9-generated .bed (rather than to genotype values) will see a diff. The fix is documented and one flag away.
2. Rare third-party tools. Tools outside the IO-study list (e.g. some bespoke Stata/R scripts that read .bed directly and divide by 2 to get "MAF" without consulting .bim) could silently misinterpret. The .bim allele columns are still correct, so any tool that consults them gets the right answer. This is a script-bug class, not a vcztools-bug class.

Recommendation

Drop minor-allele. The compatibility surface is empty for the consumers we care about, the performance and design wins are substantial, and the residual risks are document-able. Add a clear release-notes entry pointing users at --keep-allele-order for plink 1.9 reading and explaining that REF/ALT is the on-disk convention.

If the maintainer wants a softer landing, the alternative is a single release where write_plink(..., a12_strategy="minor_allele") is accepted but emits a DeprecationWarning, with removal one release later. This is more friction for ~zero ecosystem benefit given the analysis above, so I'd skip it.

Sources

• PLINK 1.9 — Data management
• PLINK 2 — Data formats
• REGENIE documentation — options
• BOLT-LMM v2.5 manual
• Why specify --keep-allele-order with --vcf (Biostars)
• Difference between plink1.9 and plink2 in defining reference allele
• KING relatedness manual
• flashpca README