/mendelian-randomisation

name: mendelian-randomisation
description: Two-sample Mendelian Randomisation from GWAS summary statistics with IVW, MR-Egger, weighted median/mode, and
  full sensitivity analysis (Cochran Q, Egger intercept, Steiger, F-statistic, leave-one-out).
license: MIT
metadata:
  version: 0.1.0
  author: Reza
  domain: genetic-epidemiology
  tags:
  - mendelian-randomisation
  - causal-inference
  - two-sample-mr
  - ivw
  - mr-egger
  - gwas
  - genetic-epidemiology
  - drug-target-validation
  inputs:
  - name: instruments
    type: file
    format:
    - json
    description: Harmonised instrument JSON with exposure/outcome effect sizes
    required: true
  outputs:
  - name: report
    type: file
    format: md
    description: STROBE-MR aligned interpretation report
  - name: result
    type: file
    format: json
    description: Machine-readable MR estimates and sensitivity results
  dependencies:
    python: '>=3.10'
    packages:
    - numpy>=1.24
    - scipy>=1.10
    - matplotlib>=3.7
  demo_data:
  - path: example_data/demo_instruments.json
    description: 30 synthetic BMI->T2D instruments for offline demo
  endpoints:
    cli: python skills/mendelian-randomisation/mendelian_randomisation.py --instruments {input_file} --output {output_dir}
  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: matplotlib
    trigger_keywords:
    - mendelian randomisation
    - mendelian randomization
    - MR analysis
    - two-sample MR
    - causal inference genetics
    - IVW
    - MR-Egger
    - instrumental variable
    - drug target validation MR
    - GWAS causal

🧬 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

| Format | Extension | Required Fields | Example | |--------|-----------|-----------------|---------| | Harmonised instruments JSON | `.json` | SNP, effect_allele, other_allele, eaf, beta_exposure, se_exposure, pval_exposure, beta_outcome, se_outcome, pval_outcome | `demo_instruments.json` |

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) 3. **Weighted Med