Every qpAdm tutorial starts at "given your genotypes in EIGENSTRAT format, merged with the reference panel". Almost nobody documents how you get there — and the getting-there is where real analyses succeed or die, because the merge sets your standard errors before any model runs. This is the missing chapter: formats, builds, strand discipline, the tools that do the work, and the checks that catch the silent failures. It is the pipeline we run in production, written down.
The target state, and the formats on the way#
qpAdm consumes EIGENSTRAT (or its binary sibling PACKEDANCESTRYMAP): a .geno genotype
matrix, a .snp file of positions and alleles, a .ind file of individuals with population
labels. The AADR ships in exactly this shape.
Your own data starts life elsewhere — a consumer text export, a PLINK .bed/.bim/.fam trio,
or a VCF — and the pipeline is the sequence of conversions and one merge that ends with your
sample as one more row of the panel.
The canonical converters: PLINK itself (consumer text → .ped/.map → .bed), and EIGENSOFT's
convertf for PLINK ↔ EIGENSTRAT, driven by a small parameter file naming the input/output
formats and files. Modern practice increasingly wraps the whole thing in Poseidon's trident,
which manages panel packages with their metadata and performs merges (trident forge) with the
bookkeeping handled — it is what our own production merge uses, and its package discipline is
worth adopting even solo: a genotype file whose provenance you cannot state is a liability, not
data.
The three silent killers#
Build mismatch. The AADR's positions are GRCh37/hg19; a consumer file usually is too, but a sequencing VCF is often GRCh38. Merging across builds does not error — it quietly matches almost nothing, or worse, mismatches something. Liftover before anything else, and verify by spot-checking a few known rsIDs' positions afterwards.
Strand flips. Consumer files report genotypes on the strand the chip happened to probe. For
an A/G SNP recorded as T/C, naive merging misreads every genotype — and for the truly cursed
class, palindromic (A/T and C/G) SNPs, no strand check can rescue them because both strands
read the same alphabet. The professional move is the boring one: align alleles against the
panel's .snp records, flip where the complement matches, and drop palindromic sites
outright — they are a small fraction of the intersection and an outsized fraction of the merge
errors.
Sex chromosomes and duplicates. qpAdm runs on autosomes (auto_only is the default for a
reason); haploid male X calls, PAR-region weirdness and duplicate rsIDs at one position all
belong out of the merge, not in it. Deduplicate by position, not by name — chip annotations
recycle names more often than positions.
The merge itself, and the arithmetic to expect#
Intersect-and-merge is the only honest mode: keep exactly the positions present in both your file and the panel, your sample encoded like the panel's own (for comparisons against pseudohaploid ancients, that can mean randomly sampling one allele of yours per site — matching the reference's data class for the same reason capture classes should not be mixed).
Then check three numbers before celebrating. The intersection size: a healthy consumer chip against the AADR's 1240K sites lands in the hundreds of thousands; a number far below your chip's usual range means the pipeline, not the chip. The per-population missingness of the ancients you plan to use — the allsnps decision hangs on it. And a sanity model: run one utterly standard model (a known European target against the textbook sources and rights) and confirm it behaves like the literature says it should. A pipeline that cannot reproduce a boring known result has no business producing interesting new ones.
Or skip it, knowingly#
This pipeline is exactly the unglamorous half of what the paid analysis does before any analyst hours begin: your export or whole-genome VCF converted, aligned, merged into AADR v66 with the discipline above, and the Model Lab will even hand you the finished EIGENSTRAT bundle to run yourself. Doing it solo is genuinely achievable with a weekend and this page — and either way, the free file check is the right first move: it reads your export and reports the marker counts this whole pipeline will live off.
Terms used here are defined in the glossary.
References#
- Patterson, N. et al. (2012). Ancient admixture in human history. Genetics, 192(3), 1065–1093. (EIGENSTRAT/convertf lineage.)
- Mallick, S. et al. (2024). The Allen Ancient DNA Resource (AADR): a curated compendium of ancient human genomes. Scientific Data, 11, 182.
- Schmid, C. et al. (2024). Poseidon — a framework for archaeogenetic human genotype data management. eLife, 13, e98317.
- Chang, C. C. et al. (2015). Second-generation PLINK. GigaScience, 4, 7.
