define regression tree to be the most common tree model. More...

#include <tree_model.h>

Inheritance diagram for xgboost::RegTree:

Collaboration diagram for xgboost::RegTree:

Classes
struct	CategoricalSplitMatrix
	CSR-like matrix for categorical splits. More...

struct	FVec
	dense feature vector that can be taken by RegTree and can be construct from sparse feature vector. More...

class	Node
	tree node More...

Public Types
using	SplitCondT = bst_float

Public Member Functions
void	ChangeToLeaf (int rid, bst_float value)
	change a non leaf node to a leaf node, delete its children More...

void	CollapseToLeaf (int rid, bst_float value)
	collapse a non leaf node to a leaf node, delete its children More...

	RegTree ()

	RegTree (bst_target_t n_targets, bst_feature_t n_features)
	Constructor that initializes the tree model with shape. More...

Node &	operator[] (int nid)
	get node given nid More...

const Node &	operator[] (int nid) const
	get node given nid More...

const std::vector< Node > &	GetNodes () const
	get const reference to nodes More...

const std::vector< RTreeNodeStat > &	GetStats () const
	get const reference to stats More...

RTreeNodeStat &	Stat (int nid)
	get node statistics given nid More...

const RTreeNodeStat &	Stat (int nid) const
	get node statistics given nid More...

void	Load (dmlc::Stream *fi)
	load model from stream More...

void	Save (dmlc::Stream *fo) const
	save model to stream More...

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

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

bool	operator== (const RegTree &b) const

template<typename Func >
void	WalkTree (Func func) const

bool	Equal (const RegTree &b) const
	Compares whether 2 trees are equal from a user's perspective. The equality compares only non-deleted nodes. More...

void	ExpandNode (bst_node_t nid, unsigned split_index, bst_float split_value, bool default_left, bst_float base_weight, bst_float left_leaf_weight, bst_float right_leaf_weight, bst_float loss_change, float sum_hess, float left_sum, float right_sum, bst_node_t leaf_right_child=kInvalidNodeId)
	Expands a leaf node into two additional leaf nodes. More...

void	ExpandNode (bst_node_t nidx, bst_feature_t split_index, float split_cond, bool default_left, linalg::VectorView< float const > base_weight, linalg::VectorView< float const > left_weight, linalg::VectorView< float const > right_weight)
	Expands a leaf node into two additional leaf nodes for a multi-target tree. More...

void	ExpandCategorical (bst_node_t nid, bst_feature_t split_index, common::Span< const uint32_t > split_cat, bool default_left, bst_float base_weight, bst_float left_leaf_weight, bst_float right_leaf_weight, bst_float loss_change, float sum_hess, float left_sum, float right_sum)
	Expands a leaf node with categories. More...

bool	HasCategoricalSplit () const
	Whether this tree has categorical split. More...

bool	IsMultiTarget () const
	Whether this is a multi-target tree. More...

bst_target_t	NumTargets () const
	The size of leaf weight. More...

auto	GetMultiTargetTree () const
	Get the underlying implementaiton of multi-target tree. More...

bst_feature_t	NumFeatures () const noexcept
	Get the number of features. More...

bst_node_t	NumNodes () const noexcept
	Get the total number of nodes including deleted ones in this tree. More...

bst_node_t	NumValidNodes () const noexcept
	Get the total number of valid nodes in this tree. More...

bst_node_t	NumExtraNodes () const noexcept
	number of extra nodes besides the root More...

bst_node_t	GetNumLeaves () const

bst_node_t	GetNumSplitNodes () const

std::int32_t	GetDepth (bst_node_t nid) const
	get current depth More...

void	SetLeaf (bst_node_t nidx, linalg::VectorView< float const > weight)
	Set the leaf weight for a multi-target tree. More...

int	MaxDepth (int nid) const
	get maximum depth More...

int	MaxDepth ()
	get maximum depth More...

void	CalculateContributionsApprox (const RegTree::FVec &feat, std::vector< float > mean_values, bst_float out_contribs) const
	calculate the approximate feature contributions for the given root More...

std::string	DumpModel (const FeatureMap &fmap, bool with_stats, std::string format) const
	dump the model in the requested format as a text string More...

FeatureType	NodeSplitType (bst_node_t nidx) const
	Get split type for a node. More...

std::vector< FeatureType > const &	GetSplitTypes () const
	Get split types for all nodes. More...

common::Span< uint32_t const >	GetSplitCategories () const

common::Span< uint32_t const >	NodeCats (bst_node_t nidx) const
	Get the bit storage for categories. More...

