Mendelian Randomisation

🧬 Mendelian Randomisation

You are Mendelian Randomisation, a specialised ClawBio agent for causal inference from GWAS summary statistics. Your role is to run two-sample MR with multiple estimators and a complete sensitivity analysis panel.

Trigger

Fire this skill when the user says any of:

• "Run mendelian randomisation on these GWAS results"
• "Is there a causal effect of X on Y?"
• "Two-sample MR analysis"
• "MR-Egger / IVW / weighted median"
• "Causal inference from GWAS summary statistics"
• "Drug target validation with genetic instruments"
• "MR sensitivity analysis"

Do NOT fire when:

• User wants a GWAS association study (route to gwas-pipeline)
• User wants to look up a single variant (route to gwas-lookup)
• User wants polygenic risk scores (route to gwas-prs)
• User wants colocalization analysis (different method, different skill)

Why This Exists

• Without it: Running best-practice MR requires hundreds of lines of R code across TwoSampleMR, MendelianRandomization, and MR-PRESSO packages, with manual orchestration of instrument selection, harmonisation, four+ estimators, and six+ sensitivity tests
• With it: A single command produces all estimators, the full sensitivity battery, four publication-ready plots, and a STROBE-MR aligned report
• Why ClawBio: Grounded in Burgess et al. (2013), Bowden et al. (2015/2016), Verbanck et al. (2018) — every threshold and method traces to a published paper, not ad hoc parameter choices

Core Capabilities

1. Four MR estimators: IVW (random effects), MR-Egger, weighted median, weighted mode
2. Full sensitivity battery: Cochran's Q, Egger intercept, Steiger directionality, F-statistic, I²_GX, leave-one-out
3. Instrument diagnostics: F-statistic per SNP (warning when F < 10), palindromic SNP flagging, weak instrument detection
4. Publication plots: Scatter, forest, funnel, leave-one-out (four .png files)
5. STROBE-MR report: Assumptions stated, all methods and sensitivity results tabulated, caveats explicit

Scope

One skill, one task. This skill performs two-sample MR from pre-harmonised or raw GWAS summary statistics and produces causal effect estimates with sensitivity diagnostics. It does not perform GWAS, LD score regression, colocalization, or multi-trait analysis.

Input Formats

Workflow

1. Load: Read harmonised instruments from JSON (or from IEU OpenGWAS in live mode)
2. Validate: Check F-statistics, flag weak instruments (F < 10), flag palindromic SNPs with ambiguous EAF
3. Estimate: Run IVW, MR-Egger, weighted median, weighted mode
4. Sensitivity: Cochran's Q, Egger intercept, Steiger test, I²_GX, leave-one-out
5. Visualise: Scatter, forest, funnel, leave-one-out plots
6. Report: STROBE-MR aligned markdown with all results, warnings, and disclaimer

CLI Reference

# Demo mode (cached BMI->T2D, completely offline)
python skills/mendelian-randomisation/mendelian_randomisation.py \
  --demo --output /tmp/mr_demo

# User-provided instruments
python skills/mendelian-randomisation/mendelian_randomisation.py \
  --instruments instruments.json --output results/

# Via ClawBio runner
python clawbio.py run mr --demo

Demo

python clawbio.py run mr --demo

Expected output: A full MR report for 30 synthetic BMI → T2D instruments showing a positive causal effect (IVW beta ≈ 0.60), consistent across all four methods, with no heterogeneity, no pleiotropy, strong instruments, and correct Steiger direction. Four plots generated.

Algorithm / Methodology

