Manages PLINK genotype filesets - format conversion (VCF, BED/BIM/FAM, PED/MAP, pgen/pvar/psam) and sample/variant QC (missingness, MAF, HWE, sex check, heterozygosity, KING relatedness) with PLINK 1.9 and 2.0. PLINK rewrites allele bookkeeping: PLINK 1.x A1 defaults to the minor allele and is recomputed every load, silently flipping effect-allele meaning unless --keep-allele-order, while PLINK 2.0 tracks explicit REF/ALT. QC order matters (variant before sample missingness), HWE is controls-only in 1.9 but not 2.0, add midp, and differential case/control missingness injects false hits. Use when converting between PLINK formats or running genotype QC before association, structure, or LD analysis. For LD pruning/clumping see linkage-disequilibrium; for GWAS see association-testing; VCF input from variant-calling/vcf-basics.
Instrucciones de origen · Vista previa de solo lectura
name
bio-population-genetics-plink-basics
description
Manages PLINK genotype filesets - format conversion (VCF, BED/BIM/FAM, PED/MAP, pgen/pvar/psam) and sample/variant QC (missingness, MAF, HWE, sex check, heterozygosity, KING relatedness) with PLINK 1.9 and 2.0. PLINK rewrites allele bookkeeping: PLINK 1.x A1 defaults to the minor allele and is recomputed every load, silently flipping effect-allele meaning unless --keep-allele-order, while PLINK 2.0 tracks explicit REF/ALT. QC order matters (variant before sample missingness), HWE is controls-only in 1.9 but not 2.0, add midp, and differential case/control missingness injects false hits. Use when converting between PLINK formats or running genotype QC before association, structure, or LD analysis. For LD pruning/clumping see linkage-disequilibrium; for GWAS see association-testing; VCF input from variant-calling/vcf-basics.
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 for relatedness. The single source of truth for versions is this block, not headings.
--make-king
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)
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
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.
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.
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.
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.
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
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.
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.
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.
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.
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
