xgboost

Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
xgboost::Learner Class Referenceabstract

Learner class that does training and prediction. This is the user facing module of xgboost training. The Load/Save function corresponds to the model used in python/R. More...

`#include <learner.h>`

Inheritance diagram for xgboost::Learner:
Collaboration diagram for xgboost::Learner:

## Public Member Functions
| ~Learner () override
| virtual destructor More...
virtual void | Configure ()=0
| Configure Learner based on set parameters. More...
virtual void | UpdateOneIter (int iter, std::shared_ptr< DMatrix > train)=0
| update the model for one iteration With the specified objective function. More...
virtual void | BoostOneIter (int iter, std::shared_ptr< DMatrix > train, HostDeviceVector< GradientPair > *in_gpair)=0
| Do customized gradient boosting with in_gpair. in_gair can be mutated after this call. More...
virtual std::string | EvalOneIter (int iter, const std::vector< std::shared_ptr< DMatrix >> &data_sets, const std::vector< std::string > &data_names)=0
| evaluate the model for specific iteration using the configured metrics. More...
virtual void | Predict (std::shared_ptr< DMatrix > data, bool output_margin, HostDeviceVector< bst_float > *out_preds, unsigned layer_begin, unsigned layer_end, bool training=false, bool pred_leaf=false, bool pred_contribs=false, bool approx_contribs=false, bool pred_interactions=false)=0
| get prediction given the model. More...
virtual void | InplacePredict (dmlc::any const &x, std::shared_ptr< DMatrix > p_m, PredictionType type, float missing, HostDeviceVector< bst_float > **out_preds, uint32_t layer_begin, uint32_t layer_end)=0
| Inplace prediction. More...
virtual void | CalcFeatureScore (std::string const &importance_type, common::Span< int32_t const > trees, std::vector< bst_feature_t > *features, std::vector< float > *scores)=0
| Calculate feature score. See doc in C API for outputs. More...
virtual int32_t | BoostedRounds () const =0
virtual uint32_t | Groups () const =0
void | LoadModel (Json const &in) override=0
| load the model from a JSON object More...
void | SaveModel (Json *out) const override=0
| saves the model config to a JSON object More...
virtual void | LoadModel (dmlc::Stream *fi)=0
virtual void | SaveModel (dmlc::Stream *fo) const =0
virtual void | SetParams (Args const &args)=0
| Set multiple parameters at once. More...
virtual void | SetParam (const std::string &key, const std::string &value)=0
| Set parameter for booster. More...
virtual uint32_t | GetNumFeature () const =0
| Get the number of features of the booster. More...
virtual void | SetAttr (const std::string &key, const std::string &value)=0
| Set additional attribute to the Booster. More...
virtual bool | GetAttr (const std::string &key, std::string *out) const =0
| Get attribute from the booster. The property will be saved along the booster. More...
virtual bool | DelAttr (const std::string &key)=0
| Delete an attribute from the booster. More...
virtual std::vector< std::string > | GetAttrNames () const =0
| Get a vector of attribute names from the booster. More...
virtual void | SetFeatureNames (std::vector< std::string > const &fn)=0
| Set the feature names for current booster. More...
virtual void | GetFeatureNames (std::vector< std::string > *fn) const =0
| Get the feature names for current booster. More...
virtual void | SetFeatureTypes (std::vector< std::string > const &ft)=0
| Set the feature types for current booster. More...
virtual void | GetFeatureTypes (std::vector< std::string > *ft) const =0
| Get the feature types for current booster. More...
bool | AllowLazyCheckPoint () const
virtual Learner * | Slice (int32_t begin_layer, int32_t end_layer, int32_t step, bool *out_of_bound)=0
| Slice the model. More...
virtual std::vector< std::string > | DumpModel (const FeatureMap &fmap, bool with_stats, std::string format)=0
| dump the model in the requested format More...
virtual XGBAPIThreadLocalEntry & | GetThreadLocal () const =0
virtual GenericParameter const * | Ctx () const =0
| Return the context object of this Booster. More...
virtual const std::map< std::string, std::string > & | GetConfigurationArguments () const =0
| Get configuration arguments currently stored by the learner. More...
Public Member Functions inherited from xgboost::Model
virtual | ~Model ()=default
Public Member Functions inherited from xgboost::Configurable
virtual | ~Configurable ()=default
virtual void | LoadConfig (Json const &in)=0
| Load configuration from JSON object. More...
virtual void | SaveConfig (Json *out) const =0
| Save configuration to JSON object. More...

