tune.block.splsda: Tuning function for block.splsda method (N-integration with...

In mixOmicsTeam/mixOmics: Omics Data Integration Project

Tuning function for block.splsda method (N-integration with sparse Discriminant Analysis)

Description

Computes M-fold or Leave-One-Out Cross-Validation scores based on a user-input grid to determine the optimal parsity parameters values for method block.splsda.

Usage

tune.block.splsda(
  X,
  Y,
  indY,
  ncomp = 2,
  test.keepX,
  already.tested.X,
  validation = "Mfold",
  folds = 10,
  dist = "max.dist",
  measure = "BER",
  weighted = TRUE,
  progressBar = FALSE,
  tol = 1e-06,
  max.iter = 100,
  near.zero.var = FALSE,
  nrepeat = 1,
  design,
  scale = TRUE,
  light.output = TRUE,
  signif.threshold = 0.01,
  BPPARAM = SerialParam(),
  seed = NULL,
  ...
)

Arguments

X	A named list of data sets (called 'blocks') measured on the same samples. Data in the list should be arranged in matrices, samples x variables, with samples order matching in all data sets.
Y	a factor or a class vector for the discrete outcome.
indY	To supply if Y is missing, indicates the position of the matrix response in the list X.
ncomp	the number of components to include in the model. Default to 2. Applies to all blocks.
test.keepX	A named list with the same length and names as X (without the outcome Y, if it is provided in X and designated using indY). Each entry of this list is a numeric vector for the different keepX values to test for that specific block.
already.tested.X	Optional, if ncomp > 1 A named list of numeric vectors each of length n_tested indicating the number of variables to select from the X data set on the first n_tested components.
validation	character. What kind of (internal) validation to use, matching one of "Mfold" or "loo" (see below). Default is "Mfold".
folds	the folds in the Mfold cross-validation. See Details.
dist	distance metric to estimate the classification error rate, should be a subset of "centroids.dist", "mahalanobis.dist" or "max.dist" (see Details).
measure	The tuning measure used for different methods. See details.
weighted	tune using either the performance of the Majority vote or the Weighted vote.
progressBar	by default set to TRUE to output the progress bar of the computation.
tol	Positive numeric used as convergence criteria/tolerance during the iterative process. Default to 1e-06.
max.iter	Integer, the maximum number of iterations. Default to 100.
near.zero.var	Logical, see the internal nearZeroVar function (should be set to TRUE in particular for data with many zero values). Setting this argument to FALSE (when appropriate) will speed up the computations. Default value is FALSE.
nrepeat	Number of times the Cross-Validation process is repeated.
design	numeric matrix of size (number of blocks in X) x (number of blocks in X) with values between 0 and 1. Each value indicates the strenght of the relationship to be modelled between two blocks; a value of 0 indicates no relationship, 1 is the maximum value. Alternatively, one of c('null', 'full') indicating a disconnected or fully connected design, respecively, or a numeric between 0 and 1 which will designate all off-diagonal elements of a fully connected design (see examples in block.splsda). If Y is provided instead of indY, the design matrix is changed to include relationships to Y.
scale	Logical. If scale = TRUE, each block is standardized to zero means and unit variances (default: TRUE)
light.output	if set to FALSE, the prediction/classification of each sample for each of test.keepX and each comp is returned.
signif.threshold	numeric between 0 and 1 indicating the significance threshold required for improvement in error rate of the components. Default to 0.01.
BPPARAM	A BiocParallelParam object indicating the type of parallelisation. See examples.
seed	set a number here if you want the function to give reproducible outputs. Not recommended during exploratory analysis. Note if RNGseed is set in 'BPPARAM', this will be overwritten by 'seed'.
...	Optional arguments: seed Integer. Seed number for reproducible parallel code. Default is NULL. run in parallel when repeating the cross-validation, which is usually the most computationally intensive process. If there is excess CPU, the cross-vaidation is also parallelised on *nix-based OS which support mclapply. Note that the argument 'scheme' has now been hardcoded to 'horst' and 'init' to 'svd.single'.

Details

This tuning function should be used to tune the keepX parameters in the block.splsda function (N-integration with sparse Discriminant Analysis).

M-fold or LOO cross-validation is performed with stratified subsampling where all classes are represented in each fold.

If validation = "Mfold", M-fold cross-validation is performed. The number of folds to generate is to be specified in the argument folds.

If validation = "loo", leave-one-out cross-validation is performed. By default folds is set to the number of unique individuals.

All combination of test.keepX values are tested. A message informs how many will be fitted on each component for a given test.keepX.

More details about the prediction distances in ?predict and the supplemental material of the mixOmics article (Rohart et al. 2017). Details about the PLS modes are in ?pls.

BER is appropriate in case of an unbalanced number of samples per class as it calculates the average proportion of wrongly classified samples in each class, weighted by the number of samples in each class. BER is less biased towards majority classes during the performance assessment.

Value

A list that contains:

error.rate	returns the prediction error for each test.keepX on each component, averaged across all repeats and subsampling folds. Standard deviation is also output. All error rates are also available as a list.
choice.keepX	returns the number of variables selected (optimal keepX) on each component, for each block.
choice.ncomp	returns the optimal number of components for the model fitted with $choice.keepX.
error.rate.class	returns the error rate for each level of Y and for each component computed with the optimal keepX
predict	Prediction values for each sample, each test.keepX, each comp and each repeat. Only if light.output=FALSE
class	Predicted class for each sample, each test.keepX, each comp and each repeat. Only if light.output=FALSE
cor.value	compute the correlation between latent variables for two-factor sPLS-DA analysis.

Author(s)

Florian Rohart, Amrit Singh, Kim-Anh Lê Cao, AL J Abadi

References

Method:

Singh A., Gautier B., Shannon C., Vacher M., Rohart F., Tebbutt S. and Lê Cao K.A. (2016). DIABLO: multi omics integration for biomarker discovery.

mixOmics article:

Rohart F, Gautier B, Singh A, Lê Cao K-A. mixOmics: an R package for 'omics feature selection and multiple data integration. PLoS Comput Biol 13(11): e1005752

See Also

block.splsda and http://www.mixOmics.org for more details.

Examples

## Not run: 
data("breast.TCGA")
# this is the X data as a list of mRNA and miRNA; the Y data set is a single data set of proteins
data = list(mrna = breast.TCGA$data.train$mrna, mirna = breast.TCGA$data.train$mirna,
            protein = breast.TCGA$data.train$protein)
# set up a full design where every block is connected
# could also consider other weights, see our mixOmics manuscript
design = matrix(1, ncol = length(data), nrow = length(data),
                dimnames = list(names(data), names(data)))
diag(design) =  0
design
# set number of component per data set
ncomp = 3

# Tuning the first two components
# -------------
## Not run: 
# definition of the keepX value to be tested for each block mRNA miRNA and protein
# names of test.keepX must match the names of 'data'
test.keepX = list(mrna = c(10, 30), mirna = c(15, 25), protein = c(4, 8))

# the following may take some time to run, so we subset the data first.
# Note that for thorough tuning, nrepeat should be >= 3 so that significance of 
# the model improvement can be measured
## ---- subset by 3rd of samples
set.seed(100)
subset <- mixOmics:::stratified.subsampling(breast.TCGA$data.train$subtype, folds = 3)[[1]][[1]]
data <- lapply(data, function(omic) omic[subset,])
Y <- breast.TCGA$data.train$subtype[subset]
## ---- run
# Check if the environment variable exists (during R CMD check) and limit cores accordingly
max_cores <- if (Sys.getenv("_R_CHECK_LIMIT_CORES_") != "") 2 else parallel::detectCores() - 1
# Setup the parallel backend with the appropriate number of workers
BPPARAM <- BiocParallel::MulticoreParam(workers = max_cores)

tune <- tune.block.splsda(
    X = data,
    Y = Y,
    ncomp = ncomp,
    test.keepX = test.keepX,
    design = design,
    nrepeat = 2, 
    BPPARAM = BPPARAM
)

plot(tune)
tune$choice.ncomp
tune$choice.keepX

# Now tuning a new component given previous tuned keepX
already.tested.X = tune$choice.keepX
tune = tune.block.splsda(X = data, Y = Y,
                         ncomp = 4, test.keepX = test.keepX, design = design,
                         already.tested.X = already.tested.X,
                         BPPARAM = BPPARAM
                         )
tune$choice.keepX

## End(Not run)

mixOmicsTeam/mixOmics documentation built on Nov. 19, 2024, 11:53 a.m.