Cross-Validation for weights selection in Transcriptome-Wide Association Studies (TWAS)

Performs cross-validation for TWAS, supporting both univariate and multivariate methods. It can either create folds for cross-validation or use pre-defined sample partitions. For multivariate methods, it applies the method to the entire Y matrix for each fold.

Usage

twasWeightsCv(
  X,
  Y,
  fold = NULL,
  samplePartitions = NULL,
  weightMethods = NULL,
  maxNumVariants = NULL,
  variantsToKeep = NULL,
  numThreads = 1,
  verbose = 1,
  fitRetention = c("none", "slim", "full"),
  seed = NULL,
  dataDrivenPriorMatricesCv = NULL,
  reweightedMixturePriorCv = NULL,
  fittedModelsCv = 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.
fold: An optional integer specifying the number of folds for cross-validation. If NULL, 'samplePartitions' must be provided.
samplePartitions: An optional dataframe with predefined sample partitions, containing columns 'Sample' (sample names) and 'Fold' (fold number). If NULL, 'fold' must be provided.
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).
maxNumVariants: An optional integer to set the randomly selected maximum number of variants to use for CV purpose, to save computing time.
variantsToKeep: An optional integer to ensure that the listed variants are kept in the CV when there is a limit on the maxNumVariants to use.
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.
verbose: Integer controlling verbosity level: 0 = suppress all messages, 1 = suppress external package messages (default), 2 = show all messages including those from external packages.
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.
seed: Integer or NULL. When supplied, seeds both the main-process RNG (fold partitioning, variant sub-sampling) and the parallel fold-fitting RNG via the BiocParallel RNGseed, so results are reproducible even 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 and uses the historical parallel default.
dataDrivenPriorMatricesCv: Optional list, one element per fold, of data-driven prior matrices for the mr.mash learner.
reweightedMixturePriorCv: Optional list, one element per fold, of reweighted mixture priors for the mvSuSiE learner.
fittedModelsCv: Optional per-fold fine-mapping fits, as method -> fold_<j> -> fit, from a fineMappingPipeline() run with cvFolds > 1. SuSiE-family weight wrappers extract from a supplied fit and never fine-map, so this is what makes cross-validating them possible; it must have been produced on samplePartitions, since a fit trained on different folds would leak held-out samples.

Value

A list with the following components:

`samplePartition`: A dataframe showing the sample partitioning used in the cross-validation.
`prediction`: A list of matrices with predicted Y values for each method and fold.
`metrics`: A matrix with rows representing methods and columns for various metrics:
- `corr`: Pearson's correlation between predicated and observed values.
- `adj_rsq`: Adjusted R-squared value (which indicates the proportion of variance explained by the model) that accounts for the number of predictors in the model.
- `pval`: P-value assessing the significance of the model's predictions.
- `RMSE`: Root Mean Squared Error, a measure of the model's prediction error.
- `MAE`: Mean Absolute Error, a measure of the average magnitude of errors in a set of predictions.
`timeElapsed`: The time taken to complete the cross-validation process.

Examples

data(multiTraitData)
X <- multiTraitData$X[, 1:80]
Y <- multiTraitData$Y
# A cross-validated method is refit on each fold's training rows. The
# SuSiE family never fine-maps, so it needs each fold's own fit, passed
# as `fittedModelsCv` from a fineMappingPipeline() run with cvFolds > 1.
twasWeightsCv(X, Y[, 1, drop = FALSE], fold = 3,
  weightMethods = list(lasso_weights = list()))
