Fine Mapping

🎯 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 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

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; 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

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:

Ω = (τ² · D² + σ² · I)⁻¹   in the LD eigenbasis

where D² are eigenvalues of X'X (n × LD eigenvalues). When τ²→0 the model reduces to standard SuSiE.

1. Eigendecompose LD once: LD = V diag(d²/n) V'
2. IBSS loop with Ω-weighted residuals instead of σ²-only residuals
3. Method-of-moments update for σ² and τ² each iteration
4. Credible sets via per-effect PIPs (p×L matrix) with purity filter

When to prefer SuSiE-inf over SuSiE:

• Large cohort (N > 50k): background polygenic signal is detectable
• Locus shows many nominally associated variants (diffuse signal)
• SuSiE returns very large credible sets (many variants absorbed as "sparse" effects)

Key thresholds / parameters:

• Prior W (ABF): 0.04 (source: Wakefield 2009, Am J Hum Genet)
• Credible set coverage: 95% (adjustable via --coverage)
• Max signals L: 10 (adjustable via --max-signals)
• Min purity (SuSiE/SuSiE-inf CS filter): 0.5 minimum absolute pairwise LD |r| within the set (Wang 2020 §3.2), not mean r². Under the sushie engine this value is forwarded to sushie's own purity argument, so it prunes at fit time as well as flagging downstream
• Convergence tolerance (SuSiE engine): ELBO change < 1e-4 (sushie min_tol)