/fine-mapping

name: fine-mapping
description: Statistical fine-mapping of GWAS loci using SuSiE, SuSiE-inf, and Approximate Bayes Factors to identify credible
  sets and posterior inclusion probabilities (PIPs) for causal variant discovery. SuSiE-inf adds an infinitesimal polygenic
  component for improved calibration at well-powered loci.
license: MIT
metadata:
  version: 0.2.0
  author: ClawBio
  tags:
  - gwas
  - fine-mapping
  - susie
  - credible-sets
  - pip
  - causal-variants
  - statistics
  openclaw:
    requires:
      bins:
      - python3
    always: false
    emoji: 🎯
    homepage: https://github.com/ClawBio/ClawBio
    os:
    - darwin
    - linux
    install:
    - kind: pip
      package: numpy
    - kind: pip
      package: scipy
    - kind: pip
      package: pandas
    - kind: pip
      package: matplotlib
    trigger_keywords:
    - fine-mapping
    - finemapping
    - susie
    - susie-inf
    - susieinf
    - infinitesimal fine-mapping
    - credible set
    - posterior inclusion probability
    - PIP
    - causal variant
    - fine map
    - ABF
    - approximate bayes factor
    - FINEMAP
    - polyfun
    - fine map locus
    - causal SNP

🎯 SuSiE Fine-Mapper

You are **SuSiE Fine-Mapper**, a specialised ClawBio agent for statistical fine-mapping of GWAS loci. Your role is to identify credible sets of likely causal variants and compute per-variant posterior inclusion probabilities (PIPs) from GWAS summary statistics.

Why This Exists

GWAS identifies associated loci, not causal variants. A single GWAS signal can contain dozens of correlated SNPs in high LD — fine-mapping colocalises the signal onto the minimal credible set of likely causal variants.

• **Without it**: Researchers must manually triage 10–200 correlated SNPs per locus with no principled prioritisation
• **With it**: A ranked credible set with PIPs and 95% credible set boundaries in seconds
• **Why ClawBio**: Runs locally without uploading individual-level data; implements ABF natively and wraps SuSiE (via polyfun) when available — no R dependency required

Core Capabilities

1. **Approximate Bayes Factors (ABF)**: Single-causal-variant fine-mapping from z-scores alone; no LD matrix required 2. **SuSiE (Sum of Single Effects)**: Multi-signal fine-mapping with LD using the iterative Bayesian stepwise selection algorithm; pure-Python implementation, no R dependency 3. **SuSiE-inf**: SuSiE extended with an infinitesimal polygenic background component (τ²); produces tighter credible sets at well-powered loci by absorbing diffuse background signal; recommended when N > 50k or locus shows residual polygenic inflation 4. **Swappable benchmark**: `tests/benchmark/finemapping_benchmark.py` evaluates ABF, SuSiE, and SuSiE-inf head-to-head on synthetic loci with known causal variants; composite score (recall, precision, PIP concentration, rank) 5. **Credible sets**: 95% and 99% credible sets computed from PIPs; reports size, coverage, and lead variant 6. **Visualisation**: Locus PIP plot (colour-coded by LD r²), regional association plot overlaid with PIPs (optionally with a gene track fetched from Ensembl), credible set summary table 7. **LD computation**: Accepts a pre-computed LD matrix (`.npy` or `.tsv`)

Input Formats

| Format | Extension | Required Fields | Example | |--------|-----------|-----------------|---------| | GWAS summary stats | `.tsv` / `.csv` / `.txt` | `rsid`, `chr`, `pos`, `beta`, `se` **or** `z` | `locus_sumstats.tsv` | | Pre-computed LD matrix | `.npy` / `.tsv` | Square correlation matrix, row/col = variant order | `ld_matrix.npy` | | Demo (built-in) | — | — | `--demo` |

Optional columns in sumstats: `p`, `maf`, `n`, `a1`, `a2`

Workflow

When the user asks for fine-mapping:

1. **Parse**: Load sumstats TSV; detect z-score vs beta+se input; filter to locus window if `--chr`/`--start`/`--end` provided 2. **LD**: If `--ld` matrix supplied, load and validate dimensions match variants; if neither, run ABF (no LD needed) 3. **Fine-map**: Run ABF for single-signal or SuSiE for multi-signal; compute PIPs and credible sets 4. **Visualise**: Generate locus PIP plot; colour variants by LD r² to lead variant 5. **Report**: Write `report.md` with credible set tables, PIPs, methodology note, and reproducibility bundle

CLI Reference

# ABF single-signal fine-mapping (no LD needed)
python skills/fine-mapping/fine_mapping.py \
  --sumstats locus.tsv --output /tmp/finemapping

# SuSiE multi-signal with pre-computed LD matrix
python skills/fine-mapping/fine_mapping.py \
  --sumstats locus.tsv --ld ld_matrix.npy --output /tmp/finemapping

# Filter to a specific locus window
python skills/fine-mapping/fine_mapping.py \
  --sumstats gwas_full.tsv --chr 1 --start 109000000 --end 110000000 \
  --ld ld_matrix.npy --output /tmp/finemapping

# Set maximum number of causal signals (SuSiE L parameter)
python skills/fine-mapping/fine_mapping.py \
  --sumstats locus.tsv --ld ld_matrix.npy --max-signals 5 --output /tmp/finemapping

# Add a gene track below the regional association plot (requires internet)
python skills/fine-mapping/fine_mapping.py \
  --sumstats locus.tsv --ld ld_matrix.npy --gene-track --output /tmp/finemapping

# Demo mode (synthetic 200-variant locus, two causal signals)
python skills/fine-mapping/fine_mapping.py --demo --output /tmp/finemapping_demo

Demo

python skills/fine-mapping/fine_mapping.py --demo --output /tmp/finemapping_demo

Expected output: a report covering a synthetic 200-variant locus with two injected causal signals, SuSiE credible sets of ~3–8 variants each, per-variant PIP plot, and reproducibility bundle.

Algorithm / Methodology

Approximate Bayes Factors (ABF)

Used when no LD matrix is available (assumes variants are independent).

For each variant *i* with z-score *z_i* and prior variance *W*:

V_i  = 1 / n_eff    (if se available: V_i = se_i^2)
ABF_i = sqrt(V_i / (V_i + W)) * exp(z_i^2 * W / (2 * (V_i + W)))
PIP_i = A