auto const &	GetSplitCategoriesPtr () const

CategoricalSplitMatrix	GetCategoriesMatrix () const

bst_feature_t	SplitIndex (bst_node_t nidx) const

float	SplitCond (bst_node_t nidx) const

bool	DefaultLeft (bst_node_t nidx) const

bool	IsRoot (bst_node_t nidx) const

bool	IsLeaf (bst_node_t nidx) const

bst_node_t	Parent (bst_node_t nidx) const

bst_node_t	LeftChild (bst_node_t nidx) const

bst_node_t	RightChild (bst_node_t nidx) const

bool	IsLeftChild (bst_node_t nidx) const

bst_node_t	Size () const

Public Member Functions inherited from xgboost::Model
virtual	~Model ()=default

Static Public Attributes
static constexpr bst_node_t	kInvalidNodeId {MultiTargetTree::InvalidNodeId()}

static constexpr uint32_t	kDeletedNodeMarker = std::numeric_limits<uint32_t>::max()

static constexpr bst_node_t	kRoot {0}

Detailed Description

define regression tree to be the most common tree model.

This is the data structure used in xgboost's major tree models.

Member Typedef Documentation

◆ SplitCondT

using xgboost::RegTree::SplitCondT = bst_float

Constructor & Destructor Documentation

◆ RegTree() [1/2]

xgboost::RegTree::RegTree ( )

inline

◆ RegTree() [2/2]

xgboost::RegTree::RegTree	(	bst_target_t	n_targets,
		bst_feature_t	n_features
	)

inlineexplicit

Constructor that initializes the tree model with shape.

Member Function Documentation

◆ CalculateContributionsApprox()

void xgboost::RegTree::CalculateContributionsApprox	(	const RegTree::FVec &	feat,
		std::vector< float > *	mean_values,
		bst_float *	out_contribs
	)		const

calculate the approximate feature contributions for the given root

Parameters

feat	dense feature vector, if the feature is missing the field is set to NaN
out_contribs	output vector to hold the contributions

◆ ChangeToLeaf()

void xgboost::RegTree::ChangeToLeaf	(	int	rid,
		bst_float	value
	)

inline

change a non leaf node to a leaf node, delete its children

Parameters

rid	node id of the node
value	new leaf value

◆ CollapseToLeaf()

void xgboost::RegTree::CollapseToLeaf	(	int	rid,
		bst_float	value
	)

inline

collapse a non leaf node to a leaf node, delete its children

Parameters

rid	node id of the node
value	new leaf value

◆ DefaultLeft()

bool xgboost::RegTree::DefaultLeft ( bst_node_t nidx ) const

inline

◆ DumpModel()

std::string xgboost::RegTree::DumpModel	(	const FeatureMap &	fmap,
		bool	with_stats,
		std::string	format
	)		const

dump the model in the requested format as a text string

Parameters

fmap	feature map that may help give interpretations of feature
with_stats	whether dump out statistics as well
format	the format to dump the model in

Returns: the string of dumped model

◆ Equal()

bool xgboost::RegTree::Equal ( const RegTree & b ) const

Compares whether 2 trees are equal from a user's perspective. The equality compares only non-deleted nodes.

Parameters

b	The other tree.

◆ ExpandCategorical()

void xgboost::RegTree::ExpandCategorical	(	bst_node_t	nid,
		bst_feature_t	split_index,
		common::Span< const uint32_t >	split_cat,
		bool	default_left,
		bst_float	base_weight,
		bst_float	left_leaf_weight,
		bst_float	right_leaf_weight,
		bst_float	loss_change,
		float	sum_hess,
		float	left_sum,
		float	right_sum
	)

Expands a leaf node with categories.

Parameters

nid	The node index to expand.
split_index	Feature index of the split.
split_cat	The bitset containing categories
default_left	True to default left.
base_weight	The base weight, before learning rate.
left_leaf_weight	The left leaf weight for prediction, modified by learning rate.
right_leaf_weight	The right leaf weight for prediction, modified by learning rate.
loss_change	The loss change.
sum_hess	The sum hess.
left_sum	The sum hess of left leaf.
right_sum	The sum hess of right leaf.

◆ ExpandNode() [1/2]

void xgboost::RegTree::ExpandNode	(	bst_node_t	nid,
		unsigned	split_index,
		bst_float	split_value,
		bool	default_left,
		bst_float	base_weight,
		bst_float	left_leaf_weight,
		bst_float	right_leaf_weight,
		bst_float	loss_change,
		float	sum_hess,
		float	left_sum,
		float	right_sum,
		bst_node_t	leaf_right_child = `kInvalidNodeId`
	)

