Skip to contents

TWAS Weights Pipeline

Source: R/twasWeightsPipeline.R
twasWeightsPipeline.Rd

S4-dispatched per-region pipeline for learning TWAS prediction weights. Accepts:

  • a QtlDataset for individual-level cohort fits;

  • a QtlSumStats for per-trait RSS fits;

  • a GwasSumStats for per-LD-block PRS-CS-style fits from GWAS summary statistics.

Usage

twasWeightsPipeline(data, ...)

# S4 method for class 'QtlDataset'
twasWeightsPipeline(
  data,
  methods = "default",
  contexts = NULL,
  traitId = NULL,
  region = NULL,
  cisWindow = NULL,
  mafCutoff = NULL,
  macCutoff = NULL,
  xvarCutoff = NULL,
  imissCutoff = NULL,
  keepIndel = NULL,
  keepSamples = NULL,
  keepVariants = NULL,
  jointRegions = FALSE,
  jointSpecification = NULL,
  fineMappingResult = NULL,
  twasWeights = NULL,
  mashPrior = NULL,
  cvFolds = 5,
  samplePartition = NULL,
  fitFullData = TRUE,
  maxCvVariants = -1,
  cvThreads = 1,
  cvWeightMethods = NULL,
  ensemble = TRUE,
  ensembleR2Threshold = 0.01,
  ensembleSolver = "quadprog",
  ensembleAlpha = 1,
  estimatePi = TRUE,
  retainFit = TRUE,
  retainFitDetail = c("slim", "full"),
  phenotypeCovariatesToResidualize = NULL,
  genotypeCovariatesToResidualize = NULL,
  residualizePhenotypeCovariates = TRUE,
  residualizeGenotypeCovariates = TRUE,
  dataType = NULL,
  naAction = c("drop", "impute"),
  verbose = 1,
  ...
)

# S4 method for class 'QtlSumStats'
twasWeightsPipeline(
  data,
  methods = NULL,
  contexts = NULL,
  traitId = NULL,
  jointSpecification = NULL,
  fineMappingResult = NULL,
  twasWeights = NULL,
  retainFit = TRUE,
  retainFitDetail = c("slim", "full"),
  dataType = NULL,
  verbose = 1L,
  ...
)

# S4 method for class 'MultiStudyQtlDataset'
twasWeightsPipeline(
  data,
  methods = "default",
  contexts = NULL,
  traitId = NULL,
  region = NULL,
  cisWindow = NULL,
  jointRegions = FALSE,
  jointSpecification = NULL,
  fineMappingResult = NULL,
  twasWeights = NULL,
  retainFit = TRUE,
  retainFitDetail = c("slim", "full"),
  naAction = c("drop", "impute"),
  verbose = 1,
  phenotypeCovariatesToResidualize = NULL,
  genotypeCovariatesToResidualize = NULL,
  residualizePhenotypeCovariates = TRUE,
  residualizeGenotypeCovariates = TRUE,
  ...
)

# S4 method for class 'ANY'
twasWeightsPipeline(data, ...)

Arguments

data

A QtlDataset, MultiStudyQtlDataset, or QtlSumStats. The MultiStudyQtlDataset method iterates the embedded individual-level QtlDataset entries and the optional embedded QtlSumStats, then rbinds the results.

...

Reserved for method-specific arguments.

methods

A character vector of short method names, a preset string ("default" or "fast_default"), or a named list of <method>_weights = args entries. For QtlSumStats / GwasSumStats inputs the default switches to the RSS preset (c("susieRss", "susieInfRss", "lassosumRss", "prsCs", "sdpr")).

contexts

Optional character vector of contexts to restrict processing to (QtlDataset / QtlSumStats inputs). Default NULL (use all contexts).

traitId

Optional character vector of trait identifiers to restrict processing to (QtlDataset / QtlSumStats inputs). Default NULL.

region

Optional variant window for QtlDataset trait selection: a GRanges, a "chr:start-end" string, or a one-row data.frame with chrom/start/end. Mutually exclusive with traitId.

cisWindow

For QtlDataset: cis-window (bp) around each trait's genomic position when extracting variants. Required when traitId is supplied. Mutually exclusive with region.

mafCutoff, macCutoff, xvarCutoff, imissCutoff, keepIndel, keepSamples, keepVariants

For QtlDataset: optional per-call genotype-filter overrides. Each replaces the corresponding construct-time QtlDataset slot for this call only (applied to a validated copy); NULL (default) leaves the stored value in place. Variant QC is a property of the data, so these are applied identically here and in fineMappingPipeline – there is deliberately no TWAS-specific variant filter.

jointRegions

