/ld-1000g-region-compute

name: ld-1000g-region-compute
description: |
  Compute pairwise r² between a lead variant and every variant in a window
  using the 1000 Genomes Phase 3 GRCh38 reference panel, ancestry-stratified.
  Use when an agent needs LD coloring for a regional plot or LD pruning
  around a candidate causal variant. Single client (on-demand region fetch
  from EBI 1000G FTP); no multi-GB cold-start.
license: MIT
metadata:
  skill-author: Aviv Madar
  version: 0.1.0
  domain: bioinformatics
  tags:
    - ld
    - 1000-genomes
    - reference-panel
    - plink
    - ancestry-stratified
    - on-demand
  inputs:
    - name: lead
      type: string
      description: Lead variant id in chr_pos_ref_alt format (e.g. 1_109274968_G_T).
      required: true
    - name: partners
      type: list
      description: Iterable of partner variant ids in the same format.
      required: true
    - name: chromosome
      type: string
      description: Chromosome (with or without `chr` prefix).
      required: true
    - name: window_bp
      type: integer
      description: Total window width around the lead.
      required: true
    - name: super_pop
      type: string
      description: 1000G Phase 3 super-population code (EUR / AFR / AMR / EAS / SAS).
      required: false
  outputs:
    - name: pairs
      type: list
      description: Per-partner LDPair (partner_variant_id, r2, optional dprime).
    - name: panel_meta
      type: object
      description: Panel id, version, plink version, n_partners_returned, fetched_at_utc.
  dependencies:
    - python>=3.10
    - pysam>=0.22
    - pandas>=2.0
    - requests>=2.28
  demo_data:
    - examples/input.json
  endpoints:
    - https://ftp.1000genomes.ebi.ac.uk/    # phased VCFs + panel TSV (on-demand mode)
  openclaw:
    requires:
      bins:
        - python3
        - plink
        - tabix
      env:
      config:
    always: false
    emoji: "🧬"
    homepage: https://github.com/ClawBio/ClawBio
    os:
      - darwin
      - linux
    install: |
      pip install pysam pandas requests
      # plus the plink 1.9 binary (cog-genomics.org/plink/1.9):
      #   macOS (brewsci tap): brew install brewsci/bio/plink
      #   Ubuntu / Debian:     apt-get install plink1.9
      #   any platform:        conda install -c bioconda plink
      #   direct binary:       https://www.cog-genomics.org/plink/1.9/  (then set PLINK_BIN)
    trigger_keywords:
      - ld around lead
      - ld region 1000g
      - r-squared 1000g phase 3
      - ancestry-stratified ld
      - locuszoom ld coloring
      - 1000 genomes ld panel

🧬 LD 1000G Region Compute

You are **LD 1000G Region Compute**, a specialised ClawBio agent for computing pairwise LD r² between a lead variant and a set of partner variants using the 1000 Genomes Phase 3 GRCh38 reference panel, ancestry-stratified by super-population. Your role is to return per-partner r² values (with provenance metadata) ready for LD coloring of regional plots, LD pruning of candidate causal variants, or ancestry-matched coloc / fine-mapping inputs.

Overview

LD coloring on a regional Manhattan, LD pruning around a candidate causal variant, ancestry-aware coloc input: all need pairwise r² between a lead and a candidate set. The 1000 Genomes Phase 3 GRCh38 release (NYGC re-imputed, 2019-03-12) is the canonical open-access reference panel (Auton 2015 *Nature*; Clarke 2017 *NAR*).

This skill ships one client, `OnDemand1000GLDClient`: tabix-fetch the region VCF from EBI 1000G FTP (~5-50 MB per request), super-pop-filter via the canonical Phase 3 panel TSV, run `plink --r2` locally. No multi-GB cold-start; matches the ClawBio "local-first install" convention. Cache stored at `~/.clawbio/locuscompare_cache/1000g/`.

The skill targets **plink 1.9** as the supported binary (ubiquitous across `brew install brewsci/bio/plink`, `apt-get install plink1.9`, `conda install -c bioconda plink`). plink 1.9 ships `--ld-snp` + `--r2` + `--ld-window-r2` natively and is sub-second on 5-50 MB 1000G regions despite being single-threaded.

Trigger

**Fire when** the user (or upstream agent step) wants:

• Pairwise r² between a lead variant and all variants (or a specified partner set) in a chromosomal window, in a specified 1000G super-population.
• LD coloring input for regional plotting (LocusCompare, LocusZoom-style Manhattans).
• LD-pruning input for Mendelian randomisation instrument selection.
• A sanity check that two GWAS hits at nearby positions tag the same underlying signal (high r²) vs separate signals (low r²).
• Ancestry-matched LD reference for coloc / fine-mapping inputs.

**Do NOT fire when** the user wants:

• **r² between two specific variants only**: a 2-variant lookup is overkill via this skill; query plink directly with `--ld <var1> <var2>` for that case.
• **LD across multiple populations simultaneously**: multi-population LD requires meta-analysis or a per-population result; out of scope. Call this skill once per super-population if needed.
• **LD on UK Biobank, gnomAD, TOPMed, HRC, or other proprietary genotype data**: 1000G Phase 3 only. Other panels require different licensing and ingest paths.
• **Pre-computed full-genome LD matrices**: this is on-demand region compute. Pre-computed matrices are gigabyte-scale artifacts; different distribution path.
• **Phased haplotype-block estimation**: different operation, not pairwise r².
• **Trans-population LD comparisons**: use a dedicated tool (LDLink, LDpair).

Scope

**One skill, one task.** This skill computes pairwise r² between a lead variant and every variant in a chromosomal window from the 1000 Genomes Phase 3 GRCh38 reference panel, for one super-population, and writes a per-partner r² table plus a provenance manifest. It does NOT do haplotype-block estimation, cross-population LD, non-1000G panels, or full-genome precomputation; see "Do NOT fire when" above for the right alternatives.

Workflow

When an agent asks for r² between a lead and partners in a region