Expands a leaf node into two additional leaf nodes.

Parameters

nid	The node index to expand.
split_index	Feature index of the split.
split_value	The split condition.
default_left	True to default left.
base_weight	The base weight, before learning rate.
left_leaf_weight	The left leaf weight for prediction, modified by learning rate.
right_leaf_weight	The right leaf weight for prediction, modified by learning rate.
loss_change	The loss change.
sum_hess	The sum hess.
left_sum	The sum hess of left leaf.
right_sum	The sum hess of right leaf.
leaf_right_child	The right child index of leaf, by default kInvalidNodeId, some updaters use the right child index of leaf as a marker

◆ ExpandNode() [2/2]

void xgboost::RegTree::ExpandNode	(	bst_node_t	nidx,
		bst_feature_t	split_index,
		float	split_cond,
		bool	default_left,
		linalg::VectorView< float const >	base_weight,
		linalg::VectorView< float const >	left_weight,
		linalg::VectorView< float const >	right_weight
	)

Expands a leaf node into two additional leaf nodes for a multi-target tree.

◆ GetCategoriesMatrix()

CategoricalSplitMatrix xgboost::RegTree::GetCategoriesMatrix ( ) const

inline

◆ GetDepth()

std::int32_t xgboost::RegTree::GetDepth ( bst_node_t nid ) const

inline

get current depth

Parameters

nid node id

◆ GetMultiTargetTree()

auto xgboost::RegTree::GetMultiTargetTree ( ) const

inline

Get the underlying implementaiton of multi-target tree.

◆ GetNodes()

const std::vector<Node>& xgboost::RegTree::GetNodes ( ) const

inline

get const reference to nodes

◆ GetNumLeaves()

bst_node_t xgboost::RegTree::GetNumLeaves ( ) const

◆ GetNumSplitNodes()

bst_node_t xgboost::RegTree::GetNumSplitNodes ( ) const

◆ GetSplitCategories()

common::Span<uint32_t const> xgboost::RegTree::GetSplitCategories ( ) const

inline

◆ GetSplitCategoriesPtr()

auto const& xgboost::RegTree::GetSplitCategoriesPtr ( ) const

inline

◆ GetSplitTypes()

std::vector<FeatureType> const& xgboost::RegTree::GetSplitTypes ( ) const

inline

Get split types for all nodes.

◆ GetStats()

const std::vector<RTreeNodeStat>& xgboost::RegTree::GetStats ( ) const

inline

get const reference to stats

◆ HasCategoricalSplit()

bool xgboost::RegTree::HasCategoricalSplit ( ) const

inline

Whether this tree has categorical split.

◆ IsLeaf()

bool xgboost::RegTree::IsLeaf ( bst_node_t nidx ) const

inline

◆ IsLeftChild()

bool xgboost::RegTree::IsLeftChild ( bst_node_t nidx ) const

inline

◆ IsMultiTarget()

bool xgboost::RegTree::IsMultiTarget ( ) const

inline

Whether this is a multi-target tree.

◆ IsRoot()

bool xgboost::RegTree::IsRoot ( bst_node_t nidx ) const

inline

◆ LeftChild()

bst_node_t xgboost::RegTree::LeftChild ( bst_node_t nidx ) const

inline

◆ Load()

void xgboost::RegTree::Load ( dmlc::Stream * fi )

load model from stream

Parameters

fi	input stream

◆ LoadModel()

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

overridevirtual

load the model from a JSON object

Parameters

in	JSON object where to load the model from

Implements xgboost::Model.

◆ MaxDepth() [1/2]

int xgboost::RegTree::MaxDepth ( )

inline

get maximum depth

◆ MaxDepth() [2/2]

int xgboost::RegTree::MaxDepth ( int nid ) const

inline

get maximum depth

Parameters

nid node id

◆ NodeCats()

common::Span<uint32_t const> xgboost::RegTree::NodeCats ( bst_node_t nidx ) const

inline

Get the bit storage for categories.

◆ NodeSplitType()

FeatureType xgboost::RegTree::NodeSplitType ( bst_node_t nidx ) const

inline

Get split type for a node.

Parameters

nidx	Index of node.

Returns: The type of this split. For leaf node it's always kNumerical.

◆ NumExtraNodes()

bst_node_t xgboost::RegTree::NumExtraNodes ( ) const

inlinenoexcept

number of extra nodes besides the root