For QtlDataset with a multi-range region: FALSE (default) learns weights for each range independently and concatenates them into one entry per (study, context, trait, method); the per-region fits are kept as a named list and per-region CV is recorded as a flat cvResult data frame (one row per region). TRUE concatenates the ranges' genotypes into one joint fit. Ignored for a single-range / cis request.

jointSpecification

Optional joint-fit specification (NULL by default). When NULL, the pipeline runs the implicit multi-trait / multi-context mr.mash branches as before. When non-NULL, the argument is parsed and validated via the joint-spec grammar documented under parseJointSpecification; the per-spec axis dispatcher implementation is in progress and a non-NULL value currently errors with an informative message.

fineMappingResult

Optional FineMappingResult. When supplied, its SuSiE / SuSiE-inf / SuSiE-ash trimmed fits for the matching (study, context, trait) tuples are injected into learnTwasWeights via fittedModels so SuSiE-family weight methods reuse the prior fit instead of refitting.

twasWeights

Optional TwasWeights resume cache. For each requested (study, context, trait, method) tuple already present in this collection, the cached TwasWeightsEntry is copied through and the corresponding weight fit is skipped. Only the un-cached method subset is fit; the cached and fresh entries are concatenated in the returned collection. Per-tuple matching mirrors the fineMappingResult cache in fineMappingPipeline. Multivariate dispatch (mvsusie, mr.mash) is unaffected because those methods produce one fit jointly across multiple (context, trait) columns.

cvFolds

Integer. Cross-validation folds. Default 5. Set to 0 to skip CV (and ensemble).

samplePartition

Optional pre-defined CV partition data.frame.

maxCvVariants

Maximum number of variants for CV. Default -1 (no limit).

cvThreads

Threads for CV parallelism. Default 1.

cvWeightMethods

Optional override of methods used for CV.

ensemble

Logical. Compute SR-TWAS ensemble weights. Default TRUE.

ensembleR2Threshold

Minimum CV R-squared for ensemble inclusion. Default 0.01.

ensembleSolver

Solver for ensemble stacking. Default "quadprog".

ensembleAlpha

Elastic-net mixing parameter (only when ensembleSolver = "glmnet"). Default 1.

estimatePi

If TRUE, estimate spike-and-slab sparsity from mr.ash before BGLR / qgg spike-and-slab methods that consume it.

phenotypeCovariatesToResidualize, genotypeCovariatesToResidualize

Character vector (or NULL) of covariate column names to residualize against. Forwarded to getResidualizedPhenotypes / getResidualizedGenotypes for QtlDataset / MultiStudyQtlDataset input. Default NULL (use all available covariates). Ignored for sumstat inputs.

residualizePhenotypeCovariates

Logical (length 1). When TRUE (default) residualize against the phenotype-side covariates listed in phenotypeCovariatesToResidualize; set FALSE to disable.

residualizeGenotypeCovariates

Logical (length 1). When TRUE (default) residualize against the genotype-side covariates listed in genotypeCovariatesToResidualize; set FALSE to disable.

dataType

Optional data-type tag stamped into every TwasWeightsEntry$dataType (e.g. "expression").

verbose

Verbosity (0 silent, 1 default, 2 includes external package messages).

Value

A TwasWeights collection keyed by (study, context, trait, method). The ldSketch slot is NULL for individual-level fits and equals the input's ldSketch for RSS-derived fits.

Details

Method-restriction rules (enforced):

  • mr.mash, mvsusie follow the multi-trait / multi-context rules of the fine-mapping mvsusie family (require at least two traits OR at least two contexts).

  • RSS-only methods (PRS-CS, lassosumRss, SDPR, all *Rss variants) are rejected on QtlDataset input.

  • Individual-level-only methods (BGLR and CRAN-stable qgg: bayes_a/b/c/l/n/r, b_lasso, dpr_*) are rejected on QtlSumStats / GwasSumStats input.

Both QtlSumStats and GwasSumStats inputs must have been QC'd via summaryStatsQc first; otherwise an error is raised pointing at that function.

The returned TwasWeights collection's ldSketch slot is set automatically: NULL for individual-level fits, the input's ldSketch for RSS-derived fits.

Optionally a FineMappingResult may be supplied as a source of pre-fit SuSiE / SuSiE-inf / SuSiE-ash objects; their trimmedFit payloads are passed through to learnTwasWeights / the RSS sub-pipelines via the fittedModels slot, avoiding a re-fit.

When the supplied FineMappingResult was produced with cross-validation (fineMappingPipeline(..., cvFolds > 1)), each matching (study, context, trait) entry's cvResult is reused: its fold partition becomes the CV partition (unless samplePartition is given explicitly) and its per-fold out-of-fold predictions/metrics are fed directly into the SR-TWAS ensemble in place of re-fitting those fine-mapping methods here. Non-fine-mapping methods (lasso, enet, ...) are still cross-validated on the same shared partition.