Plink basics

Version Compatibility

Reference examples tested with: PLINK 1.9 (1.90b7+), PLINK 2.0 (alpha 6+), pandas 2.2+.

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• CLI: <tool> --version then <tool> --help to confirm flags

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

Version traps that change results, not just syntax: PLINK 2.0 --freq reports ALT/nonmajor allele frequency, PLINK 1.9 --freq reports MAF. PLINK 2.0 has no --recode (use --export) and cannot read .ped/.map (convert with 1.9 first). PLINK 2.0 --hwe is NOT controls-only by default; PLINK 1.9 is. Missing-rate outputs are .smiss/.vmiss (2.0) vs .imiss/.lmiss (1.9). PLINK 2.0 dropped --genome; use --make-king for relatedness. The single source of truth for versions is this block, not headings.

PLINK Basics

"Convert my VCF to PLINK and run QC" -> Project a VCF into a PLINK fileset and apply sample/variant quality filters, holding the allele coding and filter order fixed so downstream effect estimates stay meaningful.

• CLI: plink2 --vcf in.vcf.gz --make-pgen (keeps REF/ALT and dosage) or --make-bed (biallelic hard calls, A1/A2)
• CLI: plink2 --geno 0.02 then plink2 --mind 0.02 --maf 0.01 --hwe 1e-6 midp (ordered QC)

Scope: PLINK file formats, conversion, and sample/variant QC (missingness, MAF, HWE, sex check, heterozygosity, KING relatedness, merging). LD pruning/clumping (--indep-pairwise, --clump) route to linkage-disequilibrium; PCA/ADMIXTURE to population-structure; --glm GWAS to association-testing; VCF generation to variant-calling/vcf-basics.

The Single Most Important Insight -- PLINK is a stateful rewriter of allele bookkeeping, not a calculator

1. The most expensive error in the field is trusting that the allele an effect estimate is "for" is the allele assumed. PLINK 1.x has no reference allele: it tracks A1 (the counted/effect allele) and A2, and A1 defaults to the minor allele, recomputed from the data at load time. The same SNP flips A1 between two cohorts when the minor allele differs by a few percent, and every --make-bed re-derives A2 as the major allele unless --keep-allele-order is passed. Betas, odds ratios, and PRS weights are all relative to A1 and become meaningless across cohorts that were not harmonized.
2. PLINK 2.0 fixed the design by tracking explicit REF/ALT in .pvar (REF is the genuine reference base; the counted allele for --glm is set independently), but exporting back to .bed collapses into the A1/A2 world and re-inherits the trap.
3. Pinning alleles to a fixed reference (--ref-allele/--a1-allele from a file, --ref-from-fa, or staying in .pgen) plus --keep-allele-order on any .bed export is the line between reproducible and quietly-wrong analysis.
4. Two QC choices silently corrupt association before any test is run: filter order (sample-vs-variant missingness) and the case/control missingness confounder. Both are covered below.

Tool Taxonomy -- PLINK 1.9 vs PLINK 2.0

Axis	PLINK 1.9 (plink)	PLINK 2.0 (plink2)
Status / model	Stable, feature-frozen; hard calls only; A1/A2	Active; hard calls and dosages; explicit REF/ALT, multiallelic-aware
Native format	.bed/.bim/.fam	.pgen/.pvar/.psam
Allele bookkeeping	A1 = minor by default (the trap)	REF/ALT tracked; counted allele explicit
PED/MAP (--file)	Yes	No (convert via 1.9)
IBD --genome / --cluster	Yes	No (use 1.9 or KING)
KING-robust relatedness	No	--make-king, --king-cutoff
Multi-fileset merge	--bmerge / --merge-list (battle-tested)	--pmerge / --pmerge-list (newer)
HWE default	controls-only	NOT controls-only
--freq default	MAF	ALT/nonmajor frequency
Missing-rate output	.imiss / .lmiss	.smiss / .vmiss
Speed/memory at biobank N	baseline	substantially faster, lower memory

