R accessors for model attributes

R-package/man/xgb.attr.Rd

@@ -0,0 +1,53 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/xgb.Booster.R
+\name{xgb.attr}
+\alias{xgb.attr}
+\alias{xgb.attr<-}
+\title{Accessors for serializable attributes of a model.}
+\usage{
+xgb.attr(object, which)
+
+xgb.attr(object, which) <- value
+}
+\arguments{
+\item{object}{Object of class \code{xgb.Booster} or  \code{xgb.Booster.handle}.}
+
+\item{which}{a non-empty character string specifying which attribute is to be accessed.}
+
+\item{value}{a value of an attribute. Non-character values are converted to character.
+When length of a \code{value} vector is more than one, only the first element is used.}
+}
+\value{
+\code{xgb.attr} returns either a string value of an attribute 
+or \code{NULL} if an attribute wasn't stored in a model.
+}
+\description{
+These methods allow to manipulate key-value attribute strings of an xgboost model.
+}
+\details{
+Note that the xgboost model attributes are a separate concept from the attributes in R.
+Specifically, they refer to key-value strings that can be attached to an xgboost model
+and stored within the model's binary representation.
+In contrast, any R-attribute assigned to an R-object of \code{xgb.Booster} class
+would not be saved by \code{xgb.save}, since xgboost model is an external memory object
+and its serialization is handled extrnally.
+
+Also note that the attribute setter would usually work more efficiently for \code{xgb.Booster.handle}
+than for \code{xgb.Booster}, since only just a handle would need to be copied.
+}
+\examples{
+data(agaricus.train, package='xgboost')
+train <- agaricus.train
+
+bst <- xgboost(data = train$data, label = train$label, max.depth = 2,
+               eta = 1, nthread = 2, nround = 2, objective = "binary:logistic")
+
+xgb.attr(bst, "my_attribute") <- "my attribute value"
+print(xgb.attr(bst, "my_attribute"))
+
+xgb.save(bst, 'xgb.model')
+bst1 <- xgb.load('xgb.model')
+print(xgb.attr(bst1, "my_attribute"))
+
+}
+