convert S4 to S3; add some extra methods to DMatrix

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

@@ -0,0 +1,29 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/xgb.DMatrix.R
+\name{dim.xgb.DMatrix}
+\alias{dim.xgb.DMatrix}
+\title{Dimensions of xgb.DMatrix}
+\usage{
+\method{dim}{xgb.DMatrix}(x)
+}
+\arguments{
+\item{x}{Object of class \code{xgb.DMatrix}}
+}
+\description{
+Returns a vector of numbers of rows and of columns in an \code{xgb.DMatrix}.
+}
+\details{
+Note: since \code{nrow} and \code{ncol} internally use \code{dim}, they can also 
+be directly used with an \code{xgb.DMatrix} object.
+}
+\examples{
+data(agaricus.train, package='xgboost')
+train <- agaricus.train
+dtrain <- xgb.DMatrix(train$data, label=train$label)
+
+stopifnot(nrow(dtrain) == nrow(train$data))
+stopifnot(ncol(dtrain) == ncol(train$data))
+stopifnot(all(dim(dtrain) == dim(train$data)))
+
+}
+

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

@@ -0,0 +1,36 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/xgb.DMatrix.R
+\name{dimnames.xgb.DMatrix}
+\alias{dimnames.xgb.DMatrix}
+\alias{dimnames<-.xgb.DMatrix}
+\title{Handling of column names of \code{xgb.DMatrix}}
+\usage{
+\method{dimnames}{xgb.DMatrix}(x)
+
+\method{dimnames}{xgb.DMatrix}(x) <- value
+}
+\arguments{
+\item{x}{object of class \code{xgb.DMatrix}}
+
+\item{value}{a list of two elements: the first one is ignored
+and the second one is column names}
+}
+\description{
+Only column names are supported for \code{xgb.DMatrix}, thus setting of 
+row names would have no effect and returnten row names would be NULL.
+}
+\details{
+Generic \code{dimnames} methods are used by \code{colnames}.
+Since row names are irrelevant, it is recommended to use \code{colnames} directly.
+}
+\examples{
+data(agaricus.train, package='xgboost')
+train <- agaricus.train
+dtrain <- xgb.DMatrix(train$data, label=train$label)
+dimnames(dtrain)
+colnames(dtrain)
+colnames(dtrain) <- make.names(1:ncol(train$data))
+print(dtrain, verbose=TRUE)
+
+}
+

R-package/man/getinfo.Rd

@@ -1,27 +1,26 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/getinfo.xgb.DMatrix.R
-\docType{methods}
+% Please edit documentation in R/xgb.DMatrix.R
 \name{getinfo}
 \alias{getinfo}
-\alias{getinfo,xgb.DMatrix-method}
+\alias{getinfo.xgb.DMatrix}
 \title{Get information of an xgb.DMatrix object}
 \usage{
 getinfo(object, ...)
 
-\S4method{getinfo}{xgb.DMatrix}(object, name)
+\method{getinfo}{xgb.DMatrix}(object, name)
 }
 \arguments{
 \item{object}{Object of class \code{xgb.DMatrix}}
 
 \item{...}{other parameters}
 
-\item{name}{the name of the field to get}
+\item{name}{the name of the information field to get (see details)}
 }
 \description{
 Get information of an xgb.DMatrix object
 }
 \details{
-The information can be one of the following:
+The \code{name} field can be one of the following:
 
 \itemize{
     \item \code{label}: label Xgboost learn from ;
@@ -34,8 +33,10 @@ The information can be one of the following:
 data(agaricus.train, package='xgboost')
 train <- agaricus.train
 dtrain <- xgb.DMatrix(train$data, label=train$label)
+
 labels <- getinfo(dtrain, 'label')
 setinfo(dtrain, 'label', 1-labels)
+
 labels2 <- getinfo(dtrain, 'label')
 stopifnot(all(labels2 == 1-labels))
 }

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

@@ -0,0 +1,58 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/xgb.Booster.R
+\name{predict.xgb.Booster}
+\alias{predict.xgb.Booster}
+\alias{predict.xgb.Booster.handle}
+\title{Predict method for eXtreme Gradient Boosting model}
+\usage{
+\method{predict}{xgb.Booster}(object, newdata, missing = NA,
+  outputmargin = FALSE, ntreelimit = NULL, predleaf = 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 
+\code{xgb.DMatrix}.}
+
+\item{missing}{Missing is only used when input is dense matrix, pick a float 
+value that represents missing value. Sometime a data use 0 or other extreme value to represents missing values.}
+
+\item{outputmargin}{whether the prediction should be shown in the original
+value of sum of functions, when outputmargin=TRUE, the prediction is 
+untransformed margin value. In logistic regression, outputmargin=T will
+output value before logistic transformation.}
+
+\item{ntreelimit}{limit number of trees used in prediction, this parameter is
+only valid for gbtree, but not for gblinear. set it to be value bigger 
+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{...}{Parameters pass to \code{predict.xgb.Booster}}
+}
+\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 
+of trees but use only the first trees for prediction to avoid overfitting 
+(without having to train a new model with less trees).
+
+The option \code{predleaf} purpose is inspired from §3.1 of the paper 
+\code{Practical Lessons from Predicting Clicks on Ads at Facebook}.
+The idea is to use the model as a generator of new features which capture non linear link 
+from original features.
+}
+\examples{
+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, 
+               eta = 1, nthread = 2, nround = 2,objective = "binary:logistic")
+pred <- predict(bst, test$data)
+}
+

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

