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 (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 Learner *	Slice (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 void	Reset ()=0
	Reset the booster object to release data caches used for training. More...

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

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

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

iter	current iteration number
train	reference to the data matrix.
in_gpair	The 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_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.

◆ 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

◆ 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

◆ 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

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

◆ 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

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

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

◆ Reset()

virtual void xgboost::Learner::Reset ( )

pure virtual

Reset the booster object to release data caches used for training.

◆ 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

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

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

fn	Input feature names

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

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

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

◆ 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

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

/home/docs/checkouts/readthedocs.org/user_builds/xgboost/checkouts/stable/include/xgboost/learner.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~Learner()

Member Function Documentation

◆ BoostedRounds()

◆ BoostOneIter()

◆ CalcFeatureScore()

◆ Configure()

◆ Create()

◆ Ctx()

◆ DelAttr()

◆ DumpModel()

◆ EvalOneIter()

◆ GetAttr()

◆ GetAttrNames()

◆ GetConfigurationArguments()

◆ GetFeatureNames()

◆ GetFeatureTypes()

◆ GetNumFeature()

◆ GetThreadLocal()

◆ Groups()

◆ InplacePredict()

◆ LoadModel() [1/2]

◆ LoadModel() [2/2]

◆ Predict()

◆ Reset()

◆ SaveModel() [1/2]

◆ SaveModel() [2/2]

◆ SetAttr()

◆ SetFeatureNames()

◆ SetFeatureTypes()

◆ SetParam()

◆ SetParams()

◆ Slice()

◆ UpdateOneIter()

Member Data Documentation

◆ ctx_

◆ gbm_

◆ metrics_

◆ obj_