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

Examples

data(qtlDatasetExample)
data(gwasSumStatsS4Example)
tw <- twasWeightsPipeline(qtlDatasetExample,
  methods = "lasso", cisWindow = 1e6)
#>   Fitting lasso ...
#>   Fitting lasso done in 0.2s
#>   CV fold 1/5 ...
#>   CV fold 2/5 ...
#>   CV fold 3/5 ...
#>   CV fold 4/5 ...
#>   CV fold 5/5 ...
causalInferencePipeline(
  gwasSumStats = gwasSumStatsS4Example, twasWeights = tw)
#> GRanges object with 1 range and 14 metadata columns:
#>       seqnames            ranges strand |    qtlStudy     context        trait
#>          <Rle>         <IRanges>  <Rle> | <character> <character>  <character>
#>   [1]    chr22 14850625-15826991      * |      study1       brain ENSG_example
#>            method   gwasStudy     twasZ  twasPval waldRatio waldRatioSe
#>       <character> <character> <numeric> <numeric> <numeric>   <numeric>
#>   [1]       lasso      trait1  -0.23712  0.812563        NA          NA
#>          mrPval       nIV         Q        I2       nCs
#>       <numeric> <integer> <numeric> <numeric> <integer>
#>   [1]        NA      <NA>        NA        NA      <NA>
#>   -------
#>   seqinfo: 1 sequence from an unspecified genome; no seqlengths