tune.block.splsda {mixOmics} | R Documentation

## 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,
    scheme= "horst",
    scale = TRUE,
    init = "svd",
    light.output = TRUE,
    signif.threshold=0.01,
    cpus = 1,
    name.save=NULL
    )

### Arguments

`X` | numeric matrix of predictors. `NA`s are allowed.
`Y` | `if(method = 'spls')` numeric vector or matrix of continuous responses (for multi-response models) `NA`s are allowed.
`indY` | To be supplied if Y is missing, indicates the position of the matrix / vector response in the list `X`
`ncomp` | the number of components to include in the model.
`test.keepX` | A list of length the number of blocks in X (without the outcome). 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 numeric vector indicating the number of variables to select from the X data set on the firsts 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 use for `splsda` to estimate the classification error rate, should be a subset of `"centroids.dist"`, `"mahalanobis.dist"` or `"max.dist"` (see Details).
`measure` | Two misclassification measure are available: overall misclassification error `overall` or the Balanced Error Rate `BER`
`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` | Convergence stopping value.
`max.iter` | integer, the maximum number of iterations.
`near.zero.var` | boolean, see the internal `nearZeroVar` function (should be set to TRUE in particular for data with many zero values). 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 0 or 1 values. A value of 1 (0) indicates a relationship (no relationship) between the blocks to be modelled. If `Y` is provided instead of `indY`, the `design` matrix is changed to include relationships to `Y`.
`scheme` | Either "horst", "factorial" or "centroid". Default = `centroid`, see reference.
`scale` | boleean. If scale = TRUE, each block is standardized to zero means and unit variances. Default = `TRUE`.
`init` | Mode of initialization use in the algorithm, either by Singular Value Decompostion of the product of each block of X with Y ("svd") or each block independently ("svd.single"). Default = `svd`.
`signif.threshold` | numeric between 0 and 1 indicating the significance threshold required for improvement in error rate of the components. Default to 0.01.
`light.output` | if set to FALSE, the prediction/classification of each sample for each of `test.keepX` and each comp is returned.
`cpus` | Integer, number of cpus to use. If greater than 1, the code will run in parallel when repeating the cross-validatio, 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`.
`name.save` | character string for the name of the file to be saved.

### 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.

### 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

    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 = 5

    # 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 = seq(10,40,20), mirna = seq(10,30,10), protein = seq(1,10,5))

    # the following may take some time to run, note that for through tuning
    # nrepeat should be > 1
    tune = tune.block.splsda(X = data, Y = breast.TCGA$data.train$subtype,
    ncomp = ncomp, test.keepX = test.keepX, design = design, nrepeat = 3)

    tune$choice.ncomp
    tune$choice.keepX

    # Only tuning the second component
    # -------------

    already.mrna = 4 # 4 variables selected on comp1 for mrna
    already.mirna  = 2 # 2 variables selected on comp1 for mirna
    already.prot  = 1 # 1 variables selected on comp1 for protein

    already.tested.X = list(mrna = already.mrna, mirna = already.mirna, protein = already.prot)

    tune = tune.block.splsda(X = data, Y = breast.TCGA$data.train$subtype,
    ncomp = 2, test.keepX = test.keepX, design = design,
    already.tested.X = already.tested.X)

    tune$choice.keepX

    ## End(Not run)

[Package mixOmics version 6.11.11 Index]