[R] docs update - callbacks and parameter style

R-package/man/callbacks.Rd

@@ -19,18 +19,19 @@ WARNING: side-effects!!! Be aware that these callback functions access and modif
 the environment from which they are called from, which is a fairly uncommon thing to do in R.
 
 To write a custom callback closure, make sure you first understand the main concepts about R envoronments.
-Check either the R docs on \code{\link[base]{environment}} or the 
+Check either R documentation on \code{\link[base]{environment}} or the 
-\href{http://adv-r.had.co.nz/Environments.html}{Environments chapter} from Hadley Wickham's "Advanced R" book.
+\href{http://adv-r.had.co.nz/Environments.html}{Environments chapter} from the "Advanced R" 
-Then take a look at the code of \code{cb.reset_learning_rate} for a simple example, 
+book by Hadley Wickham. Further, the best option is to read the code of some of the existing callbacks -
-and see the \code{cb.log_evaluation} code for something more involved.
+choose ones that do something similar to what you want to achieve. Also, you would need to get familiar 
-Also, you would need to get familiar with the objects available inside of the \code{xgb.train} internal environment.
+with the objects available inside of the \code{xgb.train} and \code{xgb.cv} internal environments.
 }
 \seealso{
-\code{\link{cb.print_evaluation}},
+\code{\link{cb.print.evaluation}},
-\code{\link{cb.log_evaluation}},
+\code{\link{cb.evaluation.log}},
-\code{\link{cb.reset_parameters}},
+\code{\link{cb.reset.parameters}},
-\code{\link{cb.early_stop}},
+\code{\link{cb.early.stop}},
-\code{\link{cb.save_model}},
+\code{\link{cb.save.model}},
+\code{\link{cb.cv.predict}},
 \code{\link{xgb.train}},
 \code{\link{xgb.cv}}
 }

R-package/man/cb.cv.predict.Rd

@@ -0,0 +1,43 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/callbacks.R
+\name{cb.cv.predict}
+\alias{cb.cv.predict}
+\title{Callback closure for returning cross-validation based predictions.}
+\usage{
+cb.cv.predict(save_models = FALSE)
+}
+\arguments{
+\item{save_models}{a flag for whether to save the folds' models.}
+}
+\value{
+Predictions are returned inside of the \code{pred} element, which is either a vector or a matrix,
+depending on the number of prediction outputs per data row. The order of predictions corresponds 
+to the order of rows in the original dataset. Note that when a custom \code{folds} list is 
+provided in \code{xgb.cv}, the predictions would only be returned properly when this list is a 
+non-overlapping list of k sets of indices, as in a standard k-fold CV. The predictions would not be 
+meaningful when user-profided folds have overlapping indices as in, e.g., random sampling splits.
+When some of the indices in the training dataset are not included into user-provided \code{folds},
+their prediction value would be \code{NA}.
+}
+\description{
+Callback closure for returning cross-validation based predictions.
+}
+\details{
+This callback function saves predictions for all of the test folds,
+and also allows to save the folds' models.
+
+It is a "finalizer" callback and it uses early stopping information whenever it is available,
+thus it must be run after the early stopping callback if the early stopping is used.
+
+Callback function expects the following values to be set in its calling frame:
+\code{bst_folds},
+\code{basket},
+\code{data},
+\code{end_iteration},
+\code{num_parallel_tree},
+\code{num_class}.
+}
+\seealso{
+\code{\link{callbacks}}
+}
+

R-package/man/cb.early.stop.Rd

@@ -0,0 +1,63 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/callbacks.R
+\name{cb.early.stop}
+\alias{cb.early.stop}
+\title{Callback closure to activate the early stopping.}
+\usage{
+cb.early.stop(stopping_rounds, maximize = FALSE, metric_name = NULL,
+  verbose = TRUE)
+}
+\arguments{
+\item{stopping_rounds}{The number of rounds with no improvement in 
+the evaluation metric in order to stop the training.}
+
+\item{maximize}{whether to maximize the evaluation metric}
+
+\item{metric_name}{the name of an evaluation column to use as a criteria for early
+stopping. If not set, the last column would be used.
+Let's say the test data in \code{watchlist} was labelled as \code{dtest}, 
+and one wants to use the AUC in test data for early stopping regardless of where 
+it is in the \code{watchlist}, then one of the following would need to be set:
+\code{metric_name='dtest-auc'} or \code{metric_name='dtest_auc'}.
+All dash '-' characters in metric names are considered equivalent to '_'.}
+
+\item{verbose}{whether to print the early stopping information.}
+}
+\description{
+Callback closure to activate the early stopping.
+}
+\details{
+This callback function determines the condition for early stopping 
+by setting the \code{stop_condition = TRUE} flag in its calling frame.
+
+The following additional fields are assigned to the model's R object:
+\itemize{
+\item \code{best_score} the evaluation score at the best iteration
+\item \code{best_iteration} at which boosting iteration the best score has occurred (1-based index)
+\item \code{best_ntreelimit} to use with the \code{ntreelimit} parameter in \code{predict}.
+     It differs from \code{best_iteration} in multiclass or random forest settings.
+}
+
+The Same values are also stored as xgb-attributes:
+\itemize{
+\item \code{best_iteration} is stored as a 0-based iteration index (for interoperability of binary models)
+\item \code{best_msg} message string is also stored.
+}
+
+At least one data element is required in the evaluation watchlist for early stopping to work.
+
+Callback function expects the following values to be set in its calling frame:
+\code{stop_condition},
+\code{bst_evaluation},
+\code{rank},
+\code{bst} (or \code{bst_folds} and \code{basket}),
+\code{iteration},
+\code{begin_iteration},
+\code{end_iteration},
+\code{num_parallel_tree}.
+}
+\seealso{
+\code{\link{callbacks}},
+\code{\link{xgb.attr}}
+}
+

R-package/man/cb.evaluation.log.Rd

@@ -0,0 +1,32 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/callbacks.R
+\name{cb.evaluation.log}
+\alias{cb.evaluation.log}
+\title{Callback closure for logging the evaluation history}
+\usage{
+cb.evaluation.log()
+}
+\description{
+Callback closure for logging the evaluation history
+}
+\details{
+This callback function appends the current iteration evaluation results \code{bst_evaluation}
+available in the calling parent frame to the \code{evaluation_log} list in a calling frame.
+
+The finalizer callback (called with \code{finalize = TURE} in the end) converts 
+the \code{evaluation_log} list into a final data.table.
+
+The iteration evaluation result \code{bst_evaluation} must be a named numeric vector. 
+
+Note: in the column names of the final data.table, the dash '-' character is replaced with 
+the underscore '_' in order to make the column names more like regular R identifiers.
+
+Callback function expects the following values to be set in its calling frame:
+\code{evaluation_log},
+\code{bst_evaluation},
+\code{iteration}.
+}
+\seealso{
+\code{\link{callbacks}}
+}
+

R-package/man/cb.print.evaluation.Rd

@@ -0,0 +1,28 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/callbacks.R
+\name{cb.print.evaluation}
+\alias{cb.print.evaluation}
+\title{Callback closure for printing the result of evaluation}
+\usage{
+cb.print.evaluation(period = 1)
+}
+\arguments{
+\item{period}{results would be printed every number of periods}
+}
+\description{
+Callback closure for printing the result of evaluation
+}
+\details{
+The callback function prints the result of evaluation at every \code{period} iterations.
+The initial and the last iteration's evaluations are always printed.
+
+Callback function expects the following values to be set in its calling frame:
+\code{bst_evaluation} (also \code{bst_evaluation_err} when available),
+\code{iteration},
+\code{begin_iteration},
+\code{end_iteration}.
+}
+\seealso{
+\code{\link{callbacks}}
+}
+

R-package/man/cb.reset.parameters.Rd

@@ -0,0 +1,37 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/callbacks.R
+\name{cb.reset.parameters}
+\alias{cb.reset.parameters}
+\title{Callback closure for restetting the booster's parameters at each iteration.}
+\usage{
+cb.reset.parameters(new_params)
+}
+\arguments{
+\item{new_params}{a list where each element corresponds to a parameter that needs to be reset.
+Each element's value must be either a vector of values of length \code{nrounds} 
+to be set at each iteration, 
+or a function of two parameters \code{learning_rates(iteration, nrounds)} 
+which returns a new parameter value by using the current iteration number 
+and the total number of boosting rounds.}
+}
+\description{
+Callback closure for restetting the booster's parameters at each iteration.
+}
+\details{
+This is a "pre-iteration" callback function used to reset booster's parameters
+at the beginning of each iteration.
+
+Note that when training is resumed from some previous model, and a function is used to 
+reset a parameter value, the \code{nround} argument in this function would be the 
+the number of boosting rounds in the current training.
+
+Callback function expects the following values to be set in its calling frame:
+\code{bst} or \code{bst_folds},
+\code{iteration},
+\code{begin_iteration},
+\code{end_iteration}.
+}
+\seealso{
+\code{\link{callbacks}}
+}
+

R-package/man/cb.save.model.Rd

@@ -0,0 +1,34 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/callbacks.R
+\name{cb.save.model}
+\alias{cb.save.model}
+\title{Callback closure for saving a model file.}
+\usage{
+cb.save.model(save_period = 0, save_name = "xgboost.model")
+}
+\arguments{
+\item{save_period}{save the model to disk after every 
+\code{save_period} iterations; 0 means save the model at the end.}
+
+\item{save_name}{the name or path for the saved model file.
+It can contain a \code{\link[base]{sprintf}} formatting specifier 
+to include the integer iteration number in the file name.
+E.g., with \code{save_name} = 'xgboost_%04d.model', 
+the file saved at iteration 50 would be named "xgboost_0050.model".}
+}
+\description{
+Callback closure for saving a model file.
+}
+\details{
+This callback function allows to save an xgb-model file, either periodically after each \code{save_period}'s or at the end.
+
+Callback function expects the following values to be set in its calling frame:
+\code{bst},
+\code{iteration},
+\code{begin_iteration},
+\code{end_iteration}.
+}
+\seealso{
+\code{\link{callbacks}}
+}
+

R-package/man/get.paths.to.leaf.Rd

@@ -4,7 +4,7 @@
 \alias{get.paths.to.leaf}
 \title{Extract path from root to leaf from data.table}
 \usage{
-get.paths.to.leaf(dt.tree)
+get.paths.to.leaf(dt_tree)
 }
 \arguments{
 \item{dt.tree}{data.table containing the nodes and edges of the trees}

R-package/man/predict.xgb.Booster.Rd

@@ -6,53 +6,124 @@
 \title{Predict method for eXtreme Gradient Boosting model}
 \usage{
 \method{predict}{xgb.Booster}(object, newdata, missing = NA,
-  outputmargin = FALSE, ntreelimit = NULL, predleaf = FALSE)
+  outputmargin = FALSE, ntreelimit = NULL, predleaf = FALSE,
+  reshape = FALSE)
 
 \method{predict}{xgb.Booster.handle}(object, ...)
 }
 \arguments{
 \item{object}{Object of class \code{xgb.Booster} or \code{xgb.Booster.handle}}
 
-\item{newdata}{takes \code{matrix}, \code{dgCMatrix}, local data file or 
+\item{newdata}{takes \code{matrix}, \code{dgCMatrix}, local data file or \code{xgb.DMatrix}.}
-\code{xgb.DMatrix}.}
 
-\item{missing}{Missing is only used when input is dense matrix, pick a float 
+\item{missing}{Missing is only used when input is dense matrix. Pick a float value that represents
-value that represents missing value. Sometime a data use 0 or other extreme value to represents missing values.}
+missing values in data (e.g., sometimes 0 or some other extreme value is used).}
 
-\item{outputmargin}{whether the prediction should be shown in the original
+\item{outputmargin}{whether the prediction should be returned in the for of original untransformed 
-value of sum of functions, when outputmargin=TRUE, the prediction is 
+sum of predictions from boosting iterations' results. E.g., setting \code{outputmargin=TRUE} for 
-untransformed margin value. In logistic regression, outputmargin=T will
+logistic regression would result in predictions for log-odds instead of probabilities.}
-output value before logistic transformation.}
 
-\item{ntreelimit}{limit number of trees used in prediction, this parameter is
+\item{ntreelimit}{limit the number of model's trees or boosting iterations used in prediction (see Details).
-only valid for gbtree, but not for gblinear. set it to be value bigger 
+It will use all the trees by default (\code{NULL} value).}
-than 0. It will use all trees by default.}
 
-\item{predleaf}{whether predict leaf index instead. If set to TRUE, the output will be a matrix object.}
+\item{predleaf}{whether predict leaf index instead.}
 
-\item{...}{Parameters pass to \code{predict.xgb.Booster}}
+\item{reshape}{whether to reshape the vector of predictions to a matrix form when there are several 
+prediction outputs per case. This option has no effect when \code{predleaf = TRUE}.}
+
+\item{...}{Parameters passed to \code{predict.xgb.Booster}}
+}
+\value{
+For regression or binary classification, it returns a vector of length \code{nrows(newdata)}.
+For multiclass classification, either a \code{num_class * nrows(newdata)} vector or 
+a \code{(nrows(newdata), num_class)} dimension matrix is returned, depending on 
+the \code{reshape} value.
+
+When \code{predleaf = TRUE}, the output is a matrix object with the 
+number of columns corresponding to the number of trees.
 }
 \description{
 Predicted values based on either xgboost model or model handle object.
 }
 \details{
-The option \code{ntreelimit} purpose is to let the user train a model with lots 
+Note that \code{ntreelimit} is not necesserily equal to the number of boosting iterations
-of trees but use only the first trees for prediction to avoid overfitting 
+and it is not necesserily equal to the number of trees in a model.
-(without having to train a new model with less trees).
+E.g., in a random forest-like model, \code{ntreelimit} would limit the number of trees.
+But for multiclass classification, there are multiple trees per iteration, 
+but \code{ntreelimit} limits the number of boosting iterations.
 
-The option \code{predleaf} purpose is inspired from §3.1 of the paper 
+Also note that \code{ntreelimit} would currently do nothing for predictions from gblinear, 
-\code{Practical Lessons from Predicting Clicks on Ads at Facebook}.
+since gblinear doesn't keep its boosting history. 
-The idea is to use the model as a generator of new features which capture non linear link 
+
-from original features.
+One possible practical applications of the \code{predleaf} option is to use the model 
+as a generator of new features which capture non-linearity and interactions, 
+e.g., as implemented in \code{\link{xgb.create.features}}.
 }
 \examples{
+## binary classification:
+
 data(agaricus.train, package='xgboost')
 data(agaricus.test, package='xgboost')
 train <- agaricus.train
 test <- agaricus.test
 
-bst <- xgboost(data = train$data, label = train$label, max.depth = 2, 
+bst <- xgboost(data = train$data, label = train$label, max_depth = 2, 
-               eta = 1, nthread = 2, nround = 2,objective = "binary:logistic")
+               eta = 1, nthread = 2, nrounds = 2, objective = "binary:logistic")
+# use all trees by default
 pred <- predict(bst, test$data)
+# use only the 1st tree
+pred <- predict(bst, test$data, ntreelimit = 1)
+
+
+## multiclass classification in iris dataset:
+
+lb <- as.numeric(iris$Species) - 1
+num_class <- 3
+set.seed(11)
+bst <- xgboost(data = as.matrix(iris[, -5]), label = lb,
+               max_depth = 4, eta = 0.5, nthread = 2, nrounds = 10, subsample = 0.5,
+               objective = "multi:softprob", num_class = num_class)
+# predict for softmax returns num_class probability numbers per case:
+pred <- predict(bst, as.matrix(iris[, -5]))
+str(pred)
+# reshape it to a num_class-columns matrix
+pred <- matrix(pred, ncol=num_class, byrow=TRUE)
+# convert the probabilities to softmax labels
+pred_labels <- max.col(pred) - 1
+# the following should result in the same error as seen in the last iteration
+sum(pred_labels != lb)/length(lb)
+
+# compare that to the predictions from softmax:
+set.seed(11)
+bst <- xgboost(data = as.matrix(iris[, -5]), label = lb,
+               max_depth = 4, eta = 0.5, nthread = 2, nrounds = 10, subsample = 0.5,
+               objective = "multi:softmax", num_class = num_class)
+pred <- predict(bst, as.matrix(iris[, -5]))
+str(pred)
+all.equal(pred, pred_labels)
+# prediction from using only 5 iterations should result 
+# in the same error as seen in iteration 5:
+pred5 <- predict(bst, as.matrix(iris[, -5]), ntreelimit=5)
+sum(pred5 != lb)/length(lb)
+
+
+## random forest-like model of 25 trees for binary classification:
+
+set.seed(11)
+bst <- xgboost(data = train$data, label = train$label, max_depth = 5,
+               nthread = 2, nrounds = 1, objective = "binary:logistic",
+               num_parallel_tree = 25, subsample = 0.6, colsample_bytree = 0.1)
+# Inspect the prediction error vs number of trees:
+lb <- test$label
+dtest <- xgb.DMatrix(test$data, label=lb)
+err <- sapply(1:25, function(n) {
+  pred <- predict(bst, dtest, ntreelimit=n)
+  sum((pred > 0.5) != lb)/length(lb)
+})
+plot(err, type='l', ylim=c(0,0.1), xlab='#trees')
+
+}
+\seealso{
+\code{\link{xgb.train}}.
 }
 

R-package/man/print.xgb.Booster.Rd

@@ -19,8 +19,8 @@ Print information about xgb.Booster.
 \examples{
 data(agaricus.train, package='xgboost')
 train <- agaricus.train
-bst <- xgboost(data = train$data, label = train$label, max.depth = 2,
+bst <- xgboost(data = train$data, label = train$label, max_depth = 2,
-               eta = 1, nthread = 2, nround = 2, objective = "binary:logistic")
+               eta = 1, nthread = 2, nrounds = 2, objective = "binary:logistic")
 attr(bst, 'myattr') <- 'memo'
 
 print(bst)

R-package/man/print.xgb.cv.Rd

@@ -23,8 +23,8 @@ including the best iteration (when available).
 \examples{
 data(agaricus.train, package='xgboost')
 train <- agaricus.train
-cv <- xgb.cv(data = train$data, label = train$label, nfold = 5, max.depth = 2,
+cv <- xgb.cv(data = train$data, label = train$label, nfold = 5, max_depth = 2,
-               eta = 1, nthread = 2, nround = 2, objective = "binary:logistic")
+               eta = 1, nthread = 2, nrounds = 2, objective = "binary:logistic")
 print(cv)
 print(cv, verbose=TRUE)
 

R-package/man/xgb.DMatrix.save.Rd

@@ -4,12 +4,12 @@
 \alias{xgb.DMatrix.save}
 \title{Save xgb.DMatrix object to binary file}
 \usage{
-xgb.DMatrix.save(DMatrix, fname)
+xgb.DMatrix.save(dmatrix, fname)
 }
 \arguments{
-\item{DMatrix}{the DMatrix object}
+\item{dmatrix}{the \code{xgb.DMatrix} object}
 
-\item{fname}{the name of the binary file.}
+\item{fname}{the name of the file to write.}
 }
 \description{
 Save xgb.DMatrix object to binary file

R-package/man/xgb.attr.Rd

@@ -52,16 +52,20 @@ Use \code{\link{`xgb.parameters<-`}} to set or change model parameters.
 
 The attribute setters would usually work more efficiently for \code{xgb.Booster.handle}
 than for \code{xgb.Booster}, since only just a handle (pointer) would need to be copied.
+That would only matter if attributes need to be set many times.
+Note, however, that when feeding a handle of an \code{xgb.Booster} object to the attribute setters,
+the raw model cache of an \code{xgb.Booster} object would not be automatically updated, 
+and it would be user's responsibility to call \code{xgb.save.raw} to update it.
 
 The \code{xgb.attributes<-} setter either updates the existing or adds one or several attributes, 
-but doesn't delete the existing attributes which don't have their names in \code{names(attributes)}.
+but it doesn't delete the other existing attributes.
 }
 \examples{
 data(agaricus.train, package='xgboost')
 train <- agaricus.train
 
-bst <- xgboost(data = train$data, label = train$label, max.depth = 2,
+bst <- xgboost(data = train$data, label = train$label, max_depth = 2,
-               eta = 1, nthread = 2, nround = 2, objective = "binary:logistic")
+               eta = 1, nthread = 2, nrounds = 2, objective = "binary:logistic")
 
 xgb.attr(bst, "my_attribute") <- "my attribute value"
 print(xgb.attr(bst, "my_attribute"))

R-package/man/xgb.create.features.Rd

@@ -4,12 +4,14 @@
 \alias{xgb.create.features}
 \title{Create new features from a previously learned model}
 \usage{
-xgb.create.features(model, training.data)
+xgb.create.features(model, data, ...)
 }
 \arguments{
 \item{model}{decision tree boosting model learned on the original data}
 
-\item{training.data}{original data (usually provided as a \code{dgCMatrix} matrix)}
+\item{data}{original data (usually provided as a \code{dgCMatrix} matrix)}
+
+\item{...}{currently not used}
 }
 \value{
 \code{dgCMatrix} matrix including both the original data and the new features.
@@ -60,7 +62,7 @@ data(agaricus.test, package='xgboost')
 dtrain <- xgb.DMatrix(data = agaricus.train$data, label = agaricus.train$label)
 dtest <- xgb.DMatrix(data = agaricus.test$data, label = agaricus.test$label)
 
-param <- list(max.depth=2, eta=1, silent=1, objective='binary:logistic')
+param <- list(max_depth=2, eta=1, silent=1, objective='binary:logistic')
 nround = 4
 
 bst = xgb.train(params = param, data = dtrain, nrounds = nround, nthread = 2)

R-package/man/xgb.cv.Rd

@@ -7,7 +7,7 @@
 xgb.cv(params = list(), data, nrounds, nfold, label = NULL, missing = NA,
   prediction = FALSE, showsd = TRUE, metrics = list(), obj = NULL,
   feval = NULL, stratified = TRUE, folds = NULL, verbose = TRUE,
-  print.every.n = 1L, early.stop.round = NULL, maximize = NULL,
+  print_every_n = 1L, early_stopping_rounds = NULL, maximize = NULL,
   callbacks = list(), ...)
 }
 \arguments{
@@ -19,11 +19,11 @@ xgb.cv(params = list(), data, nrounds, nfold, label = NULL, missing = NA,
     \item \code{binary:logistic} logistic regression for classification
   }
   \item \code{eta} step size of each boosting step
-  \item \code{max.depth} maximum depth of the tree
+  \item \code{max_depth} maximum depth of the tree
   \item \code{nthread} number of thread used in training, if not set, all threads are used
 }
 
-  See \link{xgb.train} for further details.
+  See \code{\link{xgb.train}} for further details.
   See also demo/ for walkthrough example in R.}
 
 \item{data}{takes an \code{xgb.DMatrix} or \code{Matrix} as the input.}
@@ -32,14 +32,16 @@ xgb.cv(params = list(), data, nrounds, nfold, label = NULL, missing = NA,
 
 \item{nfold}{the original dataset is randomly partitioned into \code{nfold} equal size subsamples.}
 
-\item{label}{option field, when data is \code{Matrix}}
+\item{label}{vector of response values. Should be provided only when data is \code{DMatrix}.}
 
-\item{missing}{Missing is only used when input is dense matrix, pick a float
+\item{missing}{is only used when input is a dense matrix. By default is set to NA, which means 
-value that represents missing value. Sometime a data use 0 or other extreme value to represents missing values.}
+that NA values should be considered as 'missing' by the algorithm. 
+Sometimes, 0 or other extreme value might be used to represent missing values.}
 
-\item{prediction}{A logical value indicating whether to return the prediction vector.}
+\item{prediction}{A logical value indicating whether to return the test fold predictions 
+from each CV model. This parameter engages the \code{\link{cb.cv.predict}} callback.}
 
-\item{showsd}{\code{boolean}, whether show standard deviation of cross validation}
+\item{showsd}{\code{boolean}, whether to show standard deviation of cross validation}
 
 \item{metrics, }{list of evaluation metrics to be used in cross validation,
   when it is not specified, the evaluation metric is chosen according to objective function.
@@ -59,34 +61,61 @@ gradient with given prediction and dtrain.}
 \code{list(metric='metric-name', value='metric-value')} with given 
 prediction and dtrain.}
 
-\item{stratified}{\code{boolean} whether sampling of folds should be stratified by the values of labels in \code{data}}
+\item{stratified}{a \code{boolean} indicating whether sampling of folds should be stratified 
+by the values of outcome labels.}
 
-\item{folds}{\code{list} provides a possibility of using a list of pre-defined CV folds (each element must be a vector of fold's indices).
+\item{folds}{\code{list} provides a possibility to use a list of pre-defined CV folds
-If folds are supplied, the nfold and stratified parameters would be ignored.}
+(each element must be a vector of test fold's indices). When folds are supplied, 
+the \code{nfold} and \code{stratified} parameters are ignored.}
 
 \item{verbose}{\code{boolean}, print the statistics during the process}
 
-\item{print.every.n}{Print every N progress messages when \code{verbose>0}. Default is 1 which means all messages are printed.}
+\item{print_every_n}{Print each n-th iteration evaluation messages when \code{verbose>0}.
+Default is 1 which means all messages are printed. This parameter is passed to the 
+\code{\link{cb.print.evaluation}} callback.}
 
-\item{early.stop.round}{If \code{NULL}, the early stopping function is not triggered. 
+\item{early_stopping_rounds}{If \code{NULL}, the early stopping function is not triggered. 
 If set to an integer \code{k}, training with a validation set will stop if the performance 
-doesn't improve for \code{k} rounds.}
+doesn't improve for \code{k} rounds.
+Setting this parameter engages the \code{\link{cb.early.stop}} callback.}
 
-\item{maximize}{If \code{feval} and \code{early.stop.round} are set, then \code{maximize} must be set as well.
+\item{maximize}{If \code{feval} and \code{early_stopping_rounds} are set,
-\code{maximize=TRUE} means the larger the evaluation score the better.}
+then this parameter must be set as well.
+When it is \code{TRUE}, it means the larger the evaluation score the better.
+This parameter is passed to the \code{\link{cb.early.stop}} callback.}
+
+\item{callbacks}{a list of callback functions to perform various task during boosting.
+See \code{\link{callbacks}}. Some of the callbacks are automatically created depending on the 
+parameters' values. User can provide either existing or their own callback methods in order 
+to customize the training process.}
 
 \item{...}{other parameters to pass to \code{params}.}
 }
 \value{
-TODO: update this...
+An object of class \code{xgb.cv.synchronous} with the following elements:
-
-If \code{prediction = TRUE}, a list with the following elements is returned:
 \itemize{
-  \item \code{dt} a \code{data.table} with each mean and standard deviation stat for training set and test set
+  \item \code{call} a function call.
-  \item \code{pred} an array or matrix (for multiclass classification) with predictions for each CV-fold for the model having been trained on the data in all other folds.
+  \item \code{params} parameters that were passed to the xgboost library. Note that it does not 
+        capture parameters changed by the \code{\link{cb.reset.parameters}} callback.
+  \item \code{callbacks} callback functions that were either automatically assigned or 
+        explicitely passed.
+  \item \code{evaluation_log} evaluation history storead as a \code{data.table} with the
+        first column corresponding to iteration number and the rest corresponding to the 
+        CV-based evaluation means and standard deviations for the training and test CV-sets.
+        It is created by the \code{\link{cb.evaluation.log}} callback.
+  \item \code{niter} number of boosting iterations.
+  \item \code{folds} the list of CV folds' indices - either those passed through the \code{folds} 
+        parameter or randomly generated.
+  \item \code{best_iteration} iteration number with the best evaluation metric value
+        (only available with early stopping).
+  \item \code{best_ntreelimit} the \code{ntreelimit} value corresponding to the best iteration, 
+        which could further be used in \code{predict} method
+        (only available with early stopping).
+  \item \code{pred} CV prediction values available when \code{prediction} is set. 
+        It is either vector or matrix (see \code{\link{cb.cv.predict}}).
+  \item \code{models} a liost of the CV folds' models. It is only available with the explicit 
+        setting of the \code{cb.cv.predict(save_models = TRUE)} callback.
 }
-
-If \code{prediction = FALSE}, just a \code{data.table} with each mean and standard deviation stat for training set and test set is returned.
 }
 \description{
 The cross valudation function of xgboost
@@ -105,9 +134,10 @@ Adapted from \url{http://en.wikipedia.org/wiki/Cross-validation_\%28statistics\%
 \examples{
 data(agaricus.train, package='xgboost')
 dtrain <- xgb.DMatrix(agaricus.train$data, label = agaricus.train$label)
-history <- xgb.cv(data = dtrain, nround=3, nthread = 2, nfold = 5, metrics=list("rmse","auc"),
+cv <- xgb.cv(data = dtrain, nrounds = 3, nthread = 2, nfold = 5, metrics = list("rmse","auc"),
-                  max.depth =3, eta = 1, objective = "binary:logistic")
+                  max_depth = 3, eta = 1, objective = "binary:logistic")
-print(history)
+print(cv)
+print(cv, verbose=TRUE)
 
 }
 

R-package/man/xgb.dump.Rd

@@ -4,7 +4,7 @@
 \alias{xgb.dump}
 \title{Save xgboost model to text file}
 \usage{
-xgb.dump(model = NULL, fname = NULL, fmap = "", with.stats = FALSE)
+xgb.dump(model = NULL, fname = NULL, fmap = "", with_stats = FALSE, ...)
 }
 \arguments{
 \item{model}{the model object.}
@@ -18,10 +18,12 @@ See demo/ for walkthrough example in R, and
 \url{https://github.com/dmlc/xgboost/blob/master/demo/data/featmap.txt} 
 for example Format.}
 
-\item{with.stats}{whether dump statistics of splits 
+\item{with_stats}{whether dump statistics of splits 
 When this option is on, the model dump comes with two additional statistics:
 gain is the approximate loss function gain we get in each split;
 cover is the sum of second order gradient in each node.}
+
+\item{...}{currently not used}
 }
 \value{
 if fname is not provided or set to \code{NULL} the function will return the model as a \code{character} vector. Otherwise it will return \code{TRUE}.
@@ -34,10 +36,10 @@ data(agaricus.train, package='xgboost')
 data(agaricus.test, package='xgboost')
 train <- agaricus.train
 test <- agaricus.test
-bst <- xgboost(data = train$data, label = train$label, max.depth = 2, 
+bst <- xgboost(data = train$data, label = train$label, max_depth = 2, 
-               eta = 1, nthread = 2, nround = 2,objective = "binary:logistic")
+               eta = 1, nthread = 2, nrounds = 2, objective = "binary:logistic")
 # save the model in file 'xgb.model.dump'
-xgb.dump(bst, 'xgb.model.dump', with.stats = TRUE)
+xgb.dump(bst, 'xgb.model.dump', with_stats = TRUE)
 
 # print the model without saving it to a file
 print(xgb.dump(bst))

R-package/man/xgb.importance.Rd

@@ -52,14 +52,13 @@ If you need to remember one thing only: until you want to leave us early, don't
 \examples{
 data(agaricus.train, package='xgboost')
 
-bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max.depth = 2, 
+bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max_depth = 2, 
-               eta = 1, nthread = 2, nround = 2,objective = "binary:logistic")
+               eta = 1, nthread = 2, nrounds = 2,objective = "binary:logistic")
 
-# agaricus.train$data@Dimnames[[2]] represents the column names of the sparse matrix.
+xgb.importance(colnames(agaricus.train$data), model = bst)
-xgb.importance(agaricus.train$data@Dimnames[[2]], model = bst)
 
 # Same thing with co-occurence computation this time
-xgb.importance(agaricus.train$data@Dimnames[[2]], model = bst, data = agaricus.train$data, label = agaricus.train$label)
+xgb.importance(colnames(agaricus.train$data), model = bst, data = agaricus.train$data, label = agaricus.train$label)
 
 }
 

R-package/man/xgb.load.Rd

@@ -17,8 +17,8 @@ data(agaricus.train, package='xgboost')
 data(agaricus.test, package='xgboost')
 train <- agaricus.train
 test <- agaricus.test
-bst <- xgboost(data = train$data, label = train$label, max.depth = 2, 
+bst <- xgboost(data = train$data, label = train$label, max_depth = 2, 
-               eta = 1, nthread = 2, nround = 2,objective = "binary:logistic")
+               eta = 1, nthread = 2, nrounds = 2,objective = "binary:logistic")
 xgb.save(bst, 'xgb.model')
 bst <- xgb.load('xgb.model')
 pred <- predict(bst, test$data)

R-package/man/xgb.model.dt.tree.Rd

@@ -14,7 +14,7 @@ contains feature names, this argument should be \code{NULL} (default value)}
 \item{model}{object of class \code{xgb.Booster}}
 
 \item{text}{\code{character} vector previously generated by the \code{xgb.dump} 
-function  (where parameter \code{with.stats = TRUE} should have been set).}
+function  (where parameter \code{with_stats = TRUE} should have been set).}
 
 \item{n_first_tree}{limit the parsing to the \code{n} first trees. 
 If set to \code{NULL}, all trees of the model are parsed.}
@@ -47,8 +47,8 @@ Parse a boosted tree model text dump into a \code{data.table} structure.
 
 data(agaricus.train, package='xgboost')
 
-bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max.depth = 2, 
+bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max_depth = 2, 
-               eta = 1, nthread = 2, nround = 2,objective = "binary:logistic")
+               eta = 1, nthread = 2, nrounds = 2,objective = "binary:logistic")
 
 (dt <- xgb.model.dt.tree(colnames(agaricus.train$data), bst))
 

R-package/man/xgb.parameters.Rd

@@ -23,8 +23,8 @@ than for \code{xgb.Booster}, since only just a handle would need to be copied.
 data(agaricus.train, package='xgboost')
 train <- agaricus.train
 
-bst <- xgboost(data = train$data, label = train$label, max.depth = 2,
+bst <- xgboost(data = train$data, label = train$label, max_depth = 2,
-               eta = 1, nthread = 2, nround = 2, objective = "binary:logistic")
+               eta = 1, nthread = 2, nrounds = 2, objective = "binary:logistic")
 
 xgb.parameters(bst) <- list(eta = 0.1)
 

R-package/man/xgb.plot.deepness.Rd

@@ -20,7 +20,7 @@ Display both the number of \code{leaf} and the distribution of \code{weighted ob
 by tree deepness level.
 
 The purpose of this function is to help the user to find the best trade-off to set
-the \code{max.depth} and \code{min_child_weight} parameters according to the bias / variance trade-off.
+the \code{max_depth} and \code{min_child_weight} parameters according to the bias / variance trade-off.
 
 See \link{xgb.train} for more information about these parameters.
 
@@ -36,8 +36,8 @@ This function is inspired by the blog post \url{http://aysent.github.io/2015/11/
 \examples{
 data(agaricus.train, package='xgboost')
 
-bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max.depth = 15,
+bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max_depth = 15,
-                 eta = 1, nthread = 2, nround = 30, objective = "binary:logistic",
+                 eta = 1, nthread = 2, nrounds = 30, objective = "binary:logistic",
                  min_child_weight = 50)
 
 xgb.plot.deepness(model = bst)

R-package/man/xgb.plot.importance.Rd

@@ -4,12 +4,14 @@
 \alias{xgb.plot.importance}
 \title{Plot feature importance bar graph}
 \usage{
-xgb.plot.importance(importance_matrix = NULL, numberOfClusters = c(1:10))
+xgb.plot.importance(importance_matrix = NULL, n_clusters = c(1:10), ...)
 }
 \arguments{
 \item{importance_matrix}{a \code{data.table} returned by the \code{xgb.importance} function.}
 
-\item{numberOfClusters}{a \code{numeric} vector containing the min and the max range of the possible number of clusters of bars.}
+\item{n_clusters}{a \code{numeric} vector containing the min and the max range of the possible number of clusters of bars.}
+
+\item{...}{currently not used}
 }
 \value{
 A \code{ggplot2} bar graph representing each feature by a horizontal bar. Longer is the bar, more important is the feature. Features are classified by importance and clustered by importance. The group is represented through the color of the bar.
@@ -29,11 +31,10 @@ data(agaricus.train, package='xgboost')
 #(labels = outcome column which will be learned).
 #Each column of the sparse Matrix is a feature in one hot encoding format.
 
-bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max.depth = 2,
+bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max_depth = 2,
-               eta = 1, nthread = 2, nround = 2,objective = "binary:logistic")
+               eta = 1, nthread = 2, nrounds = 2, objective = "binary:logistic")
 
-#agaricus.train$data@Dimnames[[2]] represents the column names of the sparse matrix.
+importance_matrix <- xgb.importance(colnames(agaricus.train$data), model = bst)
-importance_matrix <- xgb.importance(agaricus.train$data@Dimnames[[2]], model = bst)
 xgb.plot.importance(importance_matrix)
 
 }

R-package/man/xgb.plot.multi.trees.Rd

@@ -4,19 +4,21 @@
 \alias{xgb.plot.multi.trees}
 \title{Project all trees on one tree and plot it}
 \usage{
-xgb.plot.multi.trees(model, feature_names = NULL, features.keep = 5,
+xgb.plot.multi.trees(model, feature_names = NULL, features_keep = 5,
-  plot.width = NULL, plot.height = NULL)
+  plot_width = NULL, plot_height = NULL, ...)
 }
 \arguments{
 \item{model}{dump generated by the \code{xgb.train} function.}
 
 \item{feature_names}{names of each feature as a \code{character} vector. Can be extracted from a sparse matrix (see example). If model dump already contains feature names, this argument should be \code{NULL}.}
 
-\item{features.keep}{number of features to keep in each position of the multi trees.}
+\item{features_keep}{number of features to keep in each position of the multi trees.}
 
-\item{plot.width}{width in pixels of the graph to produce}
+\item{plot_width}{width in pixels of the graph to produce}
 
-\item{plot.height}{height in pixels of the graph to produce}
+\item{plot_height}{height in pixels of the graph to produce}
+
+\item{...}{currently not used}
 }
 \value{
 Two graphs showing the distribution of the model deepness.
@@ -39,7 +41,7 @@ its deepness (therefore in a boosting model, all trees have the same shape).
 Moreover, the trees tend to reuse the same features.
 
 The function will project each tree on one, and keep for each position the 
-\code{features.keep} first features (based on Gain per feature measure).
+\code{features_keep} first features (based on Gain per feature measure).
 
 This function is inspired by this blog post:
 \url{https://wellecks.wordpress.com/2015/02/21/peering-into-the-black-box-visualizing-lambdamart/}
@@ -47,11 +49,11 @@ This function is inspired by this blog post:
 \examples{
 data(agaricus.train, package='xgboost')
 
-bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max.depth = 15,
+bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max_depth = 15,
-                 eta = 1, nthread = 2, nround = 30, objective = "binary:logistic",
+                 eta = 1, nthread = 2, nrounds = 30, objective = "binary:logistic",
                  min_child_weight = 50)
 
-p <- xgb.plot.multi.trees(model = bst, feature_names = agaricus.train$data@Dimnames[[2]], features.keep = 3)
+p <- xgb.plot.multi.trees(model = bst, feature_names = colnames(agaricus.train$data), features_keep = 3)
 print(p)
 
 }

R-package/man/xgb.plot.tree.Rd

@@ -5,7 +5,7 @@
 \title{Plot a boosted tree model}
 \usage{
 xgb.plot.tree(feature_names = NULL, model = NULL, n_first_tree = NULL,
-  plot.width = NULL, plot.height = NULL)
+  plot_width = NULL, plot_height = NULL, ...)
 }
 \arguments{
 \item{feature_names}{names of each feature as a \code{character} vector. Can be extracted from a sparse matrix (see example). If model dump already contains feature names, this argument should be \code{NULL}.}
@@ -14,9 +14,11 @@ xgb.plot.tree(feature_names = NULL, model = NULL, n_first_tree = NULL,
 
 \item{n_first_tree}{limit the plot to the n first trees. If \code{NULL}, all trees of the model are plotted. Performance can be low for huge models.}
 
-\item{plot.width}{the width of the diagram in pixels.}
+\item{plot_width}{the width of the diagram in pixels.}
 
-\item{plot.height}{the height of the diagram in pixels.}
+\item{plot_height}{the height of the diagram in pixels.}
+
+\item{...}{currently not used.}
 }
 \value{
 A \code{DiagrammeR} of the model.
@@ -38,11 +40,10 @@ The function uses \href{http://www.graphviz.org/}{GraphViz} library for that pur
 \examples{
 data(agaricus.train, package='xgboost')
 
-bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max.depth = 2, 
+bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max_depth = 2, 
-               eta = 1, nthread = 2, nround = 2,objective = "binary:logistic")
+               eta = 1, nthread = 2, nrounds = 2,objective = "binary:logistic")
 
-# agaricus.train$data@Dimnames[[2]] represents the column names of the sparse matrix.
+xgb.plot.tree(feature_names = colnames(agaricus.train$data), model = bst)
-xgb.plot.tree(feature_names = agaricus.train$data@Dimnames[[2]], model = bst)
 
 }
 

R-package/man/xgb.save.Rd

@@ -9,7 +9,7 @@ xgb.save(model, fname)
 \arguments{
 \item{model}{the model object.}
 
-\item{fname}{the name of the binary file.}
+\item{fname}{the name of the file to write.}
 }
 \description{
 Save xgboost model from xgboost or xgb.train
@@ -19,8 +19,8 @@ data(agaricus.train, package='xgboost')
 data(agaricus.test, package='xgboost')
 train <- agaricus.train
 test <- agaricus.test
-bst <- xgboost(data = train$data, label = train$label, max.depth = 2, 
+bst <- xgboost(data = train$data, label = train$label, max_depth = 2, 
-               eta = 1, nthread = 2, nround = 2,objective = "binary:logistic")
+               eta = 1, nthread = 2, nrounds = 2,objective = "binary:logistic")
 xgb.save(bst, 'xgb.model')
 bst <- xgb.load('xgb.model')
 pred <- predict(bst, test$data)

R-package/man/xgb.save.raw.Rd

@@ -18,10 +18,11 @@ data(agaricus.train, package='xgboost')
 data(agaricus.test, package='xgboost')
 train <- agaricus.train
 test <- agaricus.test
-bst <- xgboost(data = train$data, label = train$label, max.depth = 2, 
+bst <- xgboost(data = train$data, label = train$label, max_depth = 2, 
-               eta = 1, nthread = 2, nround = 2,objective = "binary:logistic")
+               eta = 1, nthread = 2, nrounds = 2,objective = "binary:logistic")
 raw <- xgb.save.raw(bst)
 bst <- xgb.load(raw)
 pred <- predict(bst, test$data)
+
 }
 

R-package/man/xgb.train.Rd

@@ -6,13 +6,13 @@
 \title{eXtreme Gradient Boosting Training}
 \usage{
 xgb.train(params = list(), data, nrounds, watchlist = list(), obj = NULL,
-  feval = NULL, verbose = 1, print.every.n = 1L,
+  feval = NULL, verbose = 1, print_every_n = 1L,
-  early.stop.round = NULL, maximize = NULL, save_period = NULL,
+  early_stopping_rounds = NULL, maximize = NULL, save_period = NULL,
   save_name = "xgboost.model", xgb_model = NULL, callbacks = list(), ...)
 
 xgboost(data = NULL, label = NULL, missing = NA, weight = NULL,
-  params = list(), nrounds, verbose = 1, print.every.n = 1L,
+  params = list(), nrounds, verbose = 1, print_every_n = 1L,
-  early.stop.round = NULL, maximize = NULL, save_period = 0,
+  early_stopping_rounds = NULL, maximize = NULL, save_period = 0,
   save_name = "xgboost.model", xgb_model = NULL, callbacks = list(), ...)
 }
 \arguments{
@@ -59,8 +59,8 @@ xgboost(data = NULL, label = NULL, missing = NA, weight = NULL,
     \item \code{binary:logistic} logistic regression for binary classification. Output probability.
     \item \code{binary:logitraw} logistic regression for binary classification, output score before logistic transformation.
     \item \code{num_class} set the number of classes. To use only with multiclass objectives.
-    \item \code{multi:softmax} set xgboost to do multiclass classification using the softmax objective. Class is represented by a number and should be from 0 to \code{num_class}.
+    \item \code{multi:softmax} set xgboost to do multiclass classification using the softmax objective. Class is represented by a number and should be from 0 to \code{num_class - 1}.
-    \item \code{multi:softprob} same as softmax, but output a vector of ndata * nclass, which can be further reshaped to ndata, nclass matrix. The result contains predicted probabilities of each data point belonging to each class.
+    \item \code{multi:softprob} same as softmax, but prediction outputs a vector of ndata * nclass elements, which can be further reshaped to ndata, nclass matrix. The result contains predicted probabilities of each data point belonging to each class.
     \item \code{rank:pairwise} set xgboost to do ranking task by minimizing the pairwise loss.
   }
   \item \code{base_score} the initial prediction score of all instances, global bias. Default: 0.5
@@ -79,51 +79,78 @@ watchlist=list(validation1=mat1, validation2=mat2) to watch
 the performance of each round's model on mat1 and mat2}
 
 \item{obj}{customized objective function. Returns gradient and second order 
-gradient with given prediction and dtrain,}
+gradient with given prediction and dtrain.}
 
 \item{feval}{custimized evaluation function. Returns 
 \code{list(metric='metric-name', value='metric-value')} with given 
-prediction and dtrain,}
+prediction and dtrain.}
 
 \item{verbose}{If 0, xgboost will stay silent. If 1, xgboost will print 
-information of performance. If 2, xgboost will print information of both}
+information of performance. If 2, xgboost will print some additional information.
+Setting \code{verbose > 0} automatically engages the \code{\link{cb.evaluation.log}} and 
+\code{\link{cb.print.evaluation}} callback functions.}
 
-\item{print.every.n}{Print every N progress messages when \code{verbose>0}.
+\item{print_every_n}{Print each n-th iteration evaluation messages when \code{verbose>0}.
-Default is 1 which means all messages are printed.}
+Default is 1 which means all messages are printed. This parameter is passed to the 
+\code{\link{cb.print.evaluation}} callback.}
 
-\item{early.stop.round}{If \code{NULL}, the early stopping function is not triggered. 
+\item{early_stopping_rounds}{If \code{NULL}, the early stopping function is not triggered. 
 If set to an integer \code{k}, training with a validation set will stop if the performance 
-keeps getting worse consecutively for \code{k} rounds.}
+doesn't improve for \code{k} rounds.
+Setting this parameter engages the \code{\link{cb.early.stop}} callback.}
 
-\item{maximize}{If \code{feval} and \code{early.stop.round} are set, 
+\item{maximize}{If \code{feval} and \code{early_stopping_rounds} are set,
-then \code{maximize} must be set as well.
+then this parameter must be set as well.
-\code{maximize=TRUE} means the larger the evaluation score the better.}
+When it is \code{TRUE}, it means the larger the evaluation score the better.
+This parameter is passed to the \code{\link{cb.early.stop}} callback.}
 
-\item{save_period}{save the model to the disk after every \code{save_period} rounds, 0 means save at the end.}
+\item{save_period}{when it is non-NULL, model is saved to disk after every \code{save_period} rounds,
+0 means save at the end. The saving is handled by the \code{\link{cb.save.model}} callback.}
 
 \item{save_name}{the name or path for periodically saved model file.}
 
-\item{xgb_model}{the previously built model to continue the trainig from. 
+\item{xgb_model}{a previously built model to continue the trainig from.
 Could be either an object of class \code{xgb.Booster}, or its raw data, or the name of a 
 file with a previously saved model.}
 
 \item{callbacks}{a list of callback functions to perform various task during boosting.
-See \code{\link{callbacks}}. Some of the callbacks are currently automatically 
+See \code{\link{callbacks}}. Some of the callbacks are automatically created depending on the 
-created when specific parameters are set.}
+parameters' values. User can provide either existing or their own callback methods in order 
+to customize the training process.}
 
 \item{...}{other parameters to pass to \code{params}.}
 
-\item{label}{the response variable. User should not set this field,
+\item{label}{vector of response values. Should not be provided when data is 
-if data is local data file or \code{xgb.DMatrix}.}
+a local data file name or an \code{xgb.DMatrix}.}
 
 \item{missing}{by default is set to NA, which means that NA values should be considered as 'missing'
 by the algorithm. Sometimes, 0 or other extreme value might be used to represent missing values.
-This parameter is only used when input is dense matrix,}
+This parameter is only used when input is a dense matrix.}
 
 \item{weight}{a vector indicating the weight for each row of the input.}
 }
 \value{
-TODO
+An object of class \code{xgb.Booster} with the following elements:
+\itemize{
+  \item \code{handle} a handle (pointer) to the xgboost model in memory.
+  \item \code{raw} a cached memory dump of the xgboost model saved as R's \code{raw} type.
+  \item \code{niter} number of boosting iterations.
+  \item \code{evaluation_log} evaluation history storead as a \code{data.table} with the
+        first column corresponding to iteration number and the rest corresponding to evaluation
+        metrics' values. It is created by the \code{\link{cb.evaluation.log}} callback.
+  \item \code{call} a function call.
+  \item \code{params} parameters that were passed to the xgboost library. Note that it does not 
+        capture parameters changed by the \code{\link{cb.reset.parameters}} callback.
+  \item \code{callbacks} callback functions that were either automatically assigned or 
+        explicitely passed.
+  \item \code{best_iteration} iteration number with the best evaluation metric value
+        (only available with early stopping).
+  \item \code{best_ntreelimit} the \code{ntreelimit} value corresponding to the best iteration, 
+        which could further be used in \code{predict} method
+        (only available with early stopping).
+  \item \code{best_score} the best evaluation metric value during early stopping.
+        (only available with early stopping).
+}
 }
 \description{
 \code{xgb.train} is an advanced interface for training an xgboost model. The \code{xgboost} function provides a simpler interface.
@@ -147,21 +174,21 @@ The folloiwing is the list of built-in metrics for which Xgboost provides optimi
      \item \code{rmse} root mean square error. \url{http://en.wikipedia.org/wiki/Root_mean_square_error}
      \item \code{logloss} negative log-likelihood. \url{http://en.wikipedia.org/wiki/Log-likelihood}
      \item \code{mlogloss} multiclass logloss. \url{https://www.kaggle.com/wiki/MultiClassLogLoss}
-     \item \code{error} Binary classification error rate. It is calculated as \code{(wrong cases) / (all cases)}.
+     \item \code{error} Binary classification error rate. It is calculated as \code{(# wrong cases) / (# all cases)}.
            By default, it uses the 0.5 threshold for predicted values to define negative and positive instances.
            Different threshold (e.g., 0.) could be specified as "error@0."
-     \item \code{merror} Multiclass classification error rate. It is calculated as \code{(wrong cases) / (all cases)}.
+     \item \code{merror} Multiclass classification error rate. It is calculated as \code{(# wrong cases) / (# all cases)}.
      \item \code{auc} Area under the curve. \url{http://en.wikipedia.org/wiki/Receiver_operating_characteristic#'Area_under_curve} for ranking evaluation.
      \item \code{ndcg} Normalized Discounted Cumulative Gain (for ranking task). \url{http://en.wikipedia.org/wiki/NDCG}
   }
 
 The following callbacks are automatically created when certain parameters are set:
 \itemize{
-  \item \code{cb.print_evaluation} is turned on when \code{verbose > 0};
+  \item \code{cb.print.evaluation} is turned on when \code{verbose > 0};
-        and the \code{print.every.n} parameter is passed to it.
+        and the \code{print_every_n} parameter is passed to it.
-  \item \code{cb.log_evaluation} is on when \code{verbose > 0} and \code{watchlist} is present.
+  \item \code{cb.evaluation.log} is on when \code{verbose > 0} and \code{watchlist} is present.
-  \item \code{cb.early_stop}: when \code{early.stop.round} is set.
+  \item \code{cb.early.stop}: when \code{early_stopping_rounds} is set.
-  \item \code{cb.save_model}: when \code{save_period > 0} is set.
+  \item \code{cb.save.model}: when \code{save_period > 0} is set.
 }
 }
 \examples{
@@ -173,8 +200,9 @@ dtest <- xgb.DMatrix(agaricus.test$data, label = agaricus.test$label)
 watchlist <- list(eval = dtest, train = dtrain)
 
 ## A simple xgb.train example:
-param <- list(max.depth = 2, eta = 1, silent = 1, objective="binary:logistic", eval_metric="auc")
+param <- list(max_depth = 2, eta = 1, silent = 1, 
-bst <- xgb.train(param, dtrain, nthread = 2, nround = 2, watchlist)
+              objective = "binary:logistic", eval_metric = "auc")
+bst <- xgb.train(param, dtrain, nthread = 2, nrounds = 2, watchlist)
 
 ## An xgb.train example where custom objective and evaluation metric are used:
 logregobj <- function(preds, dtrain) {
@@ -189,23 +217,29 @@ evalerror <- function(preds, dtrain) {
   err <- as.numeric(sum(labels != (preds > 0)))/length(labels)
   return(list(metric = "error", value = err))
 }
-bst <- xgb.train(param, dtrain, nthread = 2, nround = 2, watchlist)
+bst <- xgb.train(param, dtrain, nthread = 2, nrounds = 2, watchlist)
 
 ## An xgb.train example of using variable learning rates at each iteration:
 my_etas <- list(eta = c(0.5, 0.1))
-bst <- xgb.train(param, dtrain, nthread = 2, nround = 2, watchlist,
+bst <- xgb.train(param, dtrain, nthread = 2, nrounds = 2, watchlist,
-                 callbacks = list(cb.reset_parameters(my_etas)))
+                 callbacks = list(cb.reset.parameters(my_etas)))
 
-## Explicit use of the cb.log_evaluation callback allows to run 
+## Explicit use of the cb.evaluation.log callback allows to run 
 ## xgb.train silently but still store the evaluation results:
-bst <- xgb.train(param, dtrain, nthread = 2, nround = 2, watchlist,
+bst <- xgb.train(param, dtrain, nthread = 2, nrounds = 2, watchlist,
-                 verbose = 0, callbacks = list(cb.log_evaluation()))
+                 verbose = 0, callbacks = list(cb.evaluation.log()))
 print(bst$evaluation_log)
 
 ## An 'xgboost' interface example:
-bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, max.depth = 2, 
+bst <- xgboost(data = agaricus.train$data, label = agaricus.train$label, 
-               eta = 1, nthread = 2, nround = 2, objective = "binary:logistic")
+               max_depth = 2, eta = 1, nthread = 2, nrounds = 2, 
+               objective = "binary:logistic")
 pred <- predict(bst, agaricus.test$data)
 
 }
+\seealso{
+\code{\link{callbacks}},
+\code{\link{predict.xgb.Booster}},
+\code{\link{xgb.cv}}
+}
 

R-package/man/xgboost-deprecated.Rd

@@ -0,0 +1,17 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/utils.R
+\name{xgboost-deprecated}
+\alias{xgboost-deprecated}
+\title{Deprecation notices.}
+\description{
+At this time, some of the parameter names were changed in order to make the code style more uniform.
+The deprecated parameters would be removed in the next release.
+}
+\details{
+To see all the current deprecated and new parameters, check the \code{xgboost:::depr_par_lut} table.
+
+A deprecation warning is shown when any of the deprecated parameters is used in a call. 
+An additional warning is shown when there was a partial match to a deprecated parameter 
+(as R is able to partially match parameter names).
+}
+