add documentation notes

R-package/R/getinfo.xgb.DMatrix.R

@@ -1,5 +1,21 @@
 setClass('xgb.DMatrix')
 
+#' Get information of an xgb.DMatrix object
+#' 
+#' Get information of an xgb.DMatrix object
+#' 
+#' @param object Object of class "xgb.DMatrix"
+#' @param name the name of the field to get
+#' 
+#' @section Value
+#' return a numerical vector.
+#' 
+#' @examples
+#' data(iris)
+#' iris[,5] <- as.numeric(iris[,5])
+#' dtrain <- xgb.DMatrix(as.matrix(iris[,1:4]), label=iris[,5])
+#' labels <- getinfo(dtest, "label")
+#' 
 getinfo <- function(object, ...){
     UseMethod("getinfo")
 }

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

@@ -1,7 +1,23 @@
-#' @export
 setClass("xgb.Booster")
 
-#' @export
+#' Predict method for eXtreme Gradient Boosting model
+#' 
+#' Predicted values based on xgboost model object.
+#' 
+#' @param object Object of class "xgb.Boost"
+#' @param newdata takes \code{matrix}, \code{dgCMatrix}, local data file or 
+#'   \code{xgb.DMatrix}. 
+#' @param outputmargin whether the prediction should be shown in the original
+#'   value or after the logit mapping
+#' 
+#' @section Value
+#' return a numerical vector.
+#' 
+#' @examples
+#' data(iris)
+#' bst <- xgboost(as.matrix(iris[,1:4]),as.numeric(iris[,5]), nrounds = 2)
+#' pred <- predict(bst, as.matrix(iris[,1:4]))
+#' 
 setMethod("predict", signature = "xgb.Booster", 
           definition = function(object, newdata, outputmargin = FALSE) {
   if (class(newdata) != "xgb.DMatrix") {

R-package/R/xgb.DMatrix.R

@@ -1,4 +1,21 @@
-# constructing DMatrix
+#' Contruct xgb.DMatrix object
+#' 
+#' Contruct xgb.DMatrix object from dense matrix, sparse matrix or local file.
+#' 
+#' @param data a \code{matrix} object, a \code{dgCMatrix} object or a character 
+#'   indicating the data file.
+#' @param info a list of information of the xgb.DMatrix object
+#' @param missing Sometime a data use 0 or other extreme value to represents
+#'   missing values.
+#' @param ... other information to pass to \code{info}.
+#' 
+#' @examples
+#' data(iris)
+#' iris[,5] <- as.numeric(iris[,5])
+#' dtrain <- xgb.DMatrix(as.matrix(iris[,1:4]), label=iris[,5])
+#' xgb.DMatrix.save(dtrain, 'iris.xgb.DMatrix')
+#' dtrain <- xgb.DMatrix('iris.xgb.DMatrix')
+#' 
 xgb.DMatrix <- function(data, info = list(), missing = 0, ...) {
   if (typeof(data) == "character") {
     handle <- .Call("XGDMatrixCreateFromFile_R", data, as.integer(FALSE), 

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

@@ -1,10 +1,23 @@
-# save model or DMatrix to file
-xgb.DMatrix.save <- function(handle, fname) {
+#' Save xgb.DMatrix object to binary file
+#' 
+#' Save xgb.DMatrix object to binary file
+#' 
+#' @param model the model object.
+#' @param fname the name of the binary file.
+#' 
+#' @examples
+#' data(iris)
+#' iris[,5] <- as.numeric(iris[,5])
+#' dtrain <- xgb.DMatrix(as.matrix(iris[,1:4]), label=iris[,5])
+#' xgb.DMatrix.save(dtrain, 'iris.xgb.DMatrix')
+#' dtrain <- xgb.DMatrix('iris.xgb.DMatrix')
+#' 
+xgb.DMatrix.save <- function(DMatrix, fname) {
   if (typeof(fname) != "character") {
     stop("xgb.save: fname must be character")
   }
-  if (class(handle) == "xgb.DMatrix") {
-    .Call("XGDMatrixSaveBinary_R", handle, fname, as.integer(FALSE), 
+  if (class(DMatrix) == "xgb.DMatrix") {
+    .Call("XGDMatrixSaveBinary_R", DMatrix, fname, as.integer(FALSE), 
           PACKAGE = "xgboost")
     return(TRUE)
   }

R-package/R/xgb.dump.R

@@ -1,11 +1,23 @@
-# dump model
-xgb.dump <- function(booster, fname, fmap = "") {
-  if (class(booster) != "xgb.Booster") {
+#' Save xgboost model to text file
+#' 
+#' Save a xgboost model to text file. Could be parsed later.
+#' 
+#' @param model the model object.
+#' @param fname the name of the binary file.
+#' @param fmap TODO(tqchen)
+#' 
+#' @examples
+#' data(iris)
+#' bst <- xgboost(as.matrix(iris[,1:4]),as.numeric(iris[,5]), nrounds = 2)
+#' xgb.dump(bst, 'iris.xgb.model.dump')
+#' 
+xgb.dump <- function(model, fname, fmap = "") {
+  if (class(model) != "xgb.Booster") {
     stop("xgb.dump: first argument must be type xgb.Booster")
   }
   if (typeof(fname) != "character") {
     stop("xgb.dump: second argument must be type character")
   }
-  .Call("XGBoosterDumpModel_R", booster, fname, fmap, PACKAGE = "xgboost")
+  .Call("XGBoosterDumpModel_R", model, fname, fmap, PACKAGE = "xgboost")
   return(TRUE)
 } 

R-package/R/xgb.load.R

@@ -1,3 +1,16 @@
+#' Load xgboost model from binary file
+#' 
+#' Load xgboost model from the binary model file
+#' 
+#' @param modelfile the name of the binary file.
+#' 
+#' @examples
+#' data(iris)
+#' bst <- xgboost(as.matrix(iris[,1:4]),as.numeric(iris[,5]), nrounds = 2)
+#' xgb.save(bst, 'iris.xgb.model')
+#' bst <- xgb.load('iris.xgb.model')
+#' pred <- predict(bst, as.matrix(iris[,1:4]))
+#' 
 xgb.load <- function(modelfile) {
   if (is.null(modelfile)) 
     stop("xgb.load: modelfile cannot be NULL")

R-package/R/xgb.save.R

@@ -1,10 +1,23 @@
-# save model or DMatrix to file
-xgb.save <- function(handle, fname) {
+#' Save xgboost model to binary file
+#' 
+#' Save xgboost model from xgboost or xgb.train
+#' 
+#' @param model the model object.
+#' @param fname the name of the binary file.
+#' 
+#' @examples
+#' data(iris)
+#' bst <- xgboost(as.matrix(iris[,1:4]),as.numeric(iris[,5]), nrounds = 2)
+#' xgb.save(bst, 'iris.xgb.model')
+#' bst <- xgb.load('iris.xgb.model')
+#' pred <- predict(bst, as.matrix(iris[,1:4]))
+#' 
+xgb.save <- function(model, fname) {
   if (typeof(fname) != "character") {
     stop("xgb.save: fname must be character")
   }
-  if (class(handle) == "xgb.Booster") {
-    .Call("XGBoosterSaveModel_R", handle, fname, PACKAGE = "xgboost")
+  if (class(model) == "xgb.Booster") {
+    .Call("XGBoosterSaveModel_R", model, fname, PACKAGE = "xgboost")
     return(TRUE)
   }
   stop("xgb.save: the input must be either xgb.DMatrix or xgb.Booster")

R-package/R/xgb.train.R

@@ -1,4 +1,53 @@
-# train a model using given parameters
+#' eXtreme Gradient Boosting Training
+#' 
+#' The training function of xgboost
+#' 
+#' @param params the list of parameters. See 
+#'   \url{https://github.com/tqchen/xgboost/wiki/Parameters} for 
+#'   further details.
+#' @param dtrain takes an \code{xgb.DMatrix} as the input.
+#' @param nrounds the max number of iterations
+#' @param watchlist what information should be printed when \code{verbose=1} or
+#'   \code{verbose=2}.
+#' @param obj customized objective function. Given prediction and dtrain, 
+#'   return gradient and second order gradient
+#' @param feval custimized evaluation function. Given prediction and dtrain,
+#'   return a \code{list(metric='metric-name', value='metric-value')}.
+#' @param ... other parameters to pass to \code{params}.
+#' 
+#' @details 
+#' This is the training function for xgboost.
+#' 
+#' Parallelization is automatically enabled under Linux/Windows. Mac users can 
+#' also enjoy this feature if compile this package with openmp.
+#' 
+#' This function only accepts an \code{xgb.DMatrix} object as the input, 
+#' therefore it is more flexible than \code{\link{xgboost}}.
+#' 
+#' @section Value
+#' return a \code{xgb.DMatrix} class object.
+#' 
+#' @examples
+#' data(iris)
+#' iris[,5] <- as.numeric(iris[,5])
+#' dtrain = xgb.DMatrix(as.matrix(iris[,1:4]), label=iris[,5])
+#' dtest = dtrain
+#' watchlist <- list(eval = dtest, train = dtrain)
+#' param <- list(max_depth = 2, eta = 1, silent = 1)
+#' logregobj <- function(preds, dtrain) {
+#'    labels <- getinfo(dtrain, "label")
+#'    preds <- 1/(1 + exp(-preds))
+#'    grad <- preds - labels
+#'    hess <- preds * (1 - preds)
+#'    return(list(grad = grad, hess = hess))
+#' }
+#' evalerror <- function(preds, dtrain) {
+#'   labels <- getinfo(dtrain, "label")
+#'   err <- as.numeric(sum(labels != (preds > 0)))/length(labels)
+#'   return(list(metric = "error", value = err))
+#' }
+#' bst <- xgb.train(param, dtrain, nround = 2, watchlist, logregobj, evalerror)
+#' 
 xgb.train <- function(params=list(), dtrain, nrounds, watchlist = list(), 
                       obj = NULL, feval = NULL, ...) {
   if (typeof(params) != "list") {

R-package/R/xgboost.R

@@ -1,4 +1,34 @@
-# Main function for xgboost-package
+#' eXtreme Gradient Boosting (Tree) library
+#' 
+#' A simple interface for xgboost in R
+#' 
+#' @param data takes \code{matrix}, \code{dgCMatrix}, local data file or 
+#'   \code{xgb.DMatrix}. 
+#' @param label the response variable. Not required if data is local data file 
+#'   or \code{xgb.DMatrix}. 
+#' @param params the list of parameters. See 
+#'   \url{https://github.com/tqchen/xgboost/wiki/Parameters} for 
+#'   further details.
+#' @param nrounds the max number of iterations
+#' @param verbose If 0, xgboost will stay silent. If 1, xgboost will print 
+#'   information of performance. If 2, xgboost will print information of both
+#'   performance and tree.
+#' @param ... other parameters to pass to \code{params}.
+#' 
+#' @details 
+#' This is the modeling function for xgboost.
+#' 
+#' Parallelization is automatically enabled under Linux/Windows. Mac users can 
+#' also enjoy this feature if compile this package with openmp.
+#' 
+#' @section Value
+#' return a \code{xgb.DMatrix} class object.
+#' 
+#' @examples
+#' data(iris)
+#' bst <- xgboost(as.matrix(iris[,1:4]),as.numeric(iris[,5]), nrounds = 2)
+#' pred <- predict(bst, as.matrix(iris[,1:4]))
+#' 
 xgboost <- function(data = NULL, label = NULL, params = list(), nrounds, 
                     verbose = 1, ...) {
   inClass <- class(data)