## Static Public Member Functions
static Learner * | Create (const std::vector< std::shared_ptr< DMatrix > > &cache_data)
| Create a new instance of learner. More...

## Protected Attributes
std::unique_ptr< ObjFunction > | obj_
| objective function More...
std::unique_ptr< GradientBooster > | gbm_
| The gradient booster used by the model. More...
std::vector< std::unique_ptr< Metric > > | metrics_
| The evaluation metrics used to evaluate the model. More...
GenericParameter | generic_parameters_
| Training parameter. More...

## Detailed Description

Learner class that does training and prediction. This is the user facing module of xgboost training. The Load/Save function corresponds to the model used in python/R.

std::unique_ptr<Learner> learner(new Learner::Create(cache_mats));
learner.Configure(configs);
for (int iter = 0; iter < max_iter; ++iter) {
learner->UpdateOneIter(iter, train_mat);
LOG(INFO) << learner->EvalOneIter(iter, data_sets, data_names);
}

## Constructor & Destructor Documentation

## ◆ ~Learner()

xgboost::Learner::~Learner | ( |  | ) |
| override

virtual destructor

## Member Function Documentation

## ◆ AllowLazyCheckPoint()

bool xgboost::Learner::AllowLazyCheckPoint | ( |  | ) | const

Returns
  whether the model allow lazy checkpoint in rabit.

## ◆ BoostedRounds()

virtual int32_t xgboost::Learner::BoostedRounds | ( |  | ) | const
| pure virtual

## ◆ BoostOneIter()

virtual void xgboost::Learner::BoostOneIter | ( | int | iter,
|  | std::shared_ptr< DMatrix > | train,
|  | HostDeviceVector< GradientPair > * | in_gpair
| ) |  |
| pure virtual

Do customized gradient boosting with in_gpair. in_gair can be mutated after this call.

Parameters

  iter | current iteration number
  train | reference to the data matrix.
  in_gpair | The input gradient statistics.

## ◆ CalcFeatureScore()

virtual void xgboost::Learner::CalcFeatureScore | ( | std::string const & | importance_type,
|  | common::Span< int32_t const > | trees,
|  | std::vector< bst_feature_t > * | features,
|  | std::vector< float > * | scores
| ) |  |
| pure virtual

Calculate feature score. See doc in C API for outputs.

## ◆ Configure()

virtual void xgboost::Learner::Configure | ( |  | ) |
| pure virtual

Configure Learner based on set parameters.

## ◆ Create()

static Learner* xgboost::Learner::Create | ( | const std::vector< std::shared_ptr< DMatrix > > & | cache_data | ) |
| static

Create a new instance of learner.

Parameters

  cache_data | The matrix to cache the prediction.

Returns
  Created learner.

## ◆ Ctx()

virtual GenericParameter const* xgboost::Learner::Ctx | ( |  | ) | const
| pure virtual

Return the context object of this Booster.

## ◆ DelAttr()

virtual bool xgboost::Learner::DelAttr | ( | const std::string & | key | ) |
| pure virtual

Delete an attribute from the booster.

Parameters

  key | The key of the attribute.

Returns
  Whether the key was found among booster's attributes.

## ◆ DumpModel()

virtual std::vector<std::string> xgboost::Learner::DumpModel | ( | const FeatureMap & | fmap,
|  | bool | with_stats,
|  | std::string | format
| ) |  |
| pure virtual

dump the model in the requested format

Parameters

  fmap | feature map that may help give interpretations of feature
  with_stats | extra statistics while dumping model
  format | the format to dump the model in

