xgboost
Classes | Public Types | Public Member Functions | Public Attributes | Static Public Attributes | List of all members
xgboost::RegTree Class Reference

define regression tree to be the most common tree model. This is the data structure used in xgboost's major tree models. More...

#include <tree_model.h>

Inheritance diagram for xgboost::RegTree:
Inheritance graph
Collaboration diagram for xgboost::RegTree:
Collaboration graph

Classes

struct  CategoricalSplitMatrix
 
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...
 
struct  Segment
 

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 ()
 constructor More...
 
Nodeoperator[] (int nid)
 get node given nid More...
 
const Nodeoperator[] (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...
 
RTreeNodeStatStat (int nid)
 get node statistics given nid More...
 
const RTreeNodeStatStat (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 ExpandCategorical (bst_node_t nid, unsigned split_index, common::Span< 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
 
int GetDepth (int nid) const
 get current depth More...
 
int MaxDepth (int nid) const
 get maximum depth More...
 
int MaxDepth ()
 get maximum depth More...
 
int NumExtraNodes () const
 number of extra nodes besides the root More...
 
bst_node_t GetNumLeaves () const
 
bst_node_t GetNumSplitNodes () const
 
void CalculateContributions (const RegTree::FVec &feat, std::vector< float > *mean_values, bst_float *out_contribs, int condition=0, unsigned condition_feature=0) const
 calculate the feature contributions (https://arxiv.org/abs/1706.06060) for the tree More...
 
void TreeShap (const RegTree::FVec &feat, bst_float *phi, bst_node_t node_index, unsigned unique_depth, PathElement *parent_unique_path, bst_float parent_zero_fraction, bst_float parent_one_fraction, int parent_feature_index, int condition, unsigned condition_feature, bst_float condition_fraction) const
 Recursive function that computes the feature attributions for a single tree. 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...
 
const std::vector< FeatureType > & GetSplitTypes () const
 Get split types for all nodes. More...
 
common::Span< uint32_t const > GetSplitCategories () const
 
auto const & GetSplitCategoriesPtr () const
 
CategoricalSplitMatrix GetCategoriesMatrix () const
 
- Public Member Functions inherited from xgboost::Model
virtual ~Model ()=default
 

Public Attributes

TreeParam param
 model parameter More...
 

Static Public Attributes

static constexpr bst_node_t kInvalidNodeId {-1}
 
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

Constructor & Destructor Documentation

◆ RegTree()

xgboost::RegTree::RegTree ( )
inline

constructor

Member Function Documentation

◆ CalculateContributions()

void xgboost::RegTree::CalculateContributions ( const RegTree::FVec feat,
std::vector< float > *  mean_values,
bst_float out_contribs,
int  condition = 0,
unsigned  condition_feature = 0 
) const

calculate the feature contributions (https://arxiv.org/abs/1706.06060) for the tree

Parameters
featdense feature vector, if the feature is missing the field is set to NaN
out_contribsoutput vector to hold the contributions
conditionfix one feature to either off (-1) on (1) or not fixed (0 default)
condition_featurethe index of the feature to fix

◆ 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
featdense feature vector, if the feature is missing the field is set to NaN
out_contribsoutput 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
ridnode id of the node
valuenew 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
ridnode id of the node
valuenew leaf value

◆ 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
fmapfeature map that may help give interpretations of feature
with_statswhether dump out statistics as well
formatthe 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
bThe other tree.

◆ ExpandCategorical()

void xgboost::RegTree::ExpandCategorical ( bst_node_t  nid,
unsigned  split_index,
common::Span< 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
nidThe node index to expand.
split_indexFeature index of the split.
split_catThe bitset containing categories
default_leftTrue to default left.
base_weightThe base weight, before learning rate.
left_leaf_weightThe left leaf weight for prediction, modified by learning rate.
right_leaf_weightThe right leaf weight for prediction, modified by learning rate.
loss_changeThe loss change.
sum_hessThe sum hess.
left_sumThe sum hess of left leaf.
right_sumThe sum hess of right leaf.

◆ ExpandNode()

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
nidThe node index to expand.
split_indexFeature index of the split.
split_valueThe split condition.
default_leftTrue to default left.
base_weightThe base weight, before learning rate.
left_leaf_weightThe left leaf weight for prediction, modified by learning rate.
right_leaf_weightThe right leaf weight for prediction, modified by learning rate.
loss_changeThe loss change.
sum_hessThe sum hess.
left_sumThe sum hess of left leaf.
right_sumThe sum hess of right leaf.
leaf_right_childThe right child index of leaf, by default kInvalidNodeId, some updaters use the right child index of leaf as a marker

◆ GetCategoriesMatrix()

CategoricalSplitMatrix xgboost::RegTree::GetCategoriesMatrix ( ) const
inline

◆ GetDepth()

int xgboost::RegTree::GetDepth ( int  nid) const
inline

get current depth

Parameters
nidnode id

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

const std::vector<FeatureType>& 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

◆ Load()

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

load model from stream

Parameters
fiinput stream

◆ LoadModel()

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

load the model from a JSON object

Parameters
inJSON 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
nidnode id

◆ NodeSplitType()

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

Get split type for a node.

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

◆ NumExtraNodes()

int xgboost::RegTree::NumExtraNodes ( ) const
inline

number of extra nodes besides the root

◆ 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

◆ Save()

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

save model to stream

Parameters
fooutput stream

◆ SaveModel()

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

saves the model config to a JSON object

Parameters
outJSON container where to save the model to

Implements xgboost::Model.

◆ 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

◆ TreeShap()

void xgboost::RegTree::TreeShap ( const RegTree::FVec feat,
bst_float phi,
bst_node_t  node_index,
unsigned  unique_depth,
PathElement *  parent_unique_path,
bst_float  parent_zero_fraction,
bst_float  parent_one_fraction,
int  parent_feature_index,
int  condition,
unsigned  condition_feature,
bst_float  condition_fraction 
) const

Recursive function that computes the feature attributions for a single tree.

Parameters
featdense feature vector, if the feature is missing the field is set to NaN
phidense output vector of feature attributions
node_indexthe index of the current node in the tree
unique_depthhow many unique features are above the current node in the tree
parent_unique_patha vector of statistics about our current path through the tree
parent_zero_fractionwhat fraction of the parent path weight is coming as 0 (integrated)
parent_one_fractionwhat fraction of the parent path weight is coming as 1 (fixed)
parent_feature_indexwhat feature the parent node used to split
conditionfix one feature to either off (-1) on (1) or not fixed (0 default)
condition_featurethe index of the feature to fix
condition_fractionwhat fraction of the current weight matches our conditioning feature

◆ 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 {-1}
staticconstexpr

◆ kRoot

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

◆ param

TreeParam xgboost::RegTree::param

model parameter


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