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=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 Learner *	Create (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< 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...

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

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

◆ Configure() [1/2]

template<typename PairIter >

void xgboost::Learner::Configure	(	PairIter	begin,
		PairIter	end
	)

inline

set configuration from pair iterators.

Parameters

begin	The beginning iterator.
end	The end iterator.

Template Parameters

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

cfg	configurations 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_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()

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

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

◆ 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

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

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

◆ 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

inst	the instance you want to predict
output_margin	whether to only predict margin value instead of transformed prediction
out_preds	output vector to hold the predictions
ntree_limit	limit the number of trees used in prediction

◆ Save()

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

overridepure virtual

save model to stream.

Parameters

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

key	The key of the property.
value	The 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

iter	current iteration number
train	reference 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:

/workspace/include/xgboost/learner.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~Learner()

Member Function Documentation

◆ AllowLazyCheckPoint()

◆ BoostOneIter()

◆ Configure() [1/2]

◆ Configure() [2/2]

◆ Create()

◆ DelAttr()

◆ DumpModel()

◆ EvalOneIter()

◆ GetAttr()

◆ GetAttrNames()

◆ GetConfigurationArguments()

◆ InitModel()

◆ Load()

◆ Predict() [1/2]

◆ Predict() [2/2]

◆ Save()

◆ SetAttr()

◆ UpdateOneIter()

Member Data Documentation

◆ base_score_

◆ gbm_

◆ metrics_

◆ obj_