| name | claw-ancestry-pca |
| version | 0.1.0 |
| description | Ancestry decomposition PCA against the Simons Genome Diversity Project |
| author | Manuel Corpas |
| license | MIT |
| tags | ["population-genetics","PCA","ancestry","SGDP","global-diversity"] |
| inputs | [{"name":"vcf","type":"file","format":["vcf","vcf.gz"],"description":"VCF file with genotype data for your study cohort"},{"name":"pop-map","type":"file","format":["tsv","txt"],"description":"Tab-separated file mapping sample IDs to population labels"}] |
| outputs | [{"name":"figure","type":"file","format":["png","pdf"],"description":"Multi-panel PCA composite figure showing ancestry decomposition"},{"name":"report","type":"file","format":"markdown","description":"Ancestry analysis report with population assignments and statistics"}] |
| metadata | {"openclaw":{"category":"bioinformatics","homepage":"https://github.com/ClawBio/ClawBio","min_python":"3.9","dependencies":["pandas","numpy","matplotlib","scikit-learn","adjustText"],"system_dependencies":["plink","bcftools"]}} |
🦖 Ancestry Decomposition PCA
Place your study cohort in global genetic context by computing a joint PCA against the Simons Genome Diversity Project (SGDP) — 345 samples from 164 populations spanning every inhabited continent.
What it does
- Takes your VCF + population map as input
- Finds common variants between your cohort and the SGDP reference panel (bundled)
- Runs PLINK PCA on the merged dataset
- Separates your cohort from SGDP reference samples
- Matches SGDP samples to their population labels (164 populations)
- Generates a publication-quality multi-panel figure:
- Panel A: PC1 vs PC2 — main population structure of your cohort
- Panel B: PC3 vs PC2 with regional groupings and confidence ellipses
- Panel C: PC3 vs PC1 with language/cultural groupings
- Panel D: Global context — your samples (circles) vs SGDP (triangles)
- Produces a markdown report with variance explained, population assignments, and reproducibility bundle
Why this exists
If you ask ChatGPT to "run a PCA against a global reference panel," it will:
- Not know which reference panel to use
- Hallucinate PLINK flags for merging datasets with different variant sets
- Skip IBD removal (related individuals distort PCA)
- Not normalise contig names between your VCF and the reference
- Produce a single scatter plot with no population labels
This skill encodes the correct methodological decisions:
- Uses SGDP (the gold-standard reference for global diversity)
- Handles contig normalisation (chr1 vs 1)
- Filters to common biallelic SNPs shared between datasets
- Removes related individuals via IBD checks
- Produces publication-quality multi-panel figures with confidence ellipses
- Differentiates your samples (circles) from reference (triangles)
Reference Panel
The skill bundles the SGDP v4 dataset (Mallick et al., 2016, Nature):
- 345 samples from 164 populations
- Whole-genome sequencing at high coverage
- MAF > 0.1% filter applied
- Populations span: Africa, Americas, Central/South Asia, East Asia, Europe, Middle East, Oceania
Usage
python ancestry_pca.py \
--vcf your_cohort.vcf.gz \
--pop-map your_populations.tsv \
--output ancestry_report
Demo (works out of the box)
python ancestry_pca.py --demo --output demo_report