Decision Tree by Scenario

Scenario	Use	Why
Imputed data with dosage uncertainty	plink2 .pgen	1.9 hard-calls and discards dosage
Relatedness in a structured/multi-ancestry sample	plink2 --make-king	PI_HAT (--genome) is biased under structure; KING gives negative kinship for cross-ancestry unrelateds
Classic multi-dataset merge	plink1.9 --bmerge/--merge-list	most documented and predictable path
IBD --genome / IBS --cluster	plink1.9	plink2 dropped these
Reading PED/MAP or Affymetrix-era text	plink1.9 --file	plink2 cannot read them
Big modern QC/association/PCA inputs	plink2, export .bed last	speed plus correct allele handling; minimize time in A1/A2 land
Default working format	stay in .pgen through QC	keeps REF/ALT honest; export .bed only when a tool demands it (then --keep-allele-order)

File Formats

Binary (1.9)	Contents	PLINK 2.0	Contents
.bed	binary hard-call genotypes (biallelic only)	.pgen	genotypes + dosages, multiallelic-aware
.bim	variant info (chr, ID, cM, pos, A1, A2)	.pvar	variant info with genuine REF/ALT
.fam	sample info (FID, IID, father, mother, sex, pheno)	.psam	sample info

Text .ped/.map (PLINK 1.9 --file) is legacy; convert to binary once and work from there.

Format Conversion

# VCF -> PLINK. --make-pgen preserves REF/ALT and dosage; --make-bed collapses to A1/A2 hard calls.
plink2 --vcf in.vcf.gz --make-pgen --out data            # preferred working format
plink2 --vcf in.vcf.gz --double-id --make-bed --out data # biallelic hard calls; --double-id copies the VCF sample name into both FID and IID

# Keep the reference allele honest when leaving pgen for bed (otherwise A2 is re-set to major):
plink2 --pfile data --ref-from-fa --fa GRCh38.fa --make-bed --keep-allele-order --out data_bed

# PLINK -> VCF. plink2 uses --export (no --recode); add bgz to compress.
plink2 --bfile data --export vcf bgz --out out
plink  --bfile data --recode vcf --out out               # PLINK 1.9 idiom

# PED/MAP must be read by PLINK 1.9; plink2 cannot.
plink --file textdata --make-bed --out data

Multiallelic sites cannot live in .bed (biallelic by construction). Split first with bcftools norm -m- or accept plink2's split, and track which records changed. Strand-flip logic cannot operate on indels; --snps-only just-acgt removes them when needed.

Quality Control Filtering

# Variant missingness FIRST, in its own run, so a sample is not dropped for missingness driven by variants slated for removal.
plink2 --pfile data --geno 0.02 --make-pgen --out step1     # default --geno is 0.1; GWAS QC tightens to 0.02-0.05

# THEN sample missingness, MAF, and HWE on the surviving variants.
plink2 --pfile step1 --mind 0.02 --maf 0.01 --hwe 1e-6 midp --make-pgen --out step2

HWE caveats that change which variants survive:

• midp is not optional. The plain exact test is discrete and conservative for low-count genotypes, biasing toward retaining variants with missing data; mid-p brings rejection to nominal (Graffelman 2013).
• Apply HWE to controls only. A true risk variant depletes heterozygotes in cases and would fail a case-inclusive HWE test and be wrongly removed. PLINK 1.9 does this automatically; override with the include-nonctrl modifier. plink2 does NOT - replicate the behavior with --keep-if "PHENO1 == control" before --hwe, or the rewrite over-filters real associations.
• In a structured sample the Wahlund effect reduces heterozygosity, so a two-sided HWE filter drops real variants; many genotyping artifacts (contamination, paralog mismapping) instead inflate heterozygosity, so under structure a one-sided excess-het filter (plink2 keep-fewhet) avoids dropping Wahlund-deficient real variants.