@@ -0,0 +1,18 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/xgb.DMatrix.R
+\name{print.xgb.DMatrix}
+\alias{print.xgb.DMatrix}
+\title{Print xgb.DMatrix}
+\usage{
+print.xgb.DMatrix(x, verbose = FALSE, ...)
+}
+\arguments{
+\item{x}{an xgb.DMatrix object}
+
+\item{verbose}{whether to print colnames (when present)}
+}
+\description{
+Print information about an xgb.DMatrix. 
+Currently is would display
+}
+

R-package/man/setinfo.Rd

@@ -1,14 +1,13 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/setinfo.xgb.DMatrix.R
-\docType{methods}
+% Please edit documentation in R/xgb.DMatrix.R
 \name{setinfo}
 \alias{setinfo}
-\alias{setinfo,xgb.DMatrix-method}
+\alias{setinfo.xgb.DMatrix}
 \title{Set information of an xgb.DMatrix object}
 \usage{
 setinfo(object, ...)
 
-\S4method{setinfo}{xgb.DMatrix}(object, name, info)
+\method{setinfo}{xgb.DMatrix}(object, name, info)
 }
 \arguments{
 \item{object}{Object of class "xgb.DMatrix"}
@@ -23,7 +22,7 @@ setinfo(object, ...)
 Set information of an xgb.DMatrix object
 }
 \details{
-It can be one of the following:
+The \code{name} field can be one of the following:
 
 \itemize{
     \item \code{label}: label Xgboost learn from ;
@@ -36,9 +35,10 @@ It can be one of the following:
 data(agaricus.train, package='xgboost')
 train <- agaricus.train
 dtrain <- xgb.DMatrix(train$data, label=train$label)
+
 labels <- getinfo(dtrain, 'label')
 setinfo(dtrain, 'label', 1-labels)
 labels2 <- getinfo(dtrain, 'label')
-stopifnot(all(labels2 == 1-labels))
+stopifnot(all.equal(labels2, 1-labels))
 }
 

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

@@ -0,0 +1,41 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/xgb.DMatrix.R
+\name{slice}
+\alias{[.xgb.DMatrix}
+\alias{slice}
+\alias{slice.xgb.DMatrix}
+\title{Get a new DMatrix containing the specified rows of
+orginal xgb.DMatrix object}
+\usage{
+slice(object, ...)
+
+\method{slice}{xgb.DMatrix}(object, idxset, ...)
+
+\method{[}{xgb.DMatrix}(object, idxset, colset = NULL)
+}
+\arguments{
+\item{object}{Object of class "xgb.DMatrix"}
+
+\item{...}{other parameters (currently not used)}
+
+\item{idxset}{a integer vector of indices of rows needed}
+
+\item{colset}{currently not used (columns subsetting is not available)}
+}
+\description{
+Get a new DMatrix containing the specified rows of
+orginal xgb.DMatrix object
+}
+\examples{
+data(agaricus.train, package='xgboost')
+train <- agaricus.train
+dtrain <- xgb.DMatrix(train$data, label=train$label)
+
+dsub <- slice(dtrain, 1:42)
+labels1 <- getinfo(dsub, 'label')
+dsub <- dtrain[1:42, ]
+labels2 <- getinfo(dsub, 'label')
+all.equal(labels1, labels2)
+
+}
+

R-package/man/xgb.DMatrix.Rd

@@ -7,8 +7,7 @@
 xgb.DMatrix(data, info = list(), missing = NA, ...)
 }
 \arguments{
-\item{data}{a \code{matrix} object, a \code{dgCMatrix} object or a character 
-indicating the data file.}
+\item{data}{a \code{matrix} object, a \code{dgCMatrix} object or a character representing a filename}
 
 \item{info}{a list of information of the xgb.DMatrix object}
 
@@ -18,7 +17,8 @@ value that represents missing value. Sometime a data use 0 or other extreme valu
 \item{...}{other information to pass to \code{info}.}
 }
 \description{
-Contruct xgb.DMatrix object from dense matrix, sparse matrix or local file.
+Contruct xgb.DMatrix object from dense matrix, sparse matrix 
+or local file (that is a previously saved \code{xgb.DMatrix}).
 }
 \examples{
 data(agaricus.train, package='xgboost')