R: Accessors for serializable attributes of a model.

xgb.attr {xgboost} | R Documentation

## Accessors for serializable attributes of a model.

### Description

These methods allow to manipulate the key-value attribute strings of an xgboost model.

### Usage

    xgb.attr(object, name)

    xgb.attr(object, name) <- value

    xgb.attributes(object)

    xgb.attributes(object) <- value

### Arguments

`object` | Object of class `xgb.Booster` or `xgb.Booster.handle`.
`name` | a non-empty character string specifying which attribute is to be accessed.
`value` | a value of an attribute for `xgb.attr<-`; for `xgb.attributes<-` it's a list (or an object coercible to a list) with the names of attributes to set and the elements corresponding to attribute values. Non-character values are converted to character. When attribute value is not a scalar, only the first index is used. Use `NULL` to remove an attribute.

### Details

The primary purpose of xgboost model attributes is to store some meta-data about the model. Note that they are a separate concept from the object attributes in R. Specifically, they refer to key-value strings that can be attached to an xgboost model, stored together with the model's binary representation, and accessed later (from R or any other interface). In contrast, any R-attribute assigned to an R-object of `xgb.Booster` class would not be saved by `xgb.save` because an xgboost model is an external memory object and its serialization is handled externally. Also, setting an attribute that has the same name as one of xgboost's parameters wouldn't change the value of that parameter for a model. Use `xgb.parameters<-` to set or change model parameters.

The attribute setters would usually work more efficiently for `xgb.Booster.handle` than for `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 `xgb.Booster` object to the attribute setters, the raw model cache of an `xgb.Booster` object would not be automatically updated, and it would be user's responsibility to call `xgb.serialize` to update it.

The `xgb.attributes<-` setter either updates the existing or adds one or several attributes, but it doesn't delete the other existing attributes.

### Value

`xgb.attr` returns either a string value of an attribute or `NULL` if an attribute wasn't stored in a model.

`xgb.attributes` returns a list of all attribute stored in a model or `NULL` if a model has no stored attributes.

### Examples

    data(agaricus.train, package='xgboost')
    train <- agaricus.train

    bst <- xgboost(data = train$data, label = train$label, max_depth = 2,
                   eta = 1, nthread = 2, nrounds = 2, objective = "binary:logistic")

    xgb.attr(bst, "my_attribute") <- "my attribute value"
    print(xgb.attr(bst, "my_attribute"))
    xgb.attributes(bst) <- list(a = 123, b = "abc")

    xgb.save(bst, 'xgb.model')
    bst1 <- xgb.load('xgb.model')
    if (file.exists('xgb.model')) file.remove('xgb.model')
    print(xgb.attr(bst1, "my_attribute"))
    print(xgb.attributes(bst1))

    # deletion:
    xgb.attr(bst1, "my_attribute") <- NULL
    print(xgb.attributes(bst1))
    xgb.attributes(bst1) <- list(a = NULL, b = NULL)
    print(xgb.attributes(bst1))

[Package xgboost version 1.3.0.1 Index]