fine-mapping

Files (12)

• SKILL.md
• core
• fine_mapping.py
• __init__.py · fine_mapping_core/
• abf.py · fine_mapping_core/
• credible_sets.py · fine_mapping_core/
• io.py · fine_mapping_core/
• report.py · fine_mapping_core/
• susie.py · fine_mapping_core/
• susie_inf.py · fine_mapping_core/
• demo_susie_known_answer.json · tests/fixtures/
• test_fine_mapping.py · tests/

SKILL.md (first lines)

# 🎯 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 delegates SuSiE to the published [sushie](https://github.com/mancusolab/sushie) package — 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, delegated to the sushie package (mancusolab/sushie, JAX-based) via its summary-statistics interface run with a single ancestry; requires the `fine-mapping` extra (`uv sync --extra fine-mapping`)
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

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

# SuSiE multi-signal with pre-computed LD matrix (sushie engine:
# install once with `uv sync --extra fine-mapping`)
uv run --extra fine-mapping python skills/fine-mapping/fine_mapping.py \
  --sumstats locus.tsv --ld ld_matrix.npy --output /tmp/finemapping

# Filter to a specific locus window
uv run --extra fine-mapping 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)
uv run --extra fine-mapping 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)
uv run --extra fine-mapping 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)
uv run --extra fine-mapping python skills/fine-mapping/fine_mapping.py --demo --output /tmp/finemapping_demo
```

## Demo

```bash
uv run --extra fine-mapping 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, two single-variant SuSiE credible sets pinpointing the causal variants (indices 60 and 140), 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 = ABF_i / sum(ABF_j)
```

Default prior: W = 0.04 (σ = 0.2 on log-OR scale; Wakefield 2009)

### SuSiE (Sum of Single Effects, Wang et al. 2020)

When an LD matrix **R** is provided, the locus is fine-mapped by the sushie
package (`sushie.infer_ss.infer_sushie_ss` with a single ancestry), which
implements the SuSiE model with effect variances estimated by EM:

1. sushie fits L single effects (default 10) on the z-scores and LD matrix, run in float64 (jax x64) to avoid ELBO precision failures
2. sushie prunes effects to those forming valid credible sets (coverage threshold + purity); the adapter returns only these active signals, so null loci yield zero credible sets and no phantom PIPs
3. PIPs are sushie's `pip_cs` — computed over the kept signals: `PIP_i = 1 - prod_l (1 - α_l_i)`
4. Credible sets for the report: greedily add highest-α variants per signal until cumulative α ≥ 0.95, with the min-|r| purity flag (Wang 2020 §3.2)

### SuSiE-inf (Cui et al. 2024)

> **Two engines, not one.** Only the `--ld` SuSiE path runs on sushie. SuSiE-inf
> still uses this skill's own numpy IBSS implementation (`fine_mapping_core/susie_inf.py`),
> because sushie has no infinitesimal-component model to delegate to. The two
> therefore differ in their priors: sushie re-estimates the effect variance by
> EM, while SuSiE-inf keeps the fixed Wakefield-style prior and a `null_weight`.
> PIPs from the two paths are not interchangeable — do not compare them on the
> same locus and read the difference as a biological result.

Extends SuSiE with an infinitesimal variance component τ² that captures diffuse polygenic signal. The residual precision matrix becomes:

```

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio