Run multiple TWAS weight methods

Applies specified weight methods to the datasets X and Y, returning weight matrices for each method. Handles both univariate and multivariate methods, and filters out columns in X with zero standard error. This function utilizes parallel processing to handle multiple methods.

Usage

learnTwasWeights(
  X,
  Y,
  weightMethods,
  studyName = "",
  context = "",
  trait = "",
  numThreads = 1,
  fittedModels = NULL,
  fitRetention = c("none", "slim", "full"),
  weightStandardized = FALSE,
  weightsDataType = NULL,
  ldReference = NULL,
  verbose = 1,
  seed = NULL
)

Arguments

X

A matrix of samples by features, where each row represents a sample and each column a feature.

Y

A matrix (or vector, which will be converted to a matrix) of samples by outcomes, where each row corresponds to a sample.

weightMethods

A list of methods and their specific arguments, formatted as list(method1 = method1_args, method2 = method2_args), or alternatively a character vector of method names (eg, c("susie_weights", "enet_weights")) in which case default arguments will be used for all methods. methods in the list can be either univariate (applied to each column of Y) or multivariate (applied to the entire Y matrix).

studyName

Character. Study identity label recorded on the resulting weights.

context

Character. Context identity label recorded on the resulting weights.

trait

Character. Trait identity label recorded on the resulting weights.

numThreads

The number of threads to use for parallel processing. If set to -1, the function uses all available cores. If set to 0 or 1, no parallel processing is performed. If set to 2 or more, parallel processing is enabled with that many threads.

fittedModels

Named list of fitted SuSiE-family models, keyed by token (susie, susieInf, mvsusie, fsusie). Required whenever a SuSiE-family weight method is requested: those methods extract weights from an existing fit and never fine-map, so a missing fit is an error. Run fineMappingPipeline to produce the fits.

fitRetention

How much of each per-method fit is kept on the result: "none" (default) keeps none, "slim" keeps the trimmed payload downstream needs, "full" keeps the whole fitted object. Only the mr.mash methods distinguish "slim" from "full"; for every other method the two behave alike.

weightStandardized

Logical. Whether the supplied X / Y are already standardized. Default FALSE.

weightsDataType

Character or NULL. Data-type label recorded on the weights (e.g. "individual").

ldReference

An LD reference (a genotype panel, see readGenotypes, a GenotypeMixture or an LdMatrix) to record on the weights, or NULL.

verbose

Integer controlling verbosity level: 0 = suppress all messages, 1 = suppress external package messages (default), 2 = show all messages including those from external packages.

seed

Integer or NULL. When supplied, seeds the main-process RNG and the parallel method-fitting RNG via the BiocParallel RNGseed, for reproducibility under multi-threading. The main-process seed is scoped to the call, so the session RNG is left as it was found. NULL (default) does not seed at all.

Value

A list where each element is named after a method and contains the weight matrix produced by that method.

Examples

data(multiTraitData)
X <- multiTraitData$X[, 1:80]
Y <- multiTraitData$Y
# SuSiE-family methods extract weights from an existing fit and never
# fine-map themselves, so the fit is supplied via `fittedModels`.
fit <- susieR::susie(X, Y[, 1], L = 5)
#> HINT: nrow(X) = 400 >= 2 * ncol(X) = 160. Consider precomputing sufficient statistics with compute_suff_stat() and fitting with susie_ss() instead -- this avoids holding X in memory at every iteration and lets you reuse XtX across multiple y.
learnTwasWeights(X, Y[, 1, drop = FALSE],
  weightMethods = list(susie_weights = list()),
  fittedModels = list(susie = fit))
#>   Fitting susie ...
#>   Fitting susie done in 0.0s
#> TwasWeights: 1 entries
#>   1 studies, 1 contexts, 1 traits, 1 methods
#>   LD reference: NULL (individual-level fit)