GPTomics/population-genetics/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