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:
Inheritance graph
Collaboration diagram for xgboost::Learner:
Collaboration graph

Public Member Functions

 ~Learner () override
 virtual destructor More...
 
virtual void Configure ()=0
 Configure Learner based on set parameters. More...
 
virtual void UpdateOneIter (std::int32_t iter, std::shared_ptr< DMatrix > train)=0
 update the model for one iteration With the specified objective function. More...
 
virtual void BoostOneIter (std::int32_t iter, std::shared_ptr< DMatrix > train, linalg::Matrix< GradientPair > *in_gpair)=0
 Do customized gradient boosting with in_gpair. 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, bst_layer_t layer_begin, bst_layer_t 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 (std::shared_ptr< DMatrix > p_m, PredictionType type, float missing, HostDeviceVector< float > **out_preds, bst_layer_t layer_begin, bst_layer_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 std::uint32_t Groups () const =0
 Get the number of output groups from the model. 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 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...
 
virtual LearnerSlice (bst_layer_t begin, bst_layer_t end, bst_layer_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 Context 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 LearnerCreate (const std::vector< std::shared_ptr< DMatrix > > &cache_data)
 Create a new instance of learner. More...
 

Protected Attributes

std::unique_ptr< ObjFunctionobj_
 objective function More...
 
std::unique_ptr< GradientBoostergbm_
 The gradient booster used by the model. More...
 
std::vector< std::unique_ptr< Metric > > metrics_
 The evaluation metrics used to evaluate the model. More...
 
Context ctx_
 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);
}
static Learner * Create(const std::vector< std::shared_ptr< DMatrix > > &cache_data)
Create a new instance of learner.

Constructor & Destructor Documentation

◆ ~Learner()

xgboost::Learner::~Learner ( )
override

virtual destructor

Member Function Documentation

◆ BoostedRounds()

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

◆ BoostOneIter()

virtual void xgboost::Learner::BoostOneIter ( std::int32_t  iter,
std::shared_ptr< DMatrix train,
linalg::Matrix< GradientPair > *  in_gpair 
)
pure virtual

Do customized gradient boosting with in_gpair.

Note
in_gpair can be mutated after this call.
Parameters
itercurrent iteration number
trainreference to the data matrix.
in_gpairThe 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_dataThe matrix to cache the prediction.
Returns
Created learner.

◆ Ctx()

virtual Context 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
keyThe 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
fmapfeature map that may help give interpretations of feature
with_statsextra statistics while dumping model
formatthe 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
iteriteration number
data_setsdatasets to be evaluated.
data_namesname 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
keyThe key of the attribute.
outThe 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
fnOutput feature names

◆ GetFeatureTypes()

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

Get the feature types for current booster.

Parameters
fnOutput 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 std::uint32_t xgboost::Learner::Groups ( ) const
pure virtual

Get the number of output groups from the model.

◆ InplacePredict()

virtual void xgboost::Learner::InplacePredict ( std::shared_ptr< DMatrix p_m,
PredictionType  type,
float  missing,
HostDeviceVector< float > **  out_preds,
bst_layer_t  layer_begin,
bst_layer_t  layer_end 
)
pure virtual

Inplace prediction.

Parameters
p_fmatA proxy DMatrix that contains the data and related meta info.
typePrediction type.
missingMissing value in the data.
[in,out]out_predsPointer to output prediction vector.
layer_beginBeginning of boosted tree layer used for prediction.
layer_endEnd 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)
overridepure virtual

load the model from a JSON object

Parameters
inJSON 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,
bst_layer_t  layer_begin,
bst_layer_t  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
datainput data
output_marginwhether to only predict margin value instead of transformed prediction
out_predsoutput vector that stores the prediction
layer_beginBeginning of boosted tree layer used for prediction.
layer_endEnd of booster layer. 0 means do not limit trees.
trainingWhether the prediction result is used for training
pred_leafwhether to only predict the leaf index of each tree in a boosted tree predictor
pred_contribswhether to only predict the feature contributions
approx_contribswhether to approximate the feature contributions for speed
pred_interactionswhether 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
overridepure virtual

saves the model config to a JSON object

Parameters
outJSON 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
keyThe key of the property.
valueThe 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
fnInput feature names

◆ SetFeatureTypes()

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

Set the feature types for current booster.

Parameters
ftInput 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
keyThe key of parameter
valueThe value of parameter

◆ SetParams()

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

Set multiple parameters at once.

Parameters
argsparameters.

◆ Slice()

virtual Learner* xgboost::Learner::Slice ( bst_layer_t  begin,
bst_layer_t  end,
bst_layer_t  step,
bool *  out_of_bound 
)
pure virtual

Slice the model.

See InplacePredict for layer parameters.

Parameters
stepstep size between slice.
out_of_boundReturn true if end layer is out of bound.
Returns
a sliced model.

◆ UpdateOneIter()

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

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

Parameters
itercurrent iteration number
trainreference to the data matrix.

Member Data Documentation

◆ ctx_

Context xgboost::Learner::ctx_
protected

Training parameter.

◆ gbm_

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

The gradient booster used by the model.

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