#>   CV fold 1/3 ...
#>   CV fold 2/3 ...
#>   CV fold 3/3 ...
#> $samplePartition
#> # A tibble: 400 × 2
#>    Sample      Fold
#>    <chr>      <int>
#>  1 sample_029     1
#>  2 sample_096     1
#>  3 sample_167     1
#>  4 sample_190     1
#>  5 sample_299     1
#>  6 sample_189     1
#>  7 sample_068     1
#>  8 sample_027     1
#>  9 sample_380     1
#> 10 sample_287     1
#> # ℹ 390 more rows
#> 
#> $prediction
#> $prediction$lasso_predicted
#>                  cond_1
#> sample_001  0.000000000
#> sample_002  0.000000000
#> sample_003  0.000000000
#> sample_004  0.000000000
#> sample_005  0.000000000
#> sample_006  0.024377705
#> sample_007  0.000000000
#> sample_008  0.000000000
#> sample_009 -0.004557256
#> sample_010  0.000000000
#> sample_011  0.000000000
#> sample_012  0.000000000
#> sample_013  0.000000000
#> sample_014  0.000000000
#> sample_015 -0.004557256
#> sample_016  0.000000000
#> sample_017  0.000000000
#> sample_018 -0.004557256
#> sample_019  0.000000000
#> sample_020  0.000000000
#> sample_021  0.024377705
#> sample_022 -0.004557256
#> sample_023 -0.004557256
#> sample_024 -0.004557256
#> sample_025  0.000000000
#> sample_026  0.024377705
#> sample_027  0.000000000
#> sample_028  0.000000000
#> sample_029  0.000000000
#> sample_030  0.000000000
#> sample_031  0.000000000
#> sample_032  0.000000000
#> sample_033  0.000000000
#> sample_034  0.024377705
#> sample_035  0.000000000
#> sample_036  0.000000000
#> sample_037  0.000000000
#> sample_038  0.000000000
#> sample_039 -0.004557256
#> sample_040 -0.004557256
#> sample_041  0.000000000
#> sample_042  0.000000000
#> sample_043  0.000000000
#> sample_044 -0.004557256
#> sample_045 -0.004557256
#> sample_046  0.000000000
#> sample_047  0.000000000
#> sample_048  0.000000000
#> sample_049  0.000000000
#> sample_050  0.000000000
#> sample_051 -0.004557256
#> sample_052 -0.004557256
#> sample_053  0.000000000
#> sample_054  0.000000000
#> sample_055 -0.004557256
#> sample_056 -0.004557256
#> sample_057  0.024377705
#> sample_058 -0.004557256
#> sample_059  0.024377705
#> sample_060  0.000000000
#> sample_061 -0.004557256
#> sample_062  0.000000000
#> sample_063 -0.004557256
#> sample_064  0.000000000
#> sample_065  0.000000000
#> sample_066 -0.004557256
#> sample_067  0.000000000
#> sample_068  0.000000000
#> sample_069 -0.004557256
#> sample_070  0.000000000
#> sample_071 -0.004557256
#> sample_072 -0.004557256
#> sample_073  0.000000000
#> sample_074  0.000000000
#> sample_075  0.000000000
#> sample_076 -0.004557256
#> sample_077  0.000000000
#> sample_078  0.000000000
#> sample_079  0.000000000
#> sample_080 -0.004557256
#> sample_081  0.000000000
#> sample_082 -0.004557256
#> sample_083  0.000000000
#> sample_084 -0.004557256
#> sample_085 -0.004557256
#> sample_086  0.000000000
#> sample_087 -0.004557256
#> sample_088  0.000000000
#> sample_089  0.000000000
#> sample_090  0.000000000
#> sample_091  0.000000000
#> sample_092  0.000000000
#> sample_093  0.024377705
#> sample_094  0.000000000
#> sample_095  0.000000000
#> sample_096  0.000000000
#> sample_097  0.000000000
#> sample_098  0.000000000
#> sample_099 -0.004557256
#> sample_100  0.000000000
#> sample_101  0.000000000
#> sample_102 -0.004557256
#> sample_103 -0.004557256
#> sample_104  0.000000000
#> sample_105 -0.004557256
#> sample_106  0.000000000
#> sample_107  0.000000000
#> sample_108  0.000000000
#> sample_109  0.000000000
#> sample_110  0.000000000
#> sample_111  0.000000000
#> sample_112 -0.004557256
#> sample_113  0.000000000
#> sample_114 -0.004557256
#> sample_115 -0.004557256
#> sample_116  0.000000000
#> sample_117  0.000000000
#> sample_118  0.000000000
#> sample_119  0.000000000
#> sample_120  0.000000000
#> sample_121  0.000000000
#> sample_122  0.000000000
#> sample_123  0.000000000
#> sample_124  0.000000000
#> sample_125  0.000000000
#> sample_126  0.000000000
#> sample_127  0.000000000
#> sample_128 -0.004557256
#> sample_129  0.000000000
#> sample_130  0.000000000
#> sample_131  0.000000000
#> sample_132  0.000000000
#> sample_133 -0.004557256
#> sample_134 -0.004557256
#> sample_135  0.000000000
#> sample_136  0.000000000
#> sample_137 -0.004557256
#> sample_138  0.000000000
#> sample_139  0.000000000
#> sample_140  0.000000000
#> sample_141 -0.004557256
#> sample_142  0.053312666
#> sample_143 -0.004557256
#> sample_144 -0.004557256
#> sample_145  0.000000000
#> sample_146 -0.004557256
#> sample_147  0.000000000
#> sample_148  0.000000000
#> sample_149  0.000000000
#> sample_150 -0.004557256
#> sample_151 -0.004557256
#> sample_152 -0.004557256
#> sample_153  0.000000000
#> sample_154 -0.004557256
#> sample_155  0.000000000
#> sample_156  0.000000000
#> sample_157  0.000000000
#> sample_158 -0.004557256
#> sample_159 -0.004557256
#> sample_160  0.000000000
#> sample_161 -0.004557256
#> sample_162  0.000000000
#> sample_163  0.000000000
#> sample_164  0.000000000
#> sample_165  0.000000000
#> sample_166  0.000000000
#> sample_167  0.000000000
#> sample_168  0.000000000
#> sample_169  0.000000000
#> sample_170  0.000000000
#> sample_171  0.024377705
#> sample_172  0.000000000
#> sample_173  0.000000000
#> sample_174  0.000000000
#> sample_175  0.000000000
#> sample_176  0.000000000
#> sample_177 -0.004557256
#> sample_178 -0.004557256
#> sample_179 -0.004557256
#> sample_180  0.000000000
#> sample_181  0.000000000
#> sample_182  0.000000000
#> sample_183  0.000000000
#> sample_184  0.000000000
#> sample_185 -0.004557256
#> sample_186  0.000000000
#> sample_187  0.000000000
#> sample_188  0.000000000
#> sample_189  0.000000000
#> sample_190  0.000000000
#> sample_191  0.024377705
#> sample_192  0.000000000
#> sample_193  0.000000000
#> sample_194 -0.004557256
#> sample_195  0.000000000
#> sample_196  0.024377705
#> sample_197  0.000000000
#> sample_198  0.000000000
#> sample_199  0.000000000
#> sample_200  0.000000000
#> sample_201  0.000000000
#> sample_202 -0.004557256
#> sample_203 -0.004557256
#> sample_204  0.000000000
#> sample_205  0.000000000
#> sample_206  0.000000000
#> sample_207  0.000000000
#> sample_208  0.000000000
#> sample_209  0.000000000
#> sample_210 -0.004557256
#> sample_211 -0.004557256
#> sample_212  0.000000000
#> sample_213  0.000000000
#> sample_214 -0.004557256
#> sample_215  0.000000000
#> sample_216  0.000000000
#> sample_217  0.024377705
#> sample_218 -0.004557256
#> sample_219  0.000000000
#> sample_220  0.000000000
#> sample_221  0.000000000
#> sample_222  0.000000000
#> sample_223  0.000000000
#> sample_224 -0.004557256
#> sample_225 -0.004557256
#> sample_226  0.000000000
#> sample_227 -0.004557256
#> sample_228  0.000000000
#> sample_229  0.000000000
#> sample_230 -0.004557256
#> sample_231  0.024377705
#> sample_232 -0.004557256
#> sample_233  0.024377705
#> sample_234  0.000000000
#> sample_235 -0.004557256
#> sample_236  0.000000000
#> sample_237 -0.004557256
#> sample_238 -0.004557256
#> sample_239  0.000000000
#> sample_240 -0.004557256
#> sample_241  0.000000000
#> sample_242  0.000000000
#> sample_243 -0.004557256
#> sample_244 -0.004557256
#> sample_245 -0.004557256
#> sample_246  0.000000000
#> sample_247  0.000000000
#> sample_248  0.000000000
#> sample_249  0.000000000
#> sample_250  0.000000000
#> sample_251  0.000000000
#> sample_252  0.000000000
#> sample_253  0.000000000
#> sample_254  0.000000000
#> sample_255  0.000000000
#> sample_256 -0.004557256
#> sample_257  0.000000000
#> sample_258 -0.004557256
#> sample_259  0.000000000
#> sample_260  0.000000000
#> sample_261 -0.004557256
#> sample_262 -0.004557256
#> sample_263  0.000000000
#> sample_264 -0.004557256
#> sample_265  0.000000000
#> sample_266 -0.004557256
#> sample_267  0.000000000
#> sample_268  0.000000000
#> sample_269 -0.004557256
#> sample_270  0.000000000
#> sample_271 -0.004557256
#> sample_272  0.000000000
#> sample_273  0.000000000
#> sample_274  0.024377705
#> sample_275 -0.004557256
#> sample_276 -0.004557256
#> sample_277  0.000000000
#> sample_278  0.000000000
#> sample_279 -0.004557256
#> sample_280  0.000000000
#> sample_281  0.000000000
#> sample_282 -0.004557256
#> sample_283  0.000000000
#> sample_284 -0.004557256
#> sample_285  0.024377705
#> sample_286  0.000000000
#> sample_287  0.000000000
#> sample_288  0.000000000
#> sample_289 -0.004557256
#> sample_290  0.000000000
#> sample_291  0.000000000
#> sample_292 -0.004557256
#> sample_293  0.000000000
#> sample_294  0.000000000
#> sample_295  0.000000000
#> sample_296  0.024377705
#> sample_297  0.000000000
#> sample_298 -0.004557256
#> sample_299  0.000000000
#> sample_300 -0.004557256
#> sample_301 -0.004557256
#> sample_302 -0.004557256
#> sample_303  0.000000000
#> sample_304 -0.004557256
#> sample_305  0.000000000
#> sample_306  0.000000000
#> sample_307  0.000000000
#> sample_308  0.000000000
#> sample_309  0.000000000
#> sample_310  0.000000000
#> sample_311 -0.004557256
#> sample_312  0.000000000
#> sample_313  0.000000000
#> sample_314  0.000000000
#> sample_315  0.000000000
#> sample_316  0.000000000
#> sample_317  0.000000000
#> sample_318  0.000000000
#> sample_319 -0.004557256
#> sample_320  0.000000000
#> sample_321 -0.004557256
#> sample_322 -0.004557256
#> sample_323  0.000000000
#> sample_324  0.000000000
#> sample_325  0.024377705
#> sample_326  0.000000000
#> sample_327 -0.004557256
#> sample_328  0.000000000
#> sample_329  0.000000000
#> sample_330  0.000000000
#> sample_331  0.000000000
#> sample_332 -0.004557256
#> sample_333  0.000000000
#> sample_334 -0.004557256
#> sample_335 -0.004557256
#> sample_336  0.000000000
#> sample_337  0.000000000
#> sample_338  0.000000000
#> sample_339 -0.004557256
#> sample_340  0.000000000
#> sample_341  0.024377705
#> sample_342 -0.004557256
#> sample_343  0.000000000
#> sample_344  0.000000000
#> sample_345  0.000000000
#> sample_346 -0.004557256
#> sample_347  0.000000000
#> sample_348  0.000000000
#> sample_349  0.000000000
#> sample_350  0.000000000
#> sample_351  0.000000000
#> sample_352  0.000000000
#> sample_353  0.000000000
#> sample_354  0.000000000
#> sample_355  0.000000000
#> sample_356  0.000000000
#> sample_357  0.000000000
#> sample_358  0.000000000
#> sample_359 -0.004557256
#> sample_360  0.000000000
#> sample_361 -0.004557256
#> sample_362 -0.004557256
#> sample_363 -0.004557256
#> sample_364  0.000000000
#> sample_365  0.000000000
#> sample_366  0.000000000
#> sample_367  0.000000000
#> sample_368  0.000000000
#> sample_369  0.000000000
#> sample_370  0.000000000
#> sample_371  0.053312666
#> sample_372  0.000000000
#> sample_373  0.024377705
#> sample_374  0.000000000
#> sample_375 -0.004557256
#> sample_376 -0.004557256
#> sample_377  0.000000000
#> sample_378  0.000000000
#> sample_379  0.000000000
#> sample_380  0.000000000
#> sample_381  0.000000000
#> sample_382  0.000000000
#> sample_383  0.000000000
#> sample_384  0.000000000
#> sample_385  0.000000000
#> sample_386  0.000000000
#> sample_387 -0.004557256
#> sample_388  0.000000000
#> sample_389  0.000000000
#> sample_390  0.000000000
#> sample_391  0.000000000
#> sample_392 -0.004557256
#> sample_393  0.000000000
#> sample_394  0.000000000
#> sample_395  0.053312666
#> sample_396  0.000000000
#> sample_397  0.000000000
#> sample_398  0.000000000
#> sample_399  0.000000000
#> sample_400  0.000000000
#> 
#> 
#> $performance
#> $performance$lasso_performance
#>               corr          rsq      adj_rsq      pval      RMSE       MAE
#> cond_1 -0.03021434 0.0009129062 -0.001597363 0.5468193 0.3881759 0.3094012
#> 
#> 
#> $foldFits
#> $foldFits$fold_1
#> list()
#> 
#> $foldFits$fold_2
#> list()
#> 
#> $foldFits$fold_3
#> list()
#> 
#> 
#> $timeElapsed
#>    user  system elapsed 
#>   1.786   0.003   1.788 
#>