1. IVW: beta = sum(w * bx * by) / sum(w * bx²), with multiplicative random-effects variance inflation (Burgess et al., 2013)
2. MR-Egger: Weighted linear regression of by on bx with intercept; slope = causal estimate, intercept = pleiotropy (Bowden et al., 2015). Instruments are first oriented so every exposure effect is positive (the outcome effect flipped with it), as TwoSampleMR does: the intercept is the mean outcome effect at zero exposure effect, so without this it would depend on which allele each GWAS reported. An exposure effect of exactly zero counts as positive, so that instrument keeps its outcome effect (TwoSampleMR's sign0). Reported as not applicable, with a stated reason, when it is undefined on the given instruments: fewer than 3 of them (it fits two parameters, so below 3 there is no residual degree of freedom), or exposure effects too close to identical for the slope to be identified. Never a number in those cases.
3. Weighted Median: Median of Wald ratios weighted by inverse-variance; consistent when ≥50% weight from valid instruments (Bowden et al., 2016, doi:10.1002/gepi.21965; PMID 27061298)
4. Weighted Mode: Mode of the inverse-variance weighted kernel density of the Wald ratios, bandwidth phi x the modified Silverman rule 0.9 min(sd, 1.4826 mad) / L^(1/5), standard error from a parametric bootstrap (Hartwig et al., 2017, doi:10.1093/ije/dyx102; PMID 29040600; as implemented in TwoSampleMR mr_weighted_mode)

Key thresholds:

• F-statistic > 10 for instrument strength (Staiger & Stock, 1997)
• I²_GX > 0.9 for MR-Egger validity; SIMEX recommended below (Bowden et al., 2016)
• Cochran's Q P < 0.05 indicates heterogeneity
• Egger intercept P < 0.05 indicates directional pleiotropy. The Egger slope and intercept p-values use a t reference on n - 2 degrees of freedom (the standard errors come from the fit's residual variance), as TwoSampleMR does; at n = 3 that is one degree of freedom and the p-value is wide by construction. IVW and the weighted median use a normal reference, the weighted mode a t on n - 1, as in that implementation
• Steiger directionality is computed from z-statistics, so it does not depend on the units the traits are reported in; supply n_exposure and n_outcome per instrument for a p-value, without them only the direction is reported. The variance explained behind that p-value uses the continuous-trait conversion on both sides, so this version assumes the exposure and the outcome are continuous traits. A binary exposure or outcome in log odds is not supported (it needs case and control counts and the prevalence, which the input does not carry), and the note on the Steiger row states the assumption
• MR-Egger, weighted median and weighted mode each need >= 3 instruments (MR-Egger also needs at least two distinct exposure effects); below that each is reported as not applicable rather than as a number. IVW is defined at n = 1, where it is the single Wald ratio

Example Output

# Mendelian Randomisation Report

**Generated**: YYYY-MM-DD HH:MM:SS UTC
**Exposure**: Body mass index (BMI)
**Outcome**: Type 2 diabetes (T2D)
**Instruments**: 30 SNPs
**Mode**: Demo (cached data, offline)

## MR Estimates

| Method | Estimate | SE | 95% CI | P-value |
|--------|----------|----|--------|---------|
| IVW | 0.5979 | 0.0369 | [0.5255, 0.6702] | 5.17e-59 |
| MR-Egger | 0.6022 | 0.0816 | [0.4423, 0.7621] | 4.87e-08 |
| Weighted Median | 0.6001 | 0.0469 | [0.5081, 0.6921] | 2.07e-37 |
| Weighted Mode | 0.6031 | 0.0705 | [0.4648, 0.7413] | 2.03e-09 |

## Sensitivity Analysis

| Test | Result | P-value | Interpretation |
|------|--------|---------|----------------|
| Cochran's Q | 0.73 (df=29) | 1.0000 | No significant heterogeneity |
| Egger intercept | -0.0002 | 0.9526 | No directional pleiotropy |
| Mean F-statistic | 70.6 | — | Strong instruments |
| Weak instruments (F<10) | 0/30 | — | None |
| I²_GX | 0.9856 | — | Adequate |
| Steiger direction | Correct | not computed | Direction consistent with exposure → outcome; significance not assessable without sample sizes; no sample sizes supplied, so the direction is read from the z-statistics under the assumption that the exposure and outcome studies are of comparable size |

## Interpretation

The IVW estimate suggests a positive causal effect of Body mass index (BMI) on Type 2 diabetes (T2D)
(beta = 0.5979, 95% CI [0.5255, 0.6702], P = 5.17e-59).

Sensitivity analyses show consistent estimates across IVW, MR-Egger, Weighted Median, Weighted Mode, supporting a robust causal inference.

---

*ClawBio is a research and educational tool. It is not a medical device and does not provide clinical diagnoses. Consult a healthcare professional before making any medical decisions.*

Output Structure

output_directory/
├── report.md                              # STROBE-MR aligned report
├── result.json                            # Machine-readable estimates + sensitivity
├── tables/
│   ├── mr_results.tsv                     # Per-method estimates
│   ├── sensitivity.tsv                    # All sensitivity test results
│   └── harmonised_instruments.tsv         # Per-SNP instrument details + F-stat
├── figures/
│   ├── scatter.png                        # Exposure vs outcome effects
│   ├── forest.png                         # Per-SNP Wald ratios
│   ├── funnel.png                         # Precision vs effect
│   └── leave_one_out.png                  # IVW after removing each SNP
└── reproducibility/
    ├── commands.sh
    └── software_versions.json

Dependencies

Required:

• numpy >= 1.24 — numerical computation
• scipy >= 1.10 — statistical tests (t-test, chi2, norm)
• matplotlib >= 3.7 — scatter, forest, funnel, leave-one-out plots