@bgicli/bgicli 2.1.1 → 2.2.0

package/data/workflows/mendelian-randomization-twosamplemr/references/interpretation-guide.md

@@ -0,0 +1,239 @@
+# MR Results Interpretation Guide
+
+## Quick Decision Tree
+
+```
+1. Is the IVW estimate significant (p < 0.05)?
+   ├── YES → Go to step 2
+   └── NO  → No evidence for causal effect (check power)
+
+2. Do all methods agree on direction?
+   ├── YES → Go to step 3
+   └── NO  → Caution: methods disagree, investigate pleiotropy
+
+3. Is there significant heterogeneity (Q p < 0.05)?
+   ├── YES → Some instruments may be invalid; rely more on robust methods
+   └── NO  → Go to step 4
+
+4. Is there directional pleiotropy (Egger intercept p < 0.05)?
+   ├── YES → IVW may be biased; prefer MR-Egger or weighted median estimate
+   └── NO  → Go to step 5
+
+5. Is the Steiger direction correct?
+   ├── YES → Evidence supports proposed causal direction
+   └── NO  → Reverse causation concern; test bidirectional MR
+
+6. Is leave-one-out stable?
+   ├── YES → Strong evidence for causality
+   └── NO  → Investigate influential SNPs; result may be driven by one locus
+```
+
+## Reading the Results Table
+
+The `mr_results.csv` contains one row per method:
+
+| Column | Description                    |
+| ------ | ------------------------------ |
+| method | MR method name                 |
+| nsnp   | Number of instruments used     |
+| b      | Causal effect estimate (beta)  |
+| se     | Standard error of the estimate |
+| pval   | P-value for the causal effect  |
+
+**Interpreting the beta:**
+
+- **Continuous exposure → continuous outcome**: 1-unit increase in
+  genetically-predicted exposure → b units change in outcome
+- **Continuous exposure → binary outcome (log-OR)**: 1-unit increase in exposure
+  → exp(b) odds ratio for outcome
+- **Binary exposure (log-OR) → continuous outcome**: 1 log-OR increase in
+  liability → b units change in outcome
+
+## Reading the Sensitivity Results
+
+### Heterogeneity (heterogeneity_results.csv)
+
+| Column | What it means                                       |
+| ------ | --------------------------------------------------- |
+| Q      | Cochran's Q statistic (larger = more heterogeneity) |
+| Q_df   | Degrees of freedom (number of SNPs - 1 for IVW)     |
+| Q_pval | P-value (< 0.05 means significant heterogeneity)    |
+
+### Pleiotropy (pleiotropy_results.csv)
+
+| Column          | What it means                                          |
+| --------------- | ------------------------------------------------------ |
+| egger_intercept | MR-Egger intercept (should be ~0 if no pleiotropy)     |
+| se              | Standard error of intercept                            |
+| pval            | P-value (< 0.05 means directional pleiotropy detected) |
+
+### Directionality (directionality_results.csv)
+
+| Column                   | What it means                          |
+| ------------------------ | -------------------------------------- |
+| snp_r2.exposure          | Variance in exposure explained by SNPs |
+| snp_r2.outcome           | Variance in outcome explained by SNPs  |
+| correct_causal_direction | TRUE if exposure R² > outcome R²       |
+| steiger_pval             | P-value for directionality test        |
+
+## Reading the Plots
+
+### Scatter Plot
+
+- **What to look for**: Points should cluster around the IVW line
+- **Good sign**: All method lines have similar slopes
+- **Bad sign**: MR-Egger line has very different slope from IVW (suggests
+  pleiotropy)
+- **Bad sign**: Points scattered widely (heterogeneity)
+
+### Forest Plot
+
+- **What to look for**: Individual SNP estimates should overlap with the
+  combined estimate
+- **Good sign**: Most CIs cross the combined estimate line
+- **Bad sign**: One or two SNPs far from the rest (potential
+  outliers/pleiotropic instruments)
+
+### Funnel Plot
+
+- **What to look for**: Symmetric distribution around the IVW estimate
+- **Good sign**: Symmetric funnel shape, most precise estimates near center
+- **Bad sign**: Asymmetry suggests directional pleiotropy or bias
+
+### Leave-One-Out Plot
+
+- **What to look for**: Estimates should be stable regardless of which SNP is
+  removed
+- **Good sign**: All points within a narrow range, CIs overlap
+- **Bad sign**: Removing one SNP dramatically shifts the estimate (that SNP is
+  influential)
+
+## Instrument Strength (F-statistics)
+
+Each instrument's strength is measured by its F-statistic: F = (beta_exposure /
+se_exposure)^2.
+
+- **F > 10 per instrument**: Rule of thumb for sufficient instrument strength
+- **Mean F > 10**: Overall instruments are adequately strong
+- **F < 10**: Weak instrument — biases MR estimate toward the confounded
+  observational estimate (toward null for two-sample MR)
+- **Report**: Always report mean F-statistic, minimum F, and number of weak
+  instruments
+
+## MR-PRESSO (Outlier Detection)
+
+MR-PRESSO (Mendelian Randomization Pleiotropy RESidual Sum and Outlier) formally
+tests for and removes outlier instruments.
+
+- **When to run**: When Cochran's Q test shows significant heterogeneity (p <
+  0.05)
+- **Global test p < 0.05**: Significant outliers exist among instruments
+- **Outlier test**: Identifies which specific SNPs are outliers
+- **Distortion test**: Tests whether removing outliers significantly changes the
+  IVW estimate
+- **Outlier-corrected estimate**: IVW re-estimated after removing identified
+  outliers
+- **Important**: MR-PRESSO only detects outliers; biological investigation of
+  flagged SNPs is still required
+
+## Method Disagreement
+
+When MR methods disagree, this warrants explicit discussion — not dismissal.
+
+**Weighted Mode non-significant but others significant:**
+
+- Weighted Mode has lower power than IVW or Weighted Median
+- Non-significance may reflect low power rather than absence of effect
+- However, if Weighted Mode points in the **opposite direction**, this is a
+  stronger concern
+- Always report and discuss — do not omit non-significant methods from the
+  summary
+
+**Discordant directions across methods:**
+
+- If any method shows effect in the opposite direction to IVW, this is a red
+  flag for pleiotropy
+- Investigate the specific instruments driving the disagreement
+- Consider MR-PRESSO to identify and remove pleiotropic outliers
+
+## Binary Outcomes and Steiger Test
+
+For binary (case-control) outcomes:
+
+- **Default R² calculation assumes quantitative traits** — this is incorrect for
+  binary outcomes
+- **Correct approach**: Use `get_r_from_lor()` to convert log-odds ratios to R²
+  on the liability scale
+- **Requires**: Effect allele frequency, number of cases/controls, and
+  population prevalence
+- **If case/control info unavailable**: Flag that Steiger R² for the outcome may
+  be inaccurate
+- **Impact**: Incorrect R² can lead to wrong conclusions about causal direction
+
+## Common Scenarios
+
+### Scenario 1: Clean causal effect
+
+- IVW significant, all methods agree, no heterogeneity, no pleiotropy, correct
+  direction
+- **Conclusion**: Strong evidence for causal effect
+
+### Scenario 2: Heterogeneity but consistent direction
+
+- IVW significant, methods agree on direction, Q p < 0.05, Egger intercept p >
+  0.05
+- **Conclusion**: Likely causal but some instruments may act through other
+  pathways; weighted median provides a more robust estimate
+
+### Scenario 3: Directional pleiotropy detected
+
+- IVW significant, Egger intercept p < 0.05, Egger slope differs from IVW
+- **Conclusion**: IVW may be biased; if MR-Egger slope is significant, causality
+  may still hold but effect size is uncertain. Consider MR-PRESSO for outlier
+  removal.
+
+### Scenario 4: Methods disagree on direction
+
+- IVW positive, MR-Egger negative (or vice versa)
+- **Conclusion**: Weak evidence; substantial pleiotropy likely. Do not claim
+  causality.
+
+### Scenario 5: Result driven by one SNP
+
+- Leave-one-out shows one SNP dramatically changes the estimate
+- **Conclusion**: Investigate that SNP's biology. If it's in a pleiotropic
+  region, consider removing it and re-running.
+
+### Scenario 6: Extreme heterogeneity with discordant outlier SNPs
+
+- Cochran's Q p < 1e-10, single-SNP analysis reveals SNPs with
+  opposite-direction effects
+- MR-PRESSO identifies specific outlier instruments
+- **Conclusion**: Run outlier-corrected analysis. Compare original vs corrected
+  estimates. Investigate biology of outlier SNPs (e.g., pleiotropic loci like
+  APOE). Report both estimates.
+
+### Scenario 7: Weighted Mode disagrees with other methods
+
+- IVW, MR-Egger, Weighted Median significant and concordant; Weighted Mode
+  non-significant
+- **Conclusion**: May reflect lower statistical power of Weighted Mode. If
+  direction is concordant, causality is still supported. If direction is
+  discordant, investigate pleiotropy. Always report explicitly.
+
+## Caveats
+
+1. **MR estimates reflect lifelong exposure** — genetic variants are fixed at
+   conception, so MR estimates reflect the effect of long-term differences in
+   exposure, not acute interventions
+2. **Population-specific** — instruments may have different effects across
+   ancestries
+3. **Linear assumption** — standard MR assumes a linear dose-response
+   relationship
+4. **Cannot distinguish closely related traits** — if BMI and waist
+   circumference share instruments, MR cannot determine which is the true causal
+   factor
+5. **Winner's curse** — selecting instruments from the same GWAS as estimation
+   can inflate associations
+6. **Sample overlap** — if exposure and outcome GWAS share participants, can
+   introduce bias (use two-sample design to minimize)

