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:

Public Member Functions
	~Learner () override
	virtual destructor

virtual void	Configure ()=0
	Configure Learner based on set parameters.

virtual void	UpdateOneIter (int iter, std::shared_ptr< DMatrix > train)=0
	update the model for one iteration With the specified objective function.

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.

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.

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.

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.

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.

virtual int32_t	BoostedRounds () const =0

virtual std::uint32_t	Groups () const =0
	Get the number of output groups from the model.

void	LoadModel (Json const &in) override=0
	load the model from a JSON object

void	SaveModel (Json *out) const override=0
	saves the model config to a JSON object

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.

virtual void	SetParam (const std::string &key, const std::string &value)=0
	Set parameter for booster.

virtual uint32_t	GetNumFeature () const =0
	Get the number of features of the booster.

virtual void	SetAttr (const std::string &key, const std::string &value)=0
	Set additional attribute to the Booster.

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.

virtual bool	DelAttr (const std::string &key)=0
	Delete an attribute from the booster.

virtual std::vector< std::string >	GetAttrNames () const =0
	Get a vector of attribute names from the booster.

virtual void	SetFeatureNames (std::vector< std::string > const &fn)=0
	Set the feature names for current booster.

virtual void	GetFeatureNames (std::vector< std::string > *fn) const =0
	Get the feature names for current booster.

virtual void	SetFeatureTypes (std::vector< std::string > const &ft)=0
	Set the feature types for current booster.

virtual void	GetFeatureTypes (std::vector< std::string > *ft) const =0
	Get the feature types for current booster.

virtual Learner *	Slice (bst_layer_t begin, bst_layer_t end, bst_layer_t step, bool *out_of_bound)=0
	Slice the model.

virtual std::vector< std::string >	DumpModel (const FeatureMap &fmap, bool with_stats, std::string format)=0
	dump the model in the requested format

virtual XGBAPIThreadLocalEntry &	GetThreadLocal () const =0

virtual Context const *	Ctx () const =0
	Return the context object of this Booster.

virtual const std::map< std::string, std::string > &	GetConfigurationArguments () const =0
	Get configuration arguments currently stored by the learner.

Public Member Functions inherited from xgboost::Configurable
virtual void	LoadConfig (Json const &in)=0
	Load configuration from JSON object.

virtual void	SaveConfig (Json *out) const =0
	Save configuration to JSON object.

Public Member Functions inherited from dmlc::Serializable
virtual	~Serializable ()
	virtual destructor

virtual void	Load (Stream *fi)=0
	load the model from a stream

virtual void	Save (Stream *fo) const =0
	saves the model to a stream

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

Protected Attributes
std::unique_ptr< ObjFunction >	obj_
	objective function

std::unique_ptr< GradientBooster >	gbm_
	The gradient booster used by the model.

std::vector< std::unique_ptr< Metric > >	metrics_
	The evaluation metrics used to evaluate the model.

Context	ctx_
	Training parameter.

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);
}

Member Function Documentation

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

Implemented in xgboost::LearnerImpl.

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

Implemented in xgboost::LearnerImpl.

◆ Configure()

virtual void xgboost::Learner::Configure ( )

pure virtual

Configure Learner based on set parameters.

Implemented in xgboost::LearnerConfiguration.

◆ Create()

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 Context const * xgboost::Learner::Ctx ( ) const

pure virtual

Return the context object of this Booster.

Implemented in xgboost::LearnerConfiguration.

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

Implemented in xgboost::LearnerConfiguration.

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

Implemented in xgboost::LearnerImpl.

◆ 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

Implemented in xgboost::LearnerImpl.

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

Implemented in xgboost::LearnerConfiguration.

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

Implemented in xgboost::LearnerConfiguration.

◆ 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

Implemented in xgboost::LearnerConfiguration, and xgboost::LearnerImpl.

◆ 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

Implemented in xgboost::LearnerConfiguration.

◆ 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

Implemented in xgboost::LearnerConfiguration.

◆ GetNumFeature()

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

pure virtual

Get the number of features of the booster.

Returns: number of features

Implemented in xgboost::LearnerConfiguration.

◆ Groups()

virtual std::uint32_t xgboost::Learner::Groups ( ) const

pure virtual

Get the number of output groups from the model.

Implemented in xgboost::LearnerImpl.

◆ 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_fmat	A proxy DMatrix that contains the data and related meta info.
	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.

Implemented in xgboost::LearnerImpl.

◆ LoadModel()

void xgboost::Learner::LoadModel ( Json const & in )

overridepure virtual

load the model from a JSON object

Parameters

in	JSON object where to load the model from

Implements xgboost::Model.

Implemented in xgboost::LearnerIO.

◆ 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

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

Implemented in xgboost::LearnerImpl.

◆ SaveModel()

void xgboost::Learner::SaveModel ( Json * out ) const

overridepure virtual

saves the model config to a JSON object

Parameters

out	JSON container where to save the model to

Implements xgboost::Model.

Implemented in xgboost::LearnerIO.

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

Implemented in xgboost::LearnerConfiguration.

◆ 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

Implemented in xgboost::LearnerConfiguration.

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

Implemented in xgboost::LearnerConfiguration.

◆ 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

Implemented in xgboost::LearnerConfiguration.

◆ SetParams()

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

pure virtual

Set multiple parameters at once.

Parameters

args	parameters.

Implemented in xgboost::LearnerConfiguration.

◆ 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

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

Returns: a sliced model.

Implemented in xgboost::LearnerImpl.

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

Implemented in xgboost::LearnerImpl.

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

External/xgboost/include/xgboost/learner.h
External/xgboost/src/learner.cc

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ BoostOneIter()

◆ CalcFeatureScore()

◆ Configure()

◆ Create()

◆ Ctx()

◆ DelAttr()

◆ DumpModel()

◆ EvalOneIter()

◆ GetAttr()

◆ GetAttrNames()

◆ GetConfigurationArguments()

◆ GetFeatureNames()

◆ GetFeatureTypes()

◆ GetNumFeature()

◆ Groups()

◆ InplacePredict()

◆ LoadModel()

◆ Predict()

◆ SaveModel()

◆ SetAttr()

◆ SetFeatureNames()

◆ SetFeatureTypes()

◆ SetParam()

◆ SetParams()

◆ Slice()

◆ UpdateOneIter()