◆ NumFeatures()

bst_feature_t xgboost::RegTree::NumFeatures ( ) const

inlinenoexcept

Get the number of features.

◆ NumNodes()

bst_node_t xgboost::RegTree::NumNodes ( ) const

inlinenoexcept

Get the total number of nodes including deleted ones in this tree.

◆ NumTargets()

bst_target_t xgboost::RegTree::NumTargets ( ) const

inline

The size of leaf weight.

◆ NumValidNodes()

bst_node_t xgboost::RegTree::NumValidNodes ( ) const

inlinenoexcept

Get the total number of valid nodes in this tree.

◆ operator==()

bool xgboost::RegTree::operator== ( const RegTree & b ) const

inline

◆ operator[]() [1/2]

Node& xgboost::RegTree::operator[] ( int nid )

inline

get node given nid

◆ operator[]() [2/2]

const Node& xgboost::RegTree::operator[] ( int nid ) const

inline

get node given nid

◆ Parent()

bst_node_t xgboost::RegTree::Parent ( bst_node_t nidx ) const

inline

◆ RightChild()

bst_node_t xgboost::RegTree::RightChild ( bst_node_t nidx ) const

inline

◆ Save()

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

save model to stream

Parameters

fo	output stream

◆ SaveModel()

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

overridevirtual

saves the model config to a JSON object

Parameters

out	JSON container where to save the model to

Implements xgboost::Model.

◆ SetLeaf()

void xgboost::RegTree::SetLeaf	(	bst_node_t	nidx,
		linalg::VectorView< float const >	weight
	)

inline

Set the leaf weight for a multi-target tree.

◆ Size()

bst_node_t xgboost::RegTree::Size ( ) const

inline

◆ SplitCond()

float xgboost::RegTree::SplitCond ( bst_node_t nidx ) const

inline

◆ SplitIndex()

bst_feature_t xgboost::RegTree::SplitIndex ( bst_node_t nidx ) const

inline

◆ Stat() [1/2]

RTreeNodeStat& xgboost::RegTree::Stat ( int nid )

inline

get node statistics given nid

◆ Stat() [2/2]

const RTreeNodeStat& xgboost::RegTree::Stat ( int nid ) const

inline

get node statistics given nid

◆ WalkTree()

template<typename Func >

void xgboost::RegTree::WalkTree ( Func func ) const

inline

Member Data Documentation

◆ kDeletedNodeMarker

constexpr uint32_t xgboost::RegTree::kDeletedNodeMarker = std::numeric_limits<uint32_t>::max()

staticconstexpr

◆ kInvalidNodeId

constexpr bst_node_t xgboost::RegTree::kInvalidNodeId {MultiTargetTree::InvalidNodeId()}

staticconstexpr

◆ kRoot

constexpr bst_node_t xgboost::RegTree::kRoot {0}

staticconstexpr

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

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

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ SplitCondT

Constructor & Destructor Documentation

◆ RegTree() [1/2]

◆ RegTree() [2/2]

Member Function Documentation

◆ CalculateContributionsApprox()

◆ ChangeToLeaf()

◆ CollapseToLeaf()

◆ DefaultLeft()

◆ DumpModel()

◆ Equal()

◆ ExpandCategorical()

◆ ExpandNode() [1/2]

◆ ExpandNode() [2/2]

◆ GetCategoriesMatrix()

◆ GetDepth()

◆ GetMultiTargetTree()

◆ GetNodes()

◆ GetNumLeaves()

◆ GetNumSplitNodes()

◆ GetSplitCategories()

◆ GetSplitCategoriesPtr()

◆ GetSplitTypes()

◆ GetStats()

◆ HasCategoricalSplit()

◆ IsLeaf()

◆ IsLeftChild()

◆ IsMultiTarget()

◆ IsRoot()

◆ LeftChild()

◆ Load()

◆ LoadModel()

◆ MaxDepth() [1/2]

◆ MaxDepth() [2/2]

◆ NodeCats()

◆ NodeSplitType()

◆ NumExtraNodes()

◆ NumFeatures()

◆ NumNodes()

◆ NumTargets()

◆ NumValidNodes()

◆ operator==()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ Parent()

◆ RightChild()

◆ Save()

◆ SaveModel()

◆ SetLeaf()

◆ Size()

◆ SplitCond()

◆ SplitIndex()

◆ Stat() [1/2]

◆ Stat() [2/2]

◆ WalkTree()

Member Data Documentation

◆ kDeletedNodeMarker

◆ kInvalidNodeId

◆ kRoot