cvApply-methods {Cardinal} | R Documentation

## Apply cross-validation to imaging analyses

### Description

Apply cross-validation with an existing or a user-specified modeling function over an imaging datasets.

### Usage

    ## S4 method for signature 'MSImagingExperiment'
    crossValidate(.x, .y, .fun,
            .fold = run(.x),
            .predict = predict,
            .process = FALSE,
            .processControl = list(),
            .peaks = NULL,
            BPPARAM = getCardinalBPPARAM(), ...)

    ## S4 method for signature 'SparseImagingExperiment'
    crossValidate(.x, .y, .fun, .fold = run(.x),
            BPPARAM = getCardinalBPPARAM(), ...)

    ## S4 method for signature 'SparseImagingExperiment'
    cvApply(.x, .y, .fun,
            .fold = run(.x),
            .predict = predict,
            .fitted = fitted,
            .simplify = FALSE,
            BPREDO = list(),
            BPPARAM = getCardinalBPPARAM(), ...)

    ## S4 method for signature 'CrossValidated2'
    summary(object, ...)

    ## S4 method for signature 'SImageSet'
    cvApply(.x, .y, .fun, .fold = sample, ...)

### Arguments

`.x` | An imaging dataset.
`.y` | The response variable for prediction.
`.fun` | A function for training a model where the first two arguments are the dataset and the response.
`.fold` | A variable determining the cross-validation folds. When specifying custom folds, it is important to make sure that data points from the same experimental run are not split among different folds. I.e., all data points from a run should belong to the same CV fold.
`.predict` | A function for predicting from a trained model. The first two arguments are the model and a new dataset.
`.fitted` | A function for extracting the predicted values from the result of a call to `.predict`.
`.simplify` | If FALSE (the default), the output of `.predict` is returned. If TRUE, then `.fitted` is applied to the results to extract fitted values. Only the fitted values, observed values, and basic model information is returned.
`.process` | Should pre-processing be applied before each training and test step? This includes peak alignment and peak filtering. Peak binning is also performed if `.peaks` is given.
`.processControl` | A list of arguments to be passed to the pre-processing steps.
`.peaks` | A peak-picked version of the full dataset `.x`, for use with pre-processing between training and test steps.
`BPREDO` | See documentation for `bplapply`.
`BPPARAM` | An optional instance of `BiocParallelParam`. See documentation for `bplapply`.
`...` | Additional arguments passed to `.fun`.
`object` | A fitted model object to summarize.

### Details

This method is designed to be used with the provided classification methods, but can also be used with user-provided functions and methods as long as they fulfill certain expectations.

The function or method passed to '.fun' must take at least two arguments: the first argument must be a object derived from `SparseImagingExperiment` or `SImageSet`, and the second argument must be the response variable. The function should return an object of a class derived from `ImagingResult` or `ResultSet`, which should have a `predict` method that takes arguments 'newx' and 'newy' in addition to the fitted model.

For `MSImagingExperiment` objects, pre-processing can be performed. This is particularly useful if there is no reference to which to align peaks, except the mean spectrum (which is calculated from the whole dataset, and may invalidate cross-validation results).

If `.process=TRUE` and `.peaks=NULL`, then either the data should be profile spectra with no peak picking, or it should be a peak-picked dataset before peak alignment. If the data has no peak picking, then the pre-processing will consist of peak picking on the mean spectrum of the training sets, followed by peak alignment and peak filtering. If the data has been peak-picked but not aligned, then the pre-processing will consist of peak alignment to the mean spectrum of the training sets, and peak filtering.

If `.process=TRUE` and `.peaks` is given, then the data should be a dataset consisting of profile spectra, and `.peaks` should be a peak-picked version of the same dataset before peak alignment. The pre-processing will consist of peak alignment to the mean spectrum of the training sets, peak filtering, and peak binning the full data to the aligned peaks.

The `crossValidate` function calls `cvApply` internally and then post-processes the result to be more easily-interpretable and space-efficient. Accuracy metrics are reported for each set of modeling parameters.

### Value

An object of class 'CrossValidated', which is derived from `ResultSet`, or an object of class 'CrossValidated2', which is derived from `ImagingResult`.

### Author(s)

Kylie A. Bemis

### See Also

`spatialShrunkenCentroids`, `PLS`, `OPLS`

[Package Cardinal version 2.8.0 Index]