[meta]
name = "admixture"
category = "population-genomics"
description = "Fast population structure analysis using maximum likelihood estimation of ancestry proportions"
tags = ["population-genetics", "ancestry", "structure", "gwas", "admixture", "plink", "k-value"]
author = "oxo-call built-in"
source_url = "https://dalexander.github.io/admixture/"

[context]
concepts = [
    "ADMIXTURE estimates ancestry proportions (Q-matrix) and allele frequencies (P-matrix) for a specified K (number of populations).",
    "ADMIXTURE uses PLINK binary format (.bed/.bim/.fam) as input; data should be LD-pruned before running.",
    "Specify K (number of ancestral populations) as a positional argument: admixture data.bed K.",
    "Run multiple K values and use cross-validation error (--cv) to select optimal K.",
    "Use --seed for reproducibility; run multiple replicates to check convergence.",
    "Output: <input>.K.Q (ancestry proportions per individual) and <input>.K.P (allele frequencies per population).",
    "Use --supervised for supervised mode with labeled reference populations.",
    "ADMIXTURE is equivalent to STRUCTURE but orders of magnitude faster.",
]

pitfalls = [
    "ADMIXTURE requires LD-pruned data — high LD inflates estimated K and distorts ancestry proportions.",
    "Run multiple replicates per K (with different seeds) — different runs may give different local optima.",
    "The Q-matrix columns are not labeled with population names — interpretation requires external knowledge.",
    "Rare variants (MAF < 0.01) should be filtered before running ADMIXTURE.",
    "Without --cv, cross-validation error is not computed — always use --cv=10 for model selection.",
    "ADMIXTURE does not handle related individuals well — remove close relatives before analysis.",
]

[[examples]]
task = "run ADMIXTURE for K=5 ancestral populations"
args = "data.bed 5 --cv=10 -j8"
explanation = "positional K=5; --cv=10 cross-validation with 10 folds; -j8 threads; outputs data.5.Q and data.5.P"

[[examples]]
task = "run ADMIXTURE with reproducible seed"
args = "data.bed 3 --seed=42 --cv=10 -j8"
explanation = "--seed for reproducibility; run same command with different seeds to check convergence"

[[examples]]
task = "run supervised ADMIXTURE with known reference populations"
args = "data.bed 3 --supervised -j8"
explanation = "--supervised mode uses .pop file (same name as .fam) with population labels for reference individuals"

[[examples]]
task = "run ADMIXTURE across multiple K values (shell loop)"
args = "data.bed K --cv=10 -j8 > admixture_K.log"
explanation = "run for K=2,3,4,5,etc in a loop; compare cross-validation errors to select optimal K"