package/data/workflows/mendelian-randomization-twosamplemr/references/method-reference.md

@@ -0,0 +1,190 @@
+# MR Methods Reference
+
+## Overview
+
+Two-sample Mendelian Randomization uses genetic variants (SNPs) as
+**instrumental variables** to estimate the causal effect of an exposure on an
+outcome. The genetic variants must satisfy three core assumptions:
+
+1. **Relevance**: Variants are associated with the exposure (F-statistic > 10)
+2. **Independence**: Variants are not associated with confounders
+3. **Exclusion restriction**: Variants affect the outcome only through the
+   exposure
+
+## Primary Methods
+
+### Inverse-Variance Weighted (IVW)
+
+The **default primary method**. Combines individual SNP Wald ratio estimates
+(β_outcome / β_exposure) using inverse-variance meta-analysis.
+
+- **Assumption**: All instruments are valid (no horizontal pleiotropy), or
+  pleiotropy is balanced (equally likely positive/negative)
+- **Strengths**: Most statistically efficient method; well-understood properties
+- **Limitations**: Biased if directional pleiotropy exists
+- **Interpretation**: The causal estimate represents the change in outcome per
+  unit change in genetically-predicted exposure
+- **Variants**: Fixed-effects (homogeneous instruments) and multiplicative
+  random-effects (heterogeneous instruments; **recommended by default**)
+
+### MR-Egger Regression
+
+Relaxes the exclusion restriction by allowing **all** instruments to have
+pleiotropic effects, provided pleiotropy is independent of instrument strength
+(InSIDE assumption).
+
+- **Assumption**: Instrument Strength Independent of Direct Effect (InSIDE)
+- **Strengths**: Provides both a causal estimate and a **pleiotropy test**
+  (intercept ≠ 0 indicates directional pleiotropy)
+- **Limitations**: Less efficient than IVW; sensitive to outliers; InSIDE may
+  not hold
+- **Intercept interpretation**:
+  - Intercept ≈ 0 (p > 0.05): No evidence of directional pleiotropy → IVW likely
+    valid
+  - Intercept ≠ 0 (p < 0.05): Directional pleiotropy present → IVW may be biased
+
+### Weighted Median
+
+Provides a consistent estimate if **at least 50% of instruments are valid**
+(majority valid assumption).
+
+- **Assumption**: Majority of information comes from valid instruments
+- **Strengths**: Robust to outliers; less sensitive to individual variant
+  removal
+- **Limitations**: Sensitive to addition/removal of variants near the validity
+  boundary
+- **When to prefer**: When heterogeneity suggests some instruments may be
+  invalid
+
+### Weighted Mode
+
+Provides a consistent estimate if the **largest group of instruments**
+identifies the same causal effect (plurality valid assumption).
+
+- **Assumption**: The most common causal estimate across instruments is the
+  correct one
+- **Strengths**: Most robust to outliers; weakest assumptions about instrument
+  validity
+- **Limitations**: Low precision; conservative confidence intervals
+- **When to prefer**: When substantial pleiotropy is suspected
+
+## Sensitivity Analyses
+
+### Cochran's Q Test (Heterogeneity)
+
+Tests whether individual SNP estimates are more variable than expected by
+chance.
+
+- **Q p > 0.05**: No significant heterogeneity → instruments behave consistently
+- **Q p < 0.05**: Significant heterogeneity → some instruments may be invalid or
+  pleiotropic
+- **Note**: Some heterogeneity is expected even with valid instruments; use
+  alongside other tests
+
+### MR-Egger Intercept (Directional Pleiotropy)
+
+Tests whether the MR-Egger intercept differs from zero.
+
+- **p > 0.05**: No evidence of directional pleiotropy → IVW estimate likely
+  unbiased
+- **p < 0.05**: Directional pleiotropy detected → IVW may be biased; consider
+  MR-Egger slope or robust methods
+
+### Steiger Directionality Test
+
+Tests whether the genetic variants explain more variance in the exposure than
+the outcome, confirming the hypothesized causal direction.
+
+- **correct_causal_direction = TRUE**: Variants are stronger instruments for
+  exposure → supports proposed direction
+- **correct_causal_direction = FALSE**: Variants explain more outcome variance →
+  reverse causation concern
+- **Limitation**: Requires sample size information; may fail if metadata is
+  incomplete
+
+### Leave-One-Out Analysis
+
+Removes each SNP in turn and re-estimates the IVW effect.
+
+- **Stable estimates**: No single SNP drives the result → robust finding
+- **Estimate changes >20%**: That SNP may be an influential outlier (potentially
+  pleiotropic)
+- **Use**: Identify and investigate influential instruments; consider removing
+  if biologically justified
+
+### Single-SNP (Wald Ratio) Analysis
+
+Computes the causal estimate for each SNP individually.
+
+- **Concordant directions**: Most SNPs point the same way → consistent evidence
+- **Discordant SNPs**: May indicate pleiotropy or different biological
+  mechanisms
+- **Use**: Complement to forest plot visualization
+
+## Diagnostic Plots
+
+### Scatter Plot
+
+- **X-axis**: SNP-exposure associations (β_exposure)
+- **Y-axis**: SNP-outcome associations (β_outcome)
+- **Lines**: Slopes from each MR method (IVW, Egger, WM, WMode)
+- **Interpretation**: Points clustering around lines = concordant estimates;
+  spread = heterogeneity
+
+### Forest Plot
+
+- Each SNP's individual Wald ratio estimate with 95% CI
+- Combined estimates from IVW and MR-Egger shown at bottom
+- **Interpretation**: Overlapping CIs = consistent instruments; outliers visible
+
+### Funnel Plot
+
+- **X-axis**: Individual SNP causal estimates
+- **Y-axis**: Precision (1/SE)
+- **Interpretation**: Symmetric funnel = no directional pleiotropy; asymmetry =
+  bias concern
+
+### Leave-One-Out Plot
+
+- IVW estimate when each SNP is removed, with 95% CI
+- **Interpretation**: Horizontal line stability = robust; shifts = influential
+  SNP
+
+## Evidence Assessment Framework
+
+**Strong evidence for causality** (all of):
+
+- IVW p < 0.05 with meaningful effect size
+- Concordant direction across all 4 methods (including Weighted Mode)
+- No significant heterogeneity (Q p > 0.05)
+- No directional pleiotropy (Egger intercept p > 0.05)
+- Correct Steiger direction (with liability-scale R² for binary outcomes)
+- Robust to leave-one-out
+- Mean F-statistic > 10 (adequate instrument strength)
+
+**Suggestive evidence** (some of):
+
+- IVW significant but one method non-significant (discuss explicitly)
+- Some heterogeneity but consistent direction; MR-PRESSO corrected estimate
+  still significant
+- Leave-one-out mostly stable
+
+**Weak/inconclusive** (any of):
+
+- Methods disagree on direction (any method opposite to IVW)
+- Strong heterogeneity with discordant outlier SNPs
+- Significant pleiotropy
+- Few instruments (<10 SNPs)
+- Incorrect Steiger direction
+- Weak instruments (mean F < 10)
+
+## References
+
+- Sanderson E, et al. (2022). Mendelian randomization. _Nat Rev Methods
+  Primers_. PMC7384151
+- Bowden J, et al. (2015). Mendelian randomization with invalid instruments.
+  _Stat Med_. 34(15):2313-25
+- Bowden J, et al. (2016). Consistent estimation in MR with some invalid
+  instruments. _Genet Epidemiol_. 40(4):304-14
+- Hartwig FP, et al. (2017). Robust inference in summary data MR using the
+  weighted mode. _Int J Epidemiol_. 46(6):1717-26

