Assemble cTWAS inputs from S4 GwasSumStats / TwasWeights

Builds the per-block ctwas-shape input set (z_snp, weights, region_info, snp_map, LD_map, the LD- and SNP-info loader closures, plus optional z_gene) that the downstream ctwas steps consume. This is step 1 of the three-step ctwasPipeline split.

Usage

assembleCtwasInputs(
  gwasSumStats,
  twasWeights,
  twasZ = NULL,
  fineMappingResult = NULL,
  method = NULL,
  twasWeightCutoff = 0,
  csMinCor = 0.8,
  minPipCutoff = 0,
  maxNumVariants = Inf
)

Arguments

gwasSumStats: NAMED LIST of GwasSumStats keyed by region_id (at least two entries). Each must have getQcInfo() non-empty.
twasWeights: The per-gene weight source. Either (a) a FLAT TwasWeights / QtlFineMappingResult (or a homogeneous list of them) carrying region provenance — each gene is placed into its home LD block internally by start(region) (matching cTWAS's p0 assignment rule); or (b) a pre-bucketed NAMED LIST keyed by region_id (keys a SUBSET of gwasSumStats's), used as-is. Blocks without any TWAS weights still contribute their SNP-level signal to ctwas's joint group prior estimate (the legacy whole-chromosome pattern where only a few of many LD blocks carry gene weights). A gene whose cis span straddles a block boundary is homed by its single anchor; the cross-block signal is cTWAS's boundary-gene concern (mergeCtwasBoundaryRegions), not placement.
twasZ: Optional GRanges of TWAS Z-scores (output of causalInferencePipeline). When supplied, the per-(trait, context) Z is used as the z_gene input to ctwas_sumstats so it is not recomputed.
fineMappingResult: Optional QtlFineMappingResult or GwasFineMappingResult carrying the per-variant PIP and credible-set membership data used by the CS / PIP rescue filters (csMinCor and minPipCutoff). When NULL (default) the smart filters are no-ops; only the magnitude filter (twasWeightCutoff) and the per-gene cap (maxNumVariants, ordered by |weight|) apply.
method: Optional character (length 1). Picks which TWAS method's weights to feed into ctwas for each (study, context, trait) gene. When NULL (default): use "ensemble" if that method is present across the weight sources; otherwise use the sole method when only one is present; otherwise run every method as an independent cTWAS run (one CtwasResult row-set per method). Passing the name explicitly (e.g. "mrash") restricts the run to that single method.
twasWeightCutoff: Numeric (length 1). Drop variants with |weight| < twasWeightCutoff from each gene's weight matrix before ctwas sees it. Default 0 (no filter).
csMinCor: Numeric (length 1). When fineMappingResult is provided, variants belonging to any 95% credible set with purity (min_abs_corr) >= csMinCor are marked as must-keep and survive the per-gene cap. Default 0.8. Ignored without a fineMappingResult.
minPipCutoff: Numeric (length 1). When fineMappingResult is provided, variants with PIP greater than minPipCutoff are marked as must-keep and survive the per-gene cap. Default 0 (no PIP rescue). Ignored without a fineMappingResult.
maxNumVariants: Numeric (length 1). Cap on per-gene variant count. When the gene has more variants than this, keep all must-keep variants and fill remaining slots by descending PIP (when available) or descending |weight|. Default Inf (no cap).

Value

A list with elements z_snp, z_gene (NULL when no twasZ), weights, region_info, snp_map, LD_map, LD_loader_fun, snpinfo_loader_fun, and resolvedMethod.

Details

The returned list is the SHARED STATE threaded through estCtwasParam → screenCtwasRegions → finemapCtwasRegions. Callers can short-circuit at any step (e.g. override the estimated priors before fine-mapping) or call ctwasPipeline() for the one-shot path.