67 lines
3.2 KiB
R
67 lines
3.2 KiB
R
% Generated by roxygen2: do not edit by hand
|
|
% Please edit documentation in R/utils.R
|
|
\name{a-compatibility-note-for-saveRDS-save}
|
|
\alias{a-compatibility-note-for-saveRDS-save}
|
|
\title{Do not use \code{\link[base]{saveRDS}} or \code{\link[base]{save}} for long-term archival of
|
|
models. Instead, use \code{\link{xgb.save}} or \code{\link{xgb.save.raw}}.}
|
|
\description{
|
|
It is a common practice to use the built-in \code{\link[base]{saveRDS}} function (or
|
|
\code{\link[base]{save}}) to persist R objects to the disk. While it is possible to persist
|
|
\code{xgb.Booster} objects using \code{\link[base]{saveRDS}}, it is not advisable to do so if
|
|
the model is to be accessed in the future. If you train a model with the current version of
|
|
XGBoost and persist it with \code{\link[base]{saveRDS}}, the model is not guaranteed to be
|
|
accessible in later releases of XGBoost. To ensure that your model can be accessed in future
|
|
releases of XGBoost, use \code{\link{xgb.save}} or \code{\link{xgb.save.raw}} instead.
|
|
}
|
|
\details{
|
|
Use \code{\link{xgb.save}} to save the XGBoost model as a stand-alone file. You may opt into
|
|
the JSON format by specifying the JSON extension. To read the model back, use
|
|
\code{\link{xgb.load}}.
|
|
|
|
Use \code{\link{xgb.save.raw}} to save the XGBoost model as a sequence (vector) of raw bytes
|
|
in a future-proof manner. Future releases of XGBoost will be able to read the raw bytes and
|
|
re-construct the corresponding model. To read the model back, use \code{\link{xgb.load.raw}}.
|
|
The \code{\link{xgb.save.raw}} function is useful if you'd like to persist the XGBoost model
|
|
as part of another R object.
|
|
|
|
Note: Do not use \code{\link{xgb.serialize}} to store models long-term. It persists not only the
|
|
model but also internal configurations and parameters, and its format is not stable across
|
|
multiple XGBoost versions. Use \code{\link{xgb.serialize}} only for checkpointing.
|
|
|
|
For more details and explanation about model persistence and archival, consult the page
|
|
\url{https://xgboost.readthedocs.io/en/latest/tutorials/saving_model.html}.
|
|
}
|
|
\examples{
|
|
data(agaricus.train, package='xgboost')
|
|
bst <- xgb.train(data = xgb.DMatrix(agaricus.train$data, label = agaricus.train$label),
|
|
max_depth = 2, eta = 1, nthread = 2, nrounds = 2,
|
|
objective = "binary:logistic")
|
|
|
|
# Save as a stand-alone file; load it with xgb.load()
|
|
fname <- file.path(tempdir(), "xgb_model.ubj")
|
|
xgb.save(bst, fname)
|
|
bst2 <- xgb.load(fname)
|
|
|
|
# Save as a stand-alone file (JSON); load it with xgb.load()
|
|
fname <- file.path(tempdir(), "xgb_model.json")
|
|
xgb.save(bst, fname)
|
|
bst2 <- xgb.load(fname)
|
|
|
|
# Save as a raw byte vector; load it with xgb.load.raw()
|
|
xgb_bytes <- xgb.save.raw(bst)
|
|
bst2 <- xgb.load.raw(xgb_bytes)
|
|
|
|
# Persist XGBoost model as part of another R object
|
|
obj <- list(xgb_model_bytes = xgb.save.raw(bst), description = "My first XGBoost model")
|
|
# Persist the R object. Here, saveRDS() is okay, since it doesn't persist
|
|
# xgb.Booster directly. What's being persisted is the future-proof byte representation
|
|
# as given by xgb.save.raw().
|
|
fname <- file.path(tempdir(), "my_object.Rds")
|
|
saveRDS(obj, fname)
|
|
# Read back the R object
|
|
obj2 <- readRDS(fname)
|
|
# Re-construct xgb.Booster object from the bytes
|
|
bst2 <- xgb.load.raw(obj2$xgb_model_bytes)
|
|
|
|
}
|