package/data/workflows/mendelian-randomization-twosamplemr/scripts/export_results.R

@@ -0,0 +1,123 @@
+# =============================================================================
+# Mendelian Randomization - Export Results
+# =============================================================================
+# Functions:
+#   export_all()  - Export all MR results, sensitivity analyses, RDS object, and PDF report
+# =============================================================================
+
+#' Export all MR analysis results
+#'
+#' Saves:
+#'   1. mr_results.csv - Primary MR estimates (all methods)
+#'   2. heterogeneity_results.csv - Cochran's Q test results
+#'   3. pleiotropy_results.csv - MR-Egger intercept test
+#'   4. directionality_results.csv - Steiger directionality test
+#'   5. harmonized_data.csv - SNP-level harmonized data
+#'   6. single_snp_results.csv - Per-SNP Wald ratio estimates
+#'   7. leaveoneout_results.csv - Leave-one-out estimates
+#'   8. mr_object.rds - Complete analysis object for downstream use
+#'   9. mr_report.pdf - Structured analysis report (auto-generated)
+#'
+#' @param mr_results MR results from run_mr()
+#' @param sensitivity_results Sensitivity list from run_sensitivity()
+#' @param dat Harmonized data from load_data.R
+#' @param output_dir Directory for saving results (default: "mr_results")
+export_all <- function(mr_results, sensitivity_results, dat,
+                        output_dir = "mr_results") {
+    cat("\n=== Exporting MR Results ===\n\n")
+
+    if (!dir.exists(output_dir)) {
+        dir.create(output_dir, recursive = TRUE)
+    }
+
+    file_count <- 0
+
+    # 1. Primary MR results
+    cat("1. MR results (all methods)...\n")
+    write.csv(mr_results, file.path(output_dir, "mr_results.csv"), row.names = FALSE)
+    cat("   Saved: mr_results.csv\n")
+    file_count <- file_count + 1
+
+    # 2. Heterogeneity results
+    cat("2. Heterogeneity test results...\n")
+    write.csv(sensitivity_results$heterogeneity,
+              file.path(output_dir, "heterogeneity_results.csv"), row.names = FALSE)
+    cat("   Saved: heterogeneity_results.csv\n")
+    file_count <- file_count + 1
+
+    # 3. Pleiotropy results
+    cat("3. Pleiotropy test results...\n")
+    write.csv(sensitivity_results$pleiotropy,
+              file.path(output_dir, "pleiotropy_results.csv"), row.names = FALSE)
+    cat("   Saved: pleiotropy_results.csv\n")
+    file_count <- file_count + 1
+
+    # 4. Directionality results
+    cat("4. Directionality test results...\n")
+    if (!is.null(sensitivity_results$directionality)) {
+        write.csv(sensitivity_results$directionality,
+                  file.path(output_dir, "directionality_results.csv"), row.names = FALSE)
+        cat("   Saved: directionality_results.csv\n")
+        file_count <- file_count + 1
+    } else {
+        cat("   Skipped (directionality test was not available)\n")
+    }
+
+    # 5. Harmonized data
+    cat("5. Harmonized SNP-level data...\n")
+    write.csv(dat, file.path(output_dir, "harmonized_data.csv"), row.names = FALSE)
+    cat("   Saved: harmonized_data.csv\n")
+    file_count <- file_count + 1
+
+    # 6. Single-SNP results
+    cat("6. Single-SNP Wald ratio results...\n")
+    write.csv(sensitivity_results$singlesnp,
+              file.path(output_dir, "single_snp_results.csv"), row.names = FALSE)
+    cat("   Saved: single_snp_results.csv\n")
+    file_count <- file_count + 1
+
+    # 7. Leave-one-out results
+    cat("7. Leave-one-out results...\n")
+    write.csv(sensitivity_results$leaveoneout,
+              file.path(output_dir, "leaveoneout_results.csv"), row.names = FALSE)
+    cat("   Saved: leaveoneout_results.csv\n")
+    file_count <- file_count + 1
+
+    # 8. Complete analysis object (RDS)
+    cat("8. Complete analysis object (RDS)...\n")
+    mr_object <- list(
+        mr_results = mr_results,
+        sensitivity = sensitivity_results,
+        harmonized_data = dat,
+        metadata = list(
+            date = Sys.time(),
+            exposure = unique(dat$exposure),
+            outcome = unique(dat$outcome),
+            n_instruments = nrow(dat),
+            methods = mr_results$method,
+            r_version = R.version.string,
+            twosamplemr_version = as.character(packageVersion("TwoSampleMR"))
+        )
+    )
+    saveRDS(mr_object, file.path(output_dir, "mr_object.rds"))
+    cat("   Saved: mr_object.rds\n")
+    cat("   (Load with: mr_obj <- readRDS('mr_results/mr_object.rds'))\n")
+    file_count <- file_count + 1
+
+    # 9. Generate analysis report (PDF)
+    cat("9. Generating analysis report...\n")
+    tryCatch({
+        source("scripts/generate_report.R")
+        generate_report(mr_results, sensitivity_results, dat, output_dir)
+        file_count <- file_count + 1
+    }, error = function(e) {
+        cat("   Warning: Report generation failed (", conditionMessage(e), ")\n")
+        cat("   All other exports completed successfully.\n")
+    })
+
+    # Summary
+    cat("\n  Files saved to:", output_dir, "/\n")
+    cat("  Total files:", file_count, "\n")
+
+    cat("\n=== Export Complete ===\n")
+}