Causal Inference Pipeline (TWAS-Z + Mendelian Randomization)

Per-region pipeline that pairs QTL-derived weight vectors (TwasWeights and/or a QTL QtlFineMappingResult) with one or more GWAS studies (GwasSumStats) to produce per-tuple TWAS Z-scores and, when fine-mapping is supplied, Wald-ratio Mendelian Randomization estimates over the QTL credible sets.

Input combinations:

twasWeights alone (no fineMappingResult): TWAS Z only, no MR.
fineMappingResult alone (no twasWeights): TWAS Z derived from SuSiE-style coefficients carried on the topLoci slot of each FineMappingEntry; plus MR.
both: TWAS Z computed from twasWeights; MR computed from fineMappingResult.

Usage

causalInferencePipeline(
  gwasSumStats,
  twasWeights = NULL,
  fineMappingResult = NULL,
  rsqCutoff = 0,
  rsqPvalCutoff = Inf,
  rsqOption = "rsq",
  rsqPvalOption = c("adj_rsq_pval", "pval"),
  mrPipCutoff = 0.5,
  mrMethod = c("ivwPerVariant", "csAware"),
  mrCpipCutoff = 0.5,
  mrPvalCutoff = 1,
  combineMethods = NULL,
  alleleFlip = TRUE,
  ...
)

Arguments

gwasSumStats: A GwasSumStats object. Must be QC'd (length(getQcInfo(x)) > 0L).
twasWeights: Optional TwasWeights carrying per-(study, context, trait, method) weights. When supplied, drives the TWAS-Z computation.
fineMappingResult: Optional QtlFineMappingResult. When supplied, drives the MR computation and (when twasWeights = NULL) the TWAS-Z weights via the SuSiE-style coefficients on each entry's topLoci.
rsqCutoff: Numeric (length 1). When > 0, performs CV weight selection (ports the legacy twas_pipeline pick_best_model + update_twas_method): per (study, context, trait, gwasStudy) keep only the method whose cvResult rsqOption metric is highest among methods that clear both rsqCutoff and the rsqPvalCutoff gate AND that produced a finite TWAS Z (the NA/Inf re-selection); groups where no method clears the cutoffs are dropped. A group whose methods carry no usable cvResult (the SS-TWAS path) keeps all methods. Needs the twasWeights cvResult, so selection is a no-op on the fineMappingResult-only path. Default 0 (no selection; score every method).
rsqPvalCutoff: Numeric (length 1). CV-p-value gate for weight selection (ports legacy rsq_pval_cutoff): a method is eligible only when its cvResult rsqPvalOption metric is < rsqPvalCutoff. Default Inf (no p-value gate). A finite value activates selection even when rsqCutoff = 0.
rsqOption: Character. Which cvResult metric is the "r-squared" used for the cutoff and ranking (ports legacy rsq_option); typically "rsq" or "adj_rsq". Default "rsq".
rsqPvalOption: Character vector of candidate cvResult metric names for the p-value gate (ports legacy rsq_pval_option); the first one present in a tuple's metrics is used. Default c("adj_rsq_pval", "pval").
mrPipCutoff: Numeric (length 1). PIP threshold for a topLoci variant to be used as an instrumental variable. Used only when mrMethod = "ivwPerVariant". Default 0.5.
mrMethod: One of "ivwPerVariant" (default) or "csAware". The IVW-per-variant method filters topLoci variants by pip > mrPipCutoff and IVW-pools Wald ratios across variants. The CS-aware method groups variants by credible set (column cs in topLoci), computes a PIP-weighted composite Wald ratio per CS using mrCpipCutoff on the per-CS cumulative PIP, then IVW-pools across CSs and reports Cochran's Q + I-squared in the output columns Q, I2.
mrCpipCutoff: Numeric (length 1). Cumulative-PIP cutoff for retaining a credible set. Used only when mrMethod = "csAware". Default 0.5.
mrPvalCutoff: Numeric (length 1). TWAS-p-value gate for running MR (ports the legacy twas_pipeline mr_pval_cutoff): MR is computed for a (qtl tuple, gwas) only when its twasPval < mrPvalCutoff; otherwise the MR output columns are NA. Default 1 (no gate; MR runs wherever a fineMappingResult entry exists).
combineMethods: Optional character vector forwarded to combinePValues for cross-method combination per (qtlStudy, context, trait, gwasStudy) group. NULL (default) skips combination.
alleleFlip: Logical, default TRUE. When TRUE, match QTL variants to the GWAS by (chrom, pos) with ref/alt swaps recognized and the exposure effect / weight sign-flipped accordingly; when FALSE, match on exact alleles only, so a ref/alt swap is treated as a distinct variant.
...: Reserved.

Value

A GRanges as described above.

LD-sketch identity check

If a QTL input (TwasWeights or QtlFineMappingResult) carries a non-NULL ldSketch, it must match the ldSketch on gwasSumStats. Mismatch is a hard error. A QTL input with ldSketch = NULL (the fit was learned from individual-level data) skips the validation for that input.

Output shape

A long-format GRanges with one row per (qtlStudy, context, trait, method, gwasStudy) tuple, positioned at the variant span of the QTL weight set, with mcols:

qtlStudy, context, trait, method, gwasStudy: Identity columns.
twasZ, twasPval: Per-tuple TWAS Z and p-value.
waldRatio, waldRatioSe, mrPval: Per-tuple IVW-aggregated Wald-ratio MR estimate, standard error, and p-value. Present only when MR was computed; NA otherwise.
nIV: Number of instrumental variables used in the MR aggregation.