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 ntree_limit=0, 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::string const &type, float missing, HostDeviceVector< bst_float > **out_preds, uint32_t layer_begin=0, uint32_t layer_end=0)=0
| Inplace prediction. More...
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 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...
bool | AllowLazyCheckPoint () const
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 & | GetGenericParameter () const =0
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.

## ◆ 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.

## ◆ 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.

## ◆ 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

## ◆ GetGenericParameter()

virtual GenericParameter const& xgboost::Learner::GetGenericParameter | ( |  | ) | const
| pure virtual

## ◆ GetThreadLocal()

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

## ◆ InplacePredict()

virtual void xgboost::Learner::InplacePredict | ( | dmlc::any const & | x,
|  | std::string const & | type,
|  | float | missing,
|  | HostDeviceVector< bst_float > ** | out_preds,
|  | uint32_t | layer_begin = `0`,
|  | uint32_t | layer_end = `0`
| ) |  |
| pure virtual

Inplace prediction.

Parameters

  | x | A type erased data adapter.
  | type | Prediction type.
  | missing | Missing value in the data.
  [in,out] | out_preds | Pointer to output prediction vector.
  | layer_begin | (Optional) Begining of boosted tree layer used for prediction.
  | layer_end | (Optional) End of booster layer. 0 means do not limit trees.

## ◆ LoadModel() [1/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.

## ◆ LoadModel() [2/2]

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

## ◆ Predict()

virtual void xgboost::Learner::Predict | ( | std::shared_ptr< DMatrix > | data,
|  | bool | output_margin,
|  | HostDeviceVector< bst_float > * | out_preds,
|  | unsigned | ntree_limit = `0`,
|  | 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
  ntree_limit | limit number of trees used for boosted tree predictor, when it equals 0, this means we are using all the 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]

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.

## ◆ SaveModel() [2/2]

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

## ◆ 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.

## ◆ 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.

## ◆ 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:

- /workspace/include/xgboost/learner.h