| train | R Documentation |
Fit Predictive Models over Different Tuning Parameters
Description
This function sets up a grid of tuning parameters for a numberof classification and regression routines, fits each model andcalculates a resampling based performance measure.
Usage
train(x, ...)## Default S3 method:train( x, y, method = "rf", preProcess = NULL, ..., weights = NULL, metric = ifelse(is.factor(y), "Accuracy", "RMSE"), maximize = ifelse(metric %in% c("RMSE", "logLoss", "MAE", "logLoss"), FALSE, TRUE), trControl = trainControl(), tuneGrid = NULL, tuneLength = ifelse(trControl$method == "none", 1, 3))## S3 method for class 'formula'train(form, data, ..., weights, subset, na.action = na.fail, contrasts = NULL)## S3 method for class 'recipe'train( x, data, method = "rf", ..., metric = ifelse(is.factor(y_dat), "Accuracy", "RMSE"), maximize = ifelse(metric %in% c("RMSE", "logLoss", "MAE"), FALSE, TRUE), trControl = trainControl(), tuneGrid = NULL, tuneLength = ifelse(trControl$method == "none", 1, 3))Arguments
x | For the default method, |
... | Arguments passed to the classification orregression routine (such as |
y | A numeric or factor vector containing the outcome foreach sample. |
method | A string specifying which classification orregression model to use. Possible values are found using |
preProcess | A string vector that defines a pre-processingof the predictor data. Current possibilities are "BoxCox","YeoJohnson", "expoTrans", "center", "scale", "range","knnImpute", "bagImpute", "medianImpute", "pca", "ica" and"spatialSign". The default is no pre-processing. See |
weights | A numeric vector of case weights. This argumentwill only affect models that allow case weights. |
metric | A string that specifies what summary metric willbe used to select the optimal model. By default, possible valuesare "RMSE" and "Rsquared" for regression and "Accuracy" and"Kappa" for classification. If custom performance metrics areused (via the |
maximize | A logical: should the metric be maximized orminimized? |
trControl | A list of values that define how this functionacts. See |
tuneGrid | A data frame with possible tuning values. Thecolumns are named the same as the tuning parameters. Use |
tuneLength | An integer denoting the amount of granularityin the tuning parameter grid. By default, this argument is thenumber of levels for each tuning parameters that should begenerated by |
form | A formula of the form |
data | Data frame from which variables specified in |
subset | An index vector specifying the cases to be usedin the training sample. (NOTE: If given, this argument must benamed.) |
na.action | A function to specify the action to be takenif NAs are found. The default action is for the procedure tofail. An alternative is |
contrasts | A list of contrasts to be used for some or allthe factors appearing as variables in the model formula. |
Details
train can be used to tune models by picking thecomplexity parameters that are associated with the optimalresampling statistics. For particular model, a grid ofparameters (if any) is created and the model is trained onslightly different data for each candidate combination of tuningparameters. Across each data set, the performance of held-outsamples is calculated and the mean and standard deviation issummarized for each combination. The combination with theoptimal resampling statistic is chosen as the final model andthe entire training set is used to fit a final model.
The predictors in x can be most any object as long asthe underlying model fit function can deal with the objectclass. The function was designed to work with simple matricesand data frame inputs, so some functionality may not work (e.g.pre-processing). When using string kernels, the vector ofcharacter strings should be converted to a matrix with a singlecolumn.
More details on this function can be found athttp://topepo.github.io/caret/model-training-and-tuning.html.
A variety of models are currently available and are enumeratedby tag (i.e. their model characteristics) athttp://topepo.github.io/caret/train-models-by-tag.html.
More details on using recipes can be found athttp://topepo.github.io/caret/using-recipes-with-train.html.Note that case weights can be passed into train using arole of "case weight" for a single variable. Also, ifthere are non-predictor columns that should be used whendetermining the model's performance metrics, the role of"performance var" can be used with multiple columns andthese will be made available during resampling to thesummaryFunction function.
Value
A list is returned of class train containing:
method | The chosen model. |
modelType | Anidentifier of the model type. |
results | A data frame thetraining error rate and values of the tuning parameters. |
bestTune | A data frame with the final parameters. |
call | The (matched) function call with dots expanded |
dots | A list containing any ... values passed to theoriginal call |
metric | A string that specifies whatsummary metric will be used to select the optimal model. |
control | The list of control parameters. |
preProcess | Either |
finalModel | A fit object usingthe best parameters |
trainingData | A data frame |
resample | A data frame with columns for each performancemetric. Each row corresponds to each resample. If leave-one-outcross-validation or out-of-bag estimation methods are requested,this will be |
perfNames | A character vector ofperformance metrics that are produced by the summary function |
maximize | A logical recycled from the function arguments. |
yLimits | The range of the training set outcomes. |
times | A list of execution times: |
Author(s)
Max Kuhn (the guts of train.formula were basedon Ripley's nnet.formula)
References
http://topepo.github.io/caret/
Kuhn (2008), “Building Predictive Models in R Using the caret”(\Sexpr[results=rd]{tools:::Rd_expr_doi("10.18637/jss.v028.i05")})
https://topepo.github.io/recipes/
See Also
models, trainControl,update.train, modelLookup,createFolds, recipe
Examples
## Not run: ######################################### Classification Exampledata(iris)TrainData <- iris[,1:4]TrainClasses <- iris[,5]knnFit1 <- train(TrainData, TrainClasses, method = "knn", preProcess = c("center", "scale"), tuneLength = 10, trControl = trainControl(method = "cv"))knnFit2 <- train(TrainData, TrainClasses, method = "knn", preProcess = c("center", "scale"), tuneLength = 10, trControl = trainControl(method = "boot"))library(MASS)nnetFit <- train(TrainData, TrainClasses, method = "nnet", preProcess = "range", tuneLength = 2, trace = FALSE, maxit = 100)######################################### Regression Examplelibrary(mlbench)data(BostonHousing)lmFit <- train(medv ~ . + rm:lstat, data = BostonHousing, method = "lm")library(rpart)rpartFit <- train(medv ~ ., data = BostonHousing, method = "rpart", tuneLength = 9)######################################### Example with a custom metricmadSummary <- function (data, lev = NULL, model = NULL) { out <- mad(data$obs - data$pred, na.rm = TRUE) names(out) <- "MAD" out}robustControl <- trainControl(summaryFunction = madSummary)marsGrid <- expand.grid(degree = 1, nprune = (1:10) * 2)earthFit <- train(medv ~ ., data = BostonHousing, method = "earth", tuneGrid = marsGrid, metric = "MAD", maximize = FALSE, trControl = robustControl)######################################### Example with a recipedata(cox2)cox2 <- cox2Descrcox2$potency <- cox2IC50library(recipes)cox2_recipe <- recipe(potency ~ ., data = cox2) %>% ## Log the outcome step_log(potency, base = 10) %>% ## Remove sparse and unbalanced predictors step_nzv(all_predictors()) %>% ## Surface area predictors are highly correlated so ## conduct PCA just on these. step_pca(contains("VSA"), prefix = "surf_area_", threshold = .95) %>% ## Remove other highly correlated predictors step_corr(all_predictors(), -starts_with("surf_area_"), threshold = .90) %>% ## Center and scale all of the non-PCA predictors step_center(all_predictors(), -starts_with("surf_area_")) %>% step_scale(all_predictors(), -starts_with("surf_area_"))set.seed(888)cox2_lm <- train(cox2_recipe, data = cox2, method = "lm", trControl = trainControl(method = "cv"))######################################### Parallel Processing Example via multicore package## library(doMC)## registerDoMC(2)## NOTE: don't run models form RWeka when using### multicore. The session will crash.## The code for train() does not change:set.seed(1)usingMC <- train(medv ~ ., data = BostonHousing, method = "glmboost")## or use:## library(doMPI) or## library(doParallel) or## library(doSMP) and so on## End(Not run)