Returns
  a vector of dump for boosters.

## ◆ EvalOneIter()

virtual std::string xgboost::Learner::EvalOneIter | ( | int | iter,
|  | const std::vector< std::shared_ptr< DMatrix >> & | data_sets,
|  | const std::vector< std::string > & | data_names
| ) |  |
| pure virtual

evaluate the model for specific iteration using the configured metrics.

Parameters

  iter | iteration number
  data_sets | datasets to be evaluated.
  data_names | name of each dataset

Returns
  a string corresponding to the evaluation result

## ◆ GetAttr()

virtual bool xgboost::Learner::GetAttr | ( | const std::string & | key,
|  | std::string * | out
| ) |  | const
| pure virtual

Get attribute from the booster. The property will be saved along the booster.

Parameters

  key | The key of the attribute.
  out | The output value.

Returns
  Whether the key exists among booster's attributes.

## ◆ GetAttrNames()

virtual std::vector<std::string> xgboost::Learner::GetAttrNames | ( |  | ) | const
| pure virtual

Get a vector of attribute names from the booster.

Returns
  vector of attribute name strings.

## ◆ GetConfigurationArguments()

virtual const std::map<std::string, std::string>& xgboost::Learner::GetConfigurationArguments | ( |  | ) | const
| pure virtual

Get configuration arguments currently stored by the learner.

Returns
  Key-value pairs representing configuration arguments

## ◆ GetFeatureNames()

virtual void xgboost::Learner::GetFeatureNames | ( | std::vector< std::string > * | fn | ) | const
| pure virtual

Get the feature names for current booster.

Parameters

  fn | Output feature names

## ◆ GetFeatureTypes()

virtual void xgboost::Learner::GetFeatureTypes | ( | std::vector< std::string > * | ft | ) | const
| pure virtual

Get the feature types for current booster.

Parameters

  fn | Output feature types

## ◆ GetNumFeature()

virtual uint32_t xgboost::Learner::GetNumFeature | ( |  | ) | const
| pure virtual

Get the number of features of the booster.

Returns
  number of features

## ◆ GetThreadLocal()

virtual XGBAPIThreadLocalEntry& xgboost::Learner::GetThreadLocal | ( |  | ) | const
| pure virtual

## ◆ Groups()

virtual uint32_t xgboost::Learner::Groups | ( |  | ) | const
| pure virtual

## ◆ InplacePredict()

virtual void xgboost::Learner::InplacePredict | ( | dmlc::any const & | x,
|  | std::shared_ptr< DMatrix > | p_m,
|  | PredictionType | type,
|  | float | missing,
|  | HostDeviceVector< bst_float > ** | out_preds,
|  | uint32_t | layer_begin,
|  | uint32_t | layer_end
| ) |  |
| pure virtual

Inplace prediction.

Parameters

  | x | A type erased data adapter.
  | p_m | An optional Proxy DMatrix object storing meta info like base margin. Can be nullptr.
  | type | Prediction type.
  | missing | Missing value in the data.
  [in,out] | out_preds | Pointer to output prediction vector.
  | layer_begin | Beginning of boosted tree layer used for prediction.
  | layer_end | End of booster layer. 0 means do not limit trees.

## ◆ LoadModel() [1/2]

virtual void xgboost::Learner::LoadModel | ( | dmlc::Stream * | fi | ) |
| pure virtual

## ◆ LoadModel() [2/2]

void xgboost::Learner::LoadModel | ( | Json const & | in | ) |
| override pure virtual

load the model from a JSON object

Parameters

  in | JSON object where to load the model from

Implements xgboost::Model.

## ◆ Predict()

virtual void xgboost::Learner::Predict | ( | std::shared_ptr< DMatrix > | data,
|  | bool | output_margin,
|  | HostDeviceVector< bst_float > * | out_preds,
|  | unsigned | layer_begin,
|  | unsigned | layer_end,
|  | bool | training = `false`,
|  | bool | pred_leaf = `false`,
|  | bool | pred_contribs = `false`,
|  | bool | approx_contribs = `false`,
|  | bool | pred_interactions = `false`
| ) |  |
| pure virtual

