\name{train}
\alias{train}
\alias{train.default}
\alias{train.formula}
\title{Fit Predictive Models over Different Tuning Parameters}
\description{
  This function sets up a grid of tuning parameters for a number of classification and regression routines,
  fits each model and calculates a resampling based performance measure. 
}
\usage{
train(x, ...)

\method{train}{default}(x, y, 
      method = "rf",  
      ..., 
      weights = NULL,
      metric = ifelse(is.factor(y), "Accuracy", "RMSE"),   
      maximize = ifelse(metric == "RMSE", FALSE, TRUE),
      trControl = trainControl(), 
      tuneGrid = NULL, 
      tuneLength = 3)

\method{train}{formula}(form, data, ..., weights, subset, na.action, contrasts = NULL)
}
\arguments{
  \item{x}{a data frame containing training data where samples are in rows and features are in columns.}
  \item{y}{a numeric or factor vector containing the outcome for each sample.}
\item{form}{A formula of the form \code{y ~ x1 + x2 + ...}}
\item{data}{Data frame from which variables specified in \code{formula} are preferentially to be taken.}
  \item{weights}{a numeric vector of case weights. This argument will only affect models that allow case weights.}
\item{subset}{An index vector specifying the cases to be used in the training sample. (NOTE: If given, this argument must be named.)}
\item{na.action}{A function to specify the action to be taken if NAs are found. The default action is for the procedure to fail. An alternative is na.omit, which leads to rejection of cases with missing values on any required variable. (NOTE: If given, this argument must be named.)}
\item{contrasts}{a list of contrasts to be used for some or all of the factors appearing as variables in the model formula.}
  \item{method}{a string specifying which classification or regression model to use. Possible values are: \code{ada}, \code{bagEarth}, \code{bagFDA}, \code{blackboost}, \code{cforest}, \code{ctree}, \code{ctree2}, \code{earth}, \code{enet}, \code{fda}, \code{gamboost}, \code{gaussprPoly}, \code{gaussprRadial}, \code{gaussprLinear}, \code{gbm}, \code{glm}, \code{glmboost}, \code{glmnet}, \code{gpls}, \code{J48}, \code{JRip}, \code{knn}, \code{lars}, \code{lasso}, \code{lda}, \code{lm}, \code{lmStepAIC}, \code{LMT}, \code{logitBoost}, \code{lssvmPoly}, \code{lssvmRadial}, \code{lvq}, \code{M5Rules}, \code{mda}, \code{multinom}, \code{nb}, \code{nnet}, \code{OneR}, \code{pam}, \code{pcaNNet}, \code{pcr}, \code{pda}, \code{pda2}, \code{penalized}, \code{pls}, \code{ppr}, \code{qda}, \code{rda}, \code{rf}, \code{rlm}, \code{rpart}, \code{rvmLinear}, \code{rvmPoly}, \code{rvmRadial}, \code{sda}, \code{sddaLDA}, \code{sddaQDA}, \code{slda}, \code{smda}, \code{sparseLDA}, \code{spls}, \code{superpc}, \code{svmPoly}, \code{svmRadial}, \code{svmLinear}, \code{treebag} and  \code{vbmpRadial}. See the Details section below.}  
  \item{\ldots}{ arguments passed to the classification or regression routine (such as \code{\link[randomForest]{randomForest}}). Errors will occur if values
         for tuning parameters are passed here.}  
  \item{metric}{a string that specifies what summary metric will be used to select the optimal model. By default, possible values are "RMSE" and "Rsquared" for regression and "Accuracy" and "Kappa" for classification. If custom performance metrics are used (via the \code{summaryFunction} argument in \code{\link{trainControl}}, the value of \code{metric} should match one of the arguments. If it does not, a warning is issued and the first metric given by the \code{summaryFunction} is used. (NOTE: If given, this argument must be named.)}         
  \item{maximize}{a logical: should the metric be maximized or minimized?}
  \item{trControl}{a list of values that define how this function acts. See \code{\link{trainControl}}. (NOTE: If given, this argument must be named.)}
  \item{tuneGrid}{a data frame with possible tuning values. The columns are named the same as the tuning parameters in each
         method preceded by a period (e.g. .decay, .lambda). See the function \code{\link{createGrid}} in this package for more details. 
         (NOTE: If given, this argument must be named.)}  
  \item{tuneLength}{an integer denoting the number of levels for each tuning parameters that should be
         generated by \code{\link{createGrid}}. (NOTE: If given, this argument must be named.)}
}
\details{
\code{train} can be used to tune models by picking the complexity parameters that are associated with the optimal resampling statistics. For particular model, a grid of parameters (if any) is created and the model is trained on slightly different data for each candidate combination of tuning parameters. Across each data set, the performance of held-out samples is calculated and the mean and standard deviation is summarized for each combination. The combination with the optimal resampling statistic is chosen as the final model and the entire training set is used to fit a final model.

A variety of models are currently available. The table below enumerates the models and the values of the \code{method} argument, as well as the complexity parameters used by \code{train}.

  
\tabular{lccc}{
\bold{Model} \tab \bold{\code{method} Value} \tab \bold{Package} \tab \bold{Tuning Parameter(s)} \cr
Generalized linear model \tab \code{glm} \tab \pkg{stats} \tab none \cr
Recursive partitioning \tab \code{rpart} \tab \pkg{rpart} \tab \code{maxdepth} \cr  
\tab \code{ctree} \tab \pkg{party} \tab \code{mincriterion} \cr   
\tab \code{ctree2} \tab \pkg{party} \tab \code{maxdepth} \cr
Boosted trees \tab \code{gbm} \tab \pkg{gbm} \tab \code{interaction depth}, \cr
\tab \tab \tab \code{n.trees}, \code{shrinkage}  \cr
\tab \code{blackboost} \tab \pkg{mboost} \tab \code{maxdepth}, \code{mstop}\cr
\tab \code{ada} \tab \pkg{ada} \tab \code{maxdepth}, \code{iter}, \code{nu}\cr            
Boosted regression models \tab \code{glmboost} \tab \pkg{mboost} \tab \code{mstop}\cr   
\tab \code{gamboost} \tab \pkg{mboost} \tab  \code{mstop}\cr    
\tab \code{logitBoost} \tab \pkg{caTools} \tab  \code{nIter}\cr    
Random forests \tab  \code{rf} \tab \pkg{randomForest} \tab \code{mtry} \cr
\tab \code{cforest} \tab \pkg{party} \tab \code{mtry} \cr   
Bagged trees \tab \code{treebag} \tab \pkg{ipred} \tab None \cr 
Elastic net (glm) \tab  \code{glmnet} \tab \pkg{glmnet} \tab \code{alpha}, \code{lambda} \cr
Neural networks \tab  \code{nnet} \tab \pkg{nnet} \tab \code{decay}, \code{size} \cr
\tab \code{pcaNNet} \tab  \pkg{caret} \tab \code{decay}, \code{size} \cr
Projection pursuit regression \tab \code{ppr} \tab \pkg{stats} \tab \code{nterms} \cr
Principal component regression \tab \code{pcr} \tab \pkg{pls} \tab \code{ncomp} \cr
Partial least squares \tab \code{pls} \tab \pkg{pls}, \pkg{caret} \tab \code{ncomp} \cr
Sparse partial least squares \tab \code{spls} \tab \pkg{spls}, \pkg{caret} \tab \code{K}, \code{eta}, \code{kappa} \cr
Support vector machines  \tab \code{svmLinear} \tab \pkg{kernlab} \tab \code{C}\cr 
  \tab \code{svmRadial} \tab \pkg{kernlab} \tab \code{sigma}, \code{C}\cr 
  \tab \code{svmPoly} \tab \pkg{kernlab} \tab \code{scale}, \code{degree}, \code{C}\cr 
Relevance vector machines \tab \code{rvmLinear} \tab \pkg{kernlab} \tab none\cr 
  \tab \code{rvmRadial} \tab \pkg{kernlab} \tab \code{sigma}\cr 
  \tab \code{rvmPoly} \tab \pkg{kernlab} \tab \code{scale}, \code{degree}\cr 
Least squares support vector machines   \tab \code{lssvmRadial} \tab \pkg{kernlab} \tab \code{sigma}\cr 
Gaussian processes  \tab \code{guassprLinearl} \tab \pkg{kernlab} \tab none\cr 
  \tab \code{guassprRadial} \tab \pkg{kernlab} \tab \code{sigma}\cr 
  \tab \code{guassprPoly} \tab \pkg{kernlab} \tab \code{scale}, \code{degree}\cr 
Linear least squares \tab \code{lm} \tab \pkg{stats} \tab None \cr 
Robust linear regression \tab \code{rlm} \tab \pkg{MASS} \tab None \cr 
Multivariate adaptive regression splines \tab \code{earth} \tab \pkg{earth} \tab \code{degree}, \code{nprune} \cr
Bagged MARS \tab \code{bagEarth} \tab \pkg{caret},  \pkg{earth}\tab \code{degree}, \code{nprune} \cr 
Rule Based Regression \tab \code{M5Rules} \tab \pkg{RWeka} \tab \code{pruned} \cr 
Elastic net \tab \code{enet} \tab \pkg{elasticnet} \tab \code{lambda}, \code{fraction} \cr
Least Angle Regression \tab \code{lars} \tab \pkg{lars} \tab \code{fraction} \cr
                       \tab \code{lars2} \tab \pkg{lars} \tab \code{steps} \cr
The Lasso \tab \code{enet} \tab \pkg{elasticnet} \tab \code{fraction} \cr
Penalized linear models \tab \code{penalized} \tab \pkg{penalized} \tab \code{lambda1}, \code{lambda2}\cr
Supervised principal components \tab \code{superpc} \tab \pkg{superpc} \tab \code{n.components}, \code{threshold} \cr 
Linear discriminant analysis \tab \code{lda} \tab \pkg{MASS} \tab  None\cr 
Quadratic discriminant analysis \tab \code{qda} \tab \pkg{MASS} \tab  None\cr 
Stabilized linear discriminant analysis \tab \code{slda} \tab \pkg{ipred} \tab  None\cr 
Stepwise diagonal discriminant analysis \tab \code{sddaLDA} \tab \pkg{SDDA} \tab None \cr
 \tab \code{sddaQDA} \tab \pkg{SDDA} \tab None \cr
Shrinkage discriminant analysis \tab \code{sda} \tab \pkg{sda} \tab \code{diagonal} \cr
Sparse linear discriminant analysis \tab \code{sparseLDA} \tab \pkg{sparseLDA} \tab \code{NumVars}, \code{lambda} \cr
Regularized discriminant analysis \tab \code{rda} \tab \pkg{klaR} \tab \code{lambda}, \code{gamma} \cr
Mixture discriminant analysis \tab \code{mda} \tab \pkg{mda} \tab \code{subclasses} \cr
Sparse mixture discriminant analysis \tab \code{smda} \tab \pkg{sparseLDA} \tab \code{NumVars}, \code{R}, \code{lambda} \cr
Penalized discriminant analysis \tab \code{pda} \tab \pkg{mda} \tab \code{lambda}\cr
\tab \code{pda2} \tab \pkg{mda} \tab \code{df}\cr
Stabilised linear discriminant analysis \tab \code{slda} \tab \pkg{ipred} \tab None\cr
Flexible discriminant analysis (MARS) \tab \code{fda} \tab \pkg{mda}, \pkg{earth} \tab \code{degree}, \code{nprune} \cr
Bagged FDA \tab \code{bagFDA} \tab \pkg{caret},  \pkg{earth} \tab \code{degree}, \code{nprune} \cr  
Logistic/multinomial regression \tab \code{multinom} \tab \pkg{nnet} \tab \code{decay}\cr 
Rule--based classification \tab \code{J48} \tab \pkg{RWeka} \tab \code{C}\cr 
 \tab \code{OneR} \tab \pkg{RWeka} \tab None\cr
 \tab \code{PART} \tab \pkg{RWeka} \tab \code{threshold}, \code{pruned}\cr
 \tab \code{JRip} \tab \pkg{RWeka} \tab \code{NumOpt}\cr
Bayesian multinomial probit model \tab \code{vbmpRadial} \tab \pkg{vbmp} \tab \code{estimateTheta} \cr
k nearest neighbors \tab \code{knn3} \tab \pkg{caret} \tab \code{k} \cr 
Nearest shrunken centroids \tab \code{pam} \tab \pkg{pamr} \tab \code{threshold} \cr  
Naive Bayes \tab \code{nb} \tab \pkg{klaR} \tab \code{usekernel} \cr
Generalized partial least squares\tab \code{gpls} \tab \pkg{gpls} \tab \code{K.prov} \cr
Learned vector quantization \tab \code{lvq} \tab \pkg{class} \tab  \code{k} 
}


By default, the function \code{\link{createGrid}} is used to define the candidate values of the tuning parameters. The user can also specify their own. To do this, a data fame is created with columns for each tuning parameter in the model. The column names must be the same as those listed in the table above with a leading dot. For example, \code{ncomp} would have the column heading \code{.ncomp}. This data frame can then be passed to \code{\link{createGrid}}.

In some cases, models may require control arguments. These can be passed via the three dots argument. Note that some models can specify tuning parameters in the control objects. If specified, these values will be superseded by those given in the \code{\link{createGrid}} argument. 

The vignette entitled "caret Manual -- Model Building" has more details and examples related to this function.

\code{train} can be used with "explicit parallelism", where different resamples (e.g. cross-validation group) can be split up and run on multiple machines or processors. By default, \code{train} will use a single processor on the host machine. To use more, the \code{computeFunction} and \code{computeArgs} arguments in \code{\link{trainControl}} can be used. \code{computeFunction} is used to pass a function that takes arguments named \code{X} and \code{FUN}. Internally, \code{train} will pass the data and modeling functions through using these arguments. By default, \code{train} uses \code{\link[base]{lapply}}. Alternatively, any function that emulates \code{\link[base]{lapply}} but distributes jobs across multiple machines/processors can be used. Arguments to such a function can be passed (if needed) via the \code{computeArgs} argument in \code{\link{trainControl}}. Examples are given below using the \pkg{Rmpi} package (via \pkg{snow}) and NetworkSpaces (via the \pkg{nws} package).
}



\value{
  A list is returned of class \code{train} containing:
  \item{modelType }{an identifier of the model type.}  
  \item{results }{a data frame the training error rate and values of the tuning parameters.}
  \item{call }{the (matched) function call with dots expanded}
  \item{dots}{a list containing any ... values passed to the original call}
  \item{metric}{a string that specifies what summary metric will be used to select the optimal model.}  
  \item{trControl}{the list of control parameters.}
   \item{finalModel}{an fit object using the best parameters}
   \item{trainingData}{a data frame}
   \item{resample}{A data frame with columns for each performance
     metric. Each row corresponds to each resample. If leave-one-out
     cross-validation or out-of-bag estimation methods are requested,
     this will be \code{NULL}. The \code{returnResamp} argument of \code{\link{trainControl}}
     controls how much of the resampled results are saved.}
  \item{perfNames}{a character vector of performance metrics that are produced by the summary function}
  \item{maximize}{a logical recycled  from the function arguments.}
}

\author{Max Kuhn (the guts of \code{train.formula} were based on Ripley's \code{nnet.formula})}

\references{Kuhn (2008), ``Building Predictive Models in R Using the caret'' (\url{http://www.jstatsoft.org/v28/i05/})}

\seealso{\code{\link{trainControl}}, \code{\link{createGrid}}, \code{\link{createFolds}}}
\examples{
#######################################
## Classification Example

data(iris)
TrainData <- iris[,1:4]
TrainClasses <- iris[,5]

knnFit1 <- train(TrainData, TrainClasses,
                 "knn",
                 tuneLength = 10,
                 trControl = trainControl(method = "cv"))

knnFit2 <- train(TrainData, TrainClasses,
                 "knn", tuneLength = 10, 
                 trControl = trainControl(method = "boot"))


library(MASS)
nnetFit <- train(TrainData, TrainClasses,
                 "nnet", 
                 tuneLength = 2,
                 trace = FALSE,
                 maxit = 100)

#######################################
## Regression Example

library(mlbench)
data(BostonHousing)

lmFit <- train(medv ~ . + rm:lstat,
               data = BostonHousing, 
               "lm")

library(rpart)
rpartFit <- train(medv ~ .,
                  data = BostonHousing,
                  "rpart",
                  tuneLength = 9)

#######################################
## Example with a custom metric

madSummary <- 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, 
                  "earth",
                  tuneGrid = marsGrid,
                  metric = "MAD",
                  maximize = FALSE,
                  trControl = robustControl)

#######################################
## Parallel Processing Example via MPI

\dontrun{

## A function to emulate lapply in parallel
mpiClacs <- function(X, FUN, ...)
  {
    theDots <- list(...)
    parLapply(theDots$cl, X, FUN)
  }

library(snow)
cl <- makeCluster(5, "MPI")

## 50 bootstrap models distributed across 5 workers
mpiControl <- trainControl(workers = 5,
                           number = 50,
                           computeFunction = mpiClacs,
                           computeArgs = list(cl = cl))
set.seed(1)
usingMPI <-  train(medv ~ .,
                   data = BostonHousing, 
                   "glmboost",
                   trControl = mpiControl)

stopCluster(cl)
}

#######################################
## Parallel Processing Example via NWS
\dontrun{

nwsClacs <- function(X, FUN, ...)
  {
    theDots <- list(...)
    eachElem(theDots$sObj,
             fun = FUN,
             elementArgs = list(X))
  }

library(nws)
sObj <- sleigh(workerCount = 5)

nwsControl <- trainControl(workers = 5,
                           number = 50,
                           computeFunction = nwsClacs,
                           computeArgs = list(sObj = sObj))
set.seed(1)
usingNWS <-  train(medv ~ .,
                   data = BostonHousing, 
                   "glmboost",
                   trControl = nwsControl)

close(sObj)

}


}

\keyword{models}
