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,
  retainFits = FALSE,
  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.
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.
retainFits: Logical. Retain the per-fold / per-method fitted-model objects on the result. Default FALSE.
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.
...: Additional arguments forwarded to the per-method weight learners.

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