Struct Booster

pub struct Booster { /* private fields */ }

Core model in XGBoost, containing functions for training, evaluating and predicting.

Usually created through the train function, which creates and trains a Booster in a single call.

For more fine grained usage, can be created using new or new_with_cached_dmats, then trained by calling update or update_custom in a loop.

Implementations

impl Booster

pub fn new(params: &BoosterParameters) -> XGBResult<Self>

Create a new Booster model with given parameters.

This model can then be trained using calls to update/boost as appropriate.

The train function is often a more convenient way of constructing, training and evaluating a Booster in a single call.

pub fn new_with_cached_dmats( params: &BoosterParameters, dmats: &[&DMatrix], ) -> XGBResult<Self>

Create a new Booster model with given parameters and list of DMatrix to cache.

Cached DMatrix can sometimes be used internally by XGBoost to speed up certain operations.

pub fn save<P: AsRef<Path>>(&self, path: P) -> XGBResult<()>

Save this Booster as a binary file at given path.

pub fn load<P: AsRef<Path>>(path: P) -> XGBResult<Self>

Load a Booster from a binary file at given path.

pub fn load_buffer(bytes: &[u8]) -> XGBResult<Self>

Load a Booster directly from a buffer.

pub fn train(params: &TrainingParameters<'_>) -> XGBResult<Self>

Convenience function for creating/training a new Booster.

This does the following:

1. create a new Booster model with given parameters
2. train the model with given DMatrix
3. print out evaluation results for each training round
4. return trained Booster

• params - training parameters
• dtrain - matrix to train Booster with
• num_boost_round - number of training iterations
• eval_sets - list of datasets to evaluate after each boosting round

pub fn set_params(&mut self, p: &BoosterParameters) -> XGBResult<()>

Update this Booster’s parameters.

pub fn update(&mut self, dtrain: &DMatrix, iteration: i32) -> XGBResult<()>

Update this model by training it for one round with given training matrix.

Uses XGBoost’s objective function that was specificed in this Booster’s learning objective parameters.

• dtrain - matrix to train the model with for a single iteration
• iteration - current iteration number

pub fn update_custom( &mut self, dtrain: &DMatrix, objective_fn: fn(&[f32], &DMatrix) -> (Vec<f32>, Vec<f32>), ) -> XGBResult<()>

Update this model by training it for one round with a custom objective function.

pub fn evaluate(&self, dmat: &DMatrix) -> XGBResult<HashMap<String, f32>>

Evaluate given matrix against this model using metrics defined in this model’s parameters.

See parameter::learning::EvaluationMetric for a full list.

Returns a map of evaluation metric name to score.

pub fn get_attribute(&self, key: &str) -> XGBResult<Option<String>>

Get a string attribute that was previously set for this model.

pub fn set_attribute(&mut self, key: &str, value: &str) -> XGBResult<()>

Store a string attribute in this model with given key.

pub fn get_attribute_names(&self) -> XGBResult<Vec<String>>

Get names of all attributes stored in this model. Values can then be fetched with calls to get_attribute.

pub fn predict(&self, dmat: &DMatrix) -> XGBResult<Vec<f32>>

Predict results for given data.

Returns an array containing one entry per row in the given data.

pub fn predict_margin(&self, dmat: &DMatrix) -> XGBResult<Vec<f32>>

Predict margin for given data.

Returns an array containing one entry per row in the given data.

pub fn predict_leaf( &self, dmat: &DMatrix, ) -> XGBResult<(Vec<f32>, (usize, usize))>

Get predicted leaf index for each sample in given data.

Returns an array of shape (number of samples, number of trees) as tuple of (data, num_rows).

Note: the leaf index of a tree is unique per tree, so e.g. leaf 1 could be found in both tree 1 and tree 0.

pub fn predict_contributions( &self, dmat: &DMatrix, ) -> XGBResult<(Vec<f32>, (usize, usize))>

Get feature contributions (SHAP values) for each prediction.

The sum of all feature contributions is equal to the run untransformed margin value of the prediction.

Returns an array of shape (number of samples, number of features + 1) as a tuple of (data, num_rows). The final column contains the bias term.

pub fn predict_interactions( &self, dmat: &DMatrix, ) -> XGBResult<(Vec<f32>, (usize, usize, usize))>

Get SHAP interaction values for each pair of features for each prediction.

The sum of each row (or column) of the interaction values equals the corresponding SHAP value (from predict_contributions), and the sum of the entire matrix equals the raw untransformed margin value of the prediction.

Returns an array of shape (number of samples, number of features + 1, number of features + 1). The final row and column contain the bias terms.

pub fn dump_model( &self, with_statistics: bool, feature_map: Option<&FeatureMap>, ) -> XGBResult<String>

Get a dump of this model as a string.

• with_statistics - whether to include statistics in output dump
• feature_map - if given, map feature IDs to feature names from given map

Trait Implementations

impl Drop for Booster

fn drop(&mut self)

Executes the destructor for this type.