Ld 1000g Region Compute

Gotchas

1. r² requires ancestry-matched reference panel. Using EUR LD against an East-Asian GWAS produces wrong LD blocks and misleading visualisations. The skill takes super_pop as a required input (or defaults to EUR with a manifest caveat) and emits the choice in every manifest. Match super_pop to the upstream cohort's ancestry. For Finnish-EUR (FinnGen) on a 1000G EUR panel, expect ~0.05 r² average divergence on common variants per Locke 2019; surface as a caveat in the rendered output. See references/ancestry_matching.md.

2. Lead variant absent from 1000G. Rare or array-only variants may not be in the 1000G panel; in that case every partner returns r²=0 because the lead has no neighbours in the reference. The skill notes LD r² unavailable for lead in the manifest. Workaround: pick a different (more common) lead in the locus that IS in 1000G via --lead <variant_id>, or accept grey points in the regional plot.

3. Variant-id format collision in 1000G VCFs. The 1000G GRCh38 VCFs use . (missing) in the ID column rather than chr:pos:ref:alt. The on-demand client passes plink --set-missing-var-ids '@:#:$1:$2' to rewrite IDs into the canonical form before LD compute (@ = chromosome, # = bp, $1 / $2 = ref / alt). Tri-allelic loci that have been split into multiple lines may still produce duplicate IDs; deduplicate the source VCF or bcftools norm -m -any upstream if you hit that case.

4. plink 1.9 --keep FID convention. plink 1.9 + --vcf assigns FID = IID = sample-id (per the plink 1.9 input docs); the on-demand client's --keep file therefore writes <sample>\t<sample> rows (NOT 0\t<sample>; that variant errors out with "No people remaining after --keep" because no loaded sample has FID=0). plink2 flips this default to FID=0, so do not copy a plink2-era keep file verbatim if you swap binaries.

5. Rare variants (MAF < 0.01) have unstable r². With ~500 EUR samples and MAF=0.005, only ~5 individuals carry the rare allele; r² estimates have huge sampling variance. The skill filters MAF < 0.01 by default and emits the count in rare_variant_drops. Do NOT manually re-include rare variants by lowering this threshold; for rare-variant fine-mapping, use a higher-density reference (TOPMed, HRC) which is out of scope.

6. 1000G Phase 3 is stable; cache is durable. The 2019-03-12 NYGC re-imputed release has not been refreshed; r² values computed today vs five years from now are identical. Cache invalidation is panel-version-keyed; the skill does NOT re-fetch when the cache is warm.

7. Admixed populations do not fit cleanly into a single 1000G super-population. Hispanic / Latino, African American, and other admixed cohorts have ancestry-specific LD that 1000G's five super-pops only partially capture. The skill emits a caveat in the manifest when super_pop = AMR and the upstream study is admixed; surface it in the user-facing reply. See references/ancestry_matching.md.

Safety

Not for clinical decisions. This skill returns LD r² estimates from a public reference panel. The output is a research-grade visualisation aid; do not use the output for clinical decision-making.

LD computed on a reference panel does not match LD in the target study population exactly. The 1000G Phase 3 super-populations are approximations. For trans-ancestry studies, populations not represented in 1000G, or admixed cohorts, the r² values are useful for visualisation only, not for hard inferential decisions (e.g., LD-pruning instruments for Mendelian randomisation should use the actual GWAS reference panel when available).

Agent Boundary

The skill computes pairwise r² between a lead variant and partner variants in a chromosomal window, using a 1000 Genomes Phase 3 GRCh38 super-population reference panel. The agent should:

• Use r² output for visualisation (LocusCompare, LocusZoom-style regional plots) and for instrument-set LD-pruning in Mendelian randomisation.
• Surface the chosen super-population in the user-facing reply. Per the user-friendly enum-expansion rule (AGENTS.md), expand the field: LD = 1000G Phase 3 EUR (n=503 samples), never just EUR.
• NOT claim "in LD" without an explicit r² threshold. The standard publication thresholds are r² > 0.6 (high LD), r² > 0.2 (any LD); the agent must cite the threshold when making a claim.
• NOT use 1000G-derived LD for ancestry-mismatched studies without flagging the mismatch. When the GWAS / eQTL ancestry does not match the chosen super-pop, the agent must surface this as a caveat in the user-facing reply.
• NOT compute LD on rare variants (MAF < 0.01). The skill drops them; the agent must NOT manually re-include them by lowering the threshold.
• Cite the panel version and plink version in any output. The manifest carries both; the agent quotes them as part of the methods statement.

Citations

• 1000 Genomes Project Consortium (2015). A global reference for human genetic variation. Nature 526, 68-74. doi:10.1038/nature15393
• Clarke et al. (2017). The international Genome Sample Resource (IGSR): A worldwide collection of genome variation incorporating the 1000 Genomes Project data. Nucleic Acids Res 45, D854-D859. doi:10.1093/nar/gkw829
• Chang et al. (2015). Second-generation PLINK: rising to the challenge of larger and richer datasets. GigaScience 4. doi:10.1186/s13742-015-0047-8
• Locke et al. (2019). Exome sequencing of Finnish isolates enhances rare-variant association power. Nature 572, 323-328. doi:10.1038/s41586-019-1457-z (Finnish-EUR vs 1000G EUR LD divergence at common variants.)