get prediction given the model.

Parameters

  data | input data
  output_margin | whether to only predict margin value instead of transformed prediction
  out_preds | output vector that stores the prediction
  layer_begin | Beginning of boosted tree layer used for prediction.
  layer_end | End of booster layer. 0 means do not limit trees.
  training | Whether the prediction result is used for training
  pred_leaf | whether to only predict the leaf index of each tree in a boosted tree predictor
  pred_contribs | whether to only predict the feature contributions
  approx_contribs | whether to approximate the feature contributions for speed
  pred_interactions | whether to compute the feature pair contributions

## ◆ SaveModel() [1/2]

virtual void xgboost::Learner::SaveModel | ( | dmlc::Stream * | fo | ) | const
| pure virtual

## ◆ SaveModel() [2/2]

void xgboost::Learner::SaveModel | ( | Json * | out | ) | const
| override pure virtual

saves the model config to a JSON object

Parameters

  out | JSON container where to save the model to

Implements xgboost::Model.

## ◆ SetAttr()

virtual void xgboost::Learner::SetAttr | ( | const std::string & | key,
|  | const std::string & | value
| ) |  |
| pure virtual

Set additional attribute to the Booster.

The property will be saved along the booster.

Parameters

  key | The key of the property.
  value | The value of the property.

## ◆ SetFeatureNames()

virtual void xgboost::Learner::SetFeatureNames | ( | std::vector< std::string > const & | fn | ) |
| pure virtual

Set the feature names for current booster.

Parameters

  fn | Input feature names

## ◆ SetFeatureTypes()

virtual void xgboost::Learner::SetFeatureTypes | ( | std::vector< std::string > const & | ft | ) |
| pure virtual

Set the feature types for current booster.

Parameters

  ft | Input feature types.

## ◆ SetParam()

virtual void xgboost::Learner::SetParam | ( | const std::string & | key,
|  | const std::string & | value
| ) |  |
| pure virtual

Set parameter for booster.

The property will NOT be saved along with booster

Parameters

  key | The key of parameter
  value | The value of parameter

## ◆ SetParams()

virtual void xgboost::Learner::SetParams | ( | Args const & | args | ) |
| pure virtual

Set multiple parameters at once.

Parameters

  args | parameters.

## ◆ Slice()

virtual Learner* xgboost::Learner::Slice | ( | int32_t | begin_layer,
|  | int32_t | end_layer,
|  | int32_t | step,
|  | bool * | out_of_bound
| ) |  |
| pure virtual

Slice the model.

See InplacePredict for layer parameters.

Parameters

  step | step size between slice.
  out_of_bound | Return true if end layer is out of bound.

Returns
  a sliced model.

## ◆ UpdateOneIter()

virtual void xgboost::Learner::UpdateOneIter | ( | int | iter,
|  | std::shared_ptr< DMatrix > | train
| ) |  |
| pure virtual

update the model for one iteration With the specified objective function.

Parameters

  iter | current iteration number
  train | reference to the data matrix.

## Member Data Documentation

## ◆ gbm_

std::unique_ptr<GradientBooster> xgboost::Learner::gbm_
| protected

The gradient booster used by the model.

## ◆ generic_parameters_

GenericParameter xgboost::Learner::generic_parameters_
| protected

Training parameter.

## ◆ metrics_

std::vector<std::unique_ptr<Metric> > xgboost::Learner::metrics_
| protected

The evaluation metrics used to evaluate the model.

## ◆ obj_

std::unique_ptr<ObjFunction> xgboost::Learner::obj_
| protected

objective function

The documentation for this class was generated from the following file:

- /home/runner/work/xgboost/xgboost/include/xgboost/learner.h

xgboost::Learner::Create
static Learner * Create(const std::vector< std::shared_ptr< DMatrix > > &cache_data)
Create a new instance of learner.