# Differential missingness: a top source of false GWAS hits. A variant genotyped less well in cases than controls
# correlates missingness with phenotype; a flat --geno keeps it and injects association.
plink2 --bfile data --pheno pheno.txt --test-missing --out diffmiss   # drop variants with case/control missingness skew

Sample QC

# Sex check. Split the pseudoautosomal region FIRST or male PAR heterozygosity reads as a sex error.
plink2 --bfile data --split-par hg38 --check-sex --out sexcheck   # PLINK 1.9 uses --split-x hg38
# Default calls: F < 0.2 -> female, F > 0.8 -> male, between -> PROBLEM. These ~2007 defaults are often wrong
# for modern arrays; plot the F histogram and re-pick thresholds at the gap between the two clumps.

# Heterozygosity outliers, on LD-pruned MAF-filtered SNPs only (raw data is dominated by a few regions).
plink2 --bfile data_pruned --het --out het   # flag |F - cohort_mean| > 3 SD: excess het = contamination, deficit = inbreeding/dup

# Relatedness. KING-robust is structure-robust; PI_HAT (--genome) is not.
plink2 --bfile data --make-king-table --out king
plink2 --bfile data --king-cutoff 0.0884 --out unrelated   # prune to no-closer-than 2nd-degree (dup 0.354, 1st 0.177, 2nd 0.0884)

--check-sex and heterozygosity outliers usually signal a sample swap or contamination, not biology - investigate the sample before dropping it. KING uses autosomes only; the same negative bias that makes cross-ancestry unrelated pairs read below zero also pulls true cross-ancestry relatives toward zero, so KING UNDER-detects relatives in admixed or multi-ancestry cohorts (use PC-Relate / PC-AiR there, out of scope here).

Merging Datasets

plink --bfile data1 --bmerge data2 --make-bed --out merged
# Aborts with a "3+ alleles" error when the same SNP is on opposite strands (A/G vs T/C). Flip the offenders, then retry:
plink --bfile data2 --flip merged-merge.missnp --make-bed --out data2_flipped

