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  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 ()
 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...
 
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 (int 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...
 
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
 
int GetLeafIndex (const FVec &feat) const
 get the leaf index More...
 
void CalculateContributions (const RegTree::FVec &feat, 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, unsigned 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, bst_float *out_contribs) const
 calculate the approximate feature contributions for the given root More...
 
int GetNext (int pid, bst_float fvalue, bool is_unknown) const
 get next position of the tree given current pid 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...
 
void FillNodeMeanValues ()
 calculate the mean value for each node, required for feature contributions More...
 
- 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,
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,
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.

b The other tree.

◆ ExpandNode()

void xgboost::RegTree::ExpandNode ( int  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 
)
inline

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

◆ FillNodeMeanValues()

void xgboost::RegTree::FillNodeMeanValues ( )

calculate the mean value for each node, required for feature contributions

◆ GetDepth()

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

get current depth

Parameters
nidnode id

◆ GetLeafIndex()

int xgboost::RegTree::GetLeafIndex ( const FVec feat) const
inline

get the leaf index

Parameters
featdense feature vector, if the feature is missing the field is set to NaN
Returns
the leaf index of the given feature

◆ GetNext()

int xgboost::RegTree::GetNext ( int  pid,
bst_float  fvalue,
bool  is_unknown 
) const
inline

get next position of the tree given current pid

Parameters
pidCurrent node id.
fvaluefeature value if not missing.
is_unknownWhether current required feature is missing.

◆ 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

◆ 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 ( int  nid) const
inline

get maximum depth

Parameters
nidnode id

◆ MaxDepth() [2/2]

int xgboost::RegTree::MaxDepth ( )
inline

get maximum depth

◆ 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,
unsigned  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()
static

◆ kInvalidNodeId

constexpr bst_node_t xgboost::RegTree::kInvalidNodeId {-1}
static

◆ kRoot

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

◆ param

TreeParam xgboost::RegTree::param

model parameter


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