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=default
 virtual destructor More...
 
template<typename PairIter >
void Configure (PairIter begin, PairIter end)
 set configuration from pair iterators. More...
 
virtual void Configure (const std::vector< std::pair< std::string, std::string > > &cfg)=0
 Set the configuration of gradient boosting. User must call configure once before InitModel and Training. More...
 
virtual void InitModel ()=0
 Initialize the model using the specified configurations via Configure. An model have to be either Loaded or initialized before Update/Predict/Save can be called. More...
 
void Load (dmlc::Stream *fi) override=0
 load model from stream More...
 
void Save (dmlc::Stream *fo) const override=0
 save model to stream. More...
 
virtual void UpdateOneIter (int iter, DMatrix *train)=0
 update the model for one iteration With the specified objective function. More...
 
virtual void BoostOneIter (int iter, 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< 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 (DMatrix *data, bool output_margin, HostDeviceVector< bst_float > *out_preds, unsigned ntree_limit=0, bool pred_leaf=false, bool pred_contribs=false, bool approx_contribs=false, bool pred_interactions=false) const =0
 get prediction given the model. More...
 
virtual void SetAttr (const std::string &key, const std::string &value)=0
 Set additional attribute to the Booster. The property will be saved along 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
 
std::vector< std::string > DumpModel (const FeatureMap &fmap, bool with_stats, std::string format) const
 dump the model in the requested format More...
 
void Predict (const SparsePage::Inst &inst, bool output_margin, HostDeviceVector< bst_float > *out_preds, unsigned ntree_limit=0) const
 online prediction function, predict score for one instance at a time NOTE: use the batch prediction interface if possible, batch prediction is usually more efficient than online prediction This function is NOT threadsafe, make sure you only call from one thread. More...
 
virtual const std::map< std::string, std::string > & GetConfigurationArguments () const =0
 Get configuration arguments currently stored by the learner. 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

bst_float base_score_
 internal base score of the model More...
 
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...
 

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 ( )
overridedefault

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,
DMatrix train,
HostDeviceVector< GradientPair > *  in_gpair 
)
pure virtual

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

Parameters
itercurrent iteration number
trainreference to the data matrix.
in_gpairThe input gradient statistics.

◆ Configure() [1/2]

template<typename PairIter >
void xgboost::Learner::Configure ( PairIter  begin,
PairIter  end 
)
inline

set configuration from pair iterators.

Parameters
beginThe beginning iterator.
endThe end iterator.
Template Parameters
PairIteriterator<std::pair<std::string, std::string> >

◆ Configure() [2/2]

virtual void xgboost::Learner::Configure ( const std::vector< std::pair< std::string, std::string > > &  cfg)
pure virtual

Set the configuration of gradient boosting. User must call configure once before InitModel and Training.

Parameters
cfgconfigurations on both training and model 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.

◆ 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()

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

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

◆ InitModel()

virtual void xgboost::Learner::InitModel ( )
pure virtual

Initialize the model using the specified configurations via Configure. An model have to be either Loaded or initialized before Update/Predict/Save can be called.

◆ Load()

void xgboost::Learner::Load ( dmlc::Stream *  fi)
overridepure virtual

load model from stream

Parameters
fiinput stream.

◆ Predict() [1/2]

virtual void xgboost::Learner::Predict ( DMatrix data,
bool  output_margin,
HostDeviceVector< bst_float > *  out_preds,
unsigned  ntree_limit = 0,
bool  pred_leaf = false,
bool  pred_contribs = false,
bool  approx_contribs = false,
bool  pred_interactions = false 
) const
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
ntree_limitlimit number of trees used for boosted tree predictor, when it equals 0, this means we are using all the trees
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

◆ Predict() [2/2]

void xgboost::Learner::Predict ( const SparsePage::Inst inst,
bool  output_margin,
HostDeviceVector< bst_float > *  out_preds,
unsigned  ntree_limit = 0 
) const
inline

online prediction function, predict score for one instance at a time NOTE: use the batch prediction interface if possible, batch prediction is usually more efficient than online prediction This function is NOT threadsafe, make sure you only call from one thread.

Parameters
instthe instance you want to predict
output_marginwhether to only predict margin value instead of transformed prediction
out_predsoutput vector to hold the predictions
ntree_limitlimit the number of trees used in prediction

◆ Save()

void xgboost::Learner::Save ( dmlc::Stream *  fo) const
overridepure virtual

save model to stream.

Parameters
fooutput stream

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

◆ UpdateOneIter()

virtual void xgboost::Learner::UpdateOneIter ( int  iter,
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

◆ base_score_

bst_float xgboost::Learner::base_score_
protected

internal base score of the model

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