--flip swaps A<->T and C<->G only and cannot disambiguate palindromic A/T and C/G SNPs (identical on both strands) - resolve those by allele frequency or drop them. Harmonize variant IDs to chr:pos:ref:alt (--set-all-var-ids @:#:\$r:\$a) before merging so the key is positional and allele-aware, not rsID-collision-prone. Build mismatch (hg19 vs hg38) requires liftover first, which can itself flip strand in inverted regions.

Per-Operation Failure Modes

A1/A2 effect-allele flip

Trigger: --make-bed without --keep-allele-order, or merging two cohorts. Mechanism: A1 is re-derived as the minor allele from whatever data is present. Symptom: betas/ORs/PRS weights point at the wrong allele; meta-analysis cancels true signal. Fix: --keep-allele-order on every .bed export and pin alleles from a fixed reference (--ref-from-fa / --a1-allele).

Wrong QC order

Trigger: --geno and --mind in one command. Mechanism: plink applies --mind (sample) before --geno (variant) in a single run; published QC wants variants dropped first. Symptom: good samples removed for missingness caused by variants that were about to be filtered. Fix: run --geno and --mind in separate invocations, variant filter first.

Differential missingness

Trigger: case/control cohorts genotyped in separate batches. Mechanism: missingness correlates with phenotype; a flat --geno retains the variant. Symptom: false genome-wide hits at batch-skewed sites. Fix: --test-missing and drop variants with case/control missingness skew, not just a global --geno.

Phenotype encoding inversion

Trigger: loading a 0/1 case/control file without --1. Mechanism: PLINK reads 1=control, 2=case, 0/-9=missing by default; a 0/1 file makes every case read as control and every control as missing. Symptom: silent, total phenotype corruption; null or inverted GWAS. Fix: --1 for 0/1 coding; any value outside {-9,0,1,2} is treated as quantitative.

PAR not split before sex/X analysis

Trigger: --check-sex or X-specific work without --split-par/--split-x. Mechanism: male PAR is diploid and heterozygous; uncoded it looks like X het. Symptom: males mis-called female; spurious sex PROBLEMs. Fix: --split-par <build> with the correct genome build (hg19 vs hg38 boundaries differ).

Quantitative Thresholds

Operation	Flag	Typical value	Rationale
Variant missingness	--geno	0.02 (PCA/structure), 0.05 (standard)	default 0.1; >2-5% missing flags batch artifacts
Sample missingness	--mind	0.02-0.05	default 0.1; apply AFTER --geno
MAF	--maf	0.01 (common-variant GWAS), 0.05 (PCA), down to 0.001 at large N	below ~0.01 power and HWE/sex-check stability collapse
HWE	--hwe ... midp	1e-6 controls-only	loose vs association: screens artifacts, not biology
Sex F	--check-sex	female <0.2, male >0.8 (default)	re-pick from the F histogram gap
Heterozygosity	--het	|F - mean| > 3 SD	excess het = contamination, deficit = inbreeding/dup; on LD-pruned SNPs
Relatedness (KING)	--king-cutoff	0.0884 (2nd-deg+), 0.177 (1st), 0.354 (dup/MZ cutoff; a true MZ/dup pair sits at ~0.5)	KING boundaries, Manichaikul 2010

Thresholds are conventions, not laws - inspect the distributions and verify current best practice before applying numbers blindly.

Common Errors

Error / symptom	Cause	Solution
--hwe-all "unrecognized flag"	flag does not exist	controls-only override is include-nonctrl (1.9); plink2 needs --keep-if "PHENO1 == control"
HWE over-filters real associations	assuming plink2 --hwe is controls-only	it is not; gate to controls first; always add midp
ALT_FREQ read as MAF	plink2 --freq reports ALT frequency	inspect columns; PLINK 1.9 --freq reports MAF
Script reads empty missingness file	wrong suffix	2.0 .smiss/.vmiss, 1.9 .imiss/.lmiss
--keep-fam sample_id keeps nothing	--keep-fam takes a FILE of FIDs	use --keep with a FID IID file
Frequencies use a subset in family data	MAF/HWE/--freq are founders-only	add --nonfounders if intended
Duplicate variant IDs break --extract/merge	duplicate IDs	--rm-dup force-first or set chr:pos:ref:alt IDs

References

1. Purcell S, et al. PLINK: a tool set for whole-genome association and population-based linkage analyses. American Journal of Human Genetics 2007; 81(3):559-575. DOI:10.1086/519795.
2. Chang CC, Chow CC, Tellier LCAM, Vattikuti S, Purcell SM, Lee JJ. Second-generation PLINK: rising to the challenge of larger and richer datasets. GigaScience 2015; 4:7. DOI:10.1186/s13742-015-0047-8.
3. Manichaikul A, Mychaleckyj JC, Rich SS, Daly K, Sale M, Chen W-M. Robust relationship inference in genome-wide association studies. Bioinformatics 2010; 26(22):2867-2873. DOI:10.1093/bioinformatics/btq559.
4. Wigginton JE, Cutler DJ, Abecasis GR. A note on exact tests of Hardy-Weinberg equilibrium. American Journal of Human Genetics 2005; 76(5):887-893. DOI:10.1086/429864.
5. Graffelman J, Moreno V. The mid p-value in exact tests for Hardy-Weinberg equilibrium. Statistical Applications in Genetics and Molecular Biology 2013; 12(4):433-448. DOI:10.1515/sagmb-2012-0039.

Related Skills

• linkage-disequilibrium - LD pruning and clumping on QC'd genotypes
• population-structure - PCA and ADMIXTURE after QC and relatedness pruning
• association-testing - GWAS with --glm on the filtered fileset
• variant-calling/vcf-basics - VCF generation and manipulation before conversion
• phasing-imputation/genotype-imputation - imputed dosages that enter as .pgen