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:
Collaboration diagram for xgboost::RegTree:

## 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...
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...
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 | 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...
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
template<bool has_missing = true>
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...
template<bool has_missing = true>
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...
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
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

using xgboost::RegTree::SplitCondT = bst_float

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

  feat | dense feature vector, if the feature is missing the field is set to NaN
  out_contribs | output vector to hold the contributions
  condition | fix one feature to either off (-1) on (1) or not fixed (0 default)
  condition_feature | the 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

  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

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

\parm b The 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

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

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

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

  nid | node id

## ◆ GetLeafIndex()

template<bool has_missing>

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

get the leaf index

Parameters

  feat | dense feature vector, if the feature is missing the field is set to NaN

Returns
  the leaf index of the given feature

## ◆ GetNext()

template<bool has_missing>

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

get next position of the tree given current pid

Parameters

  pid | Current node id.
  fvalue | feature value if not missing.
  is_unknown | Whether 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

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

## ◆ Load()

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

load model from stream

Parameters

  fi | input stream

## ◆ LoadModel()

void xgboost::RegTree::LoadModel | ( | Json const & | in | ) |
| override virtual

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

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

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

  fo | output stream

## ◆ SaveModel()

void xgboost::RegTree::SaveModel | ( | Json * | out | ) | const
| override virtual

saves the model config to a json object

Parameters

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

  feat | dense feature vector, if the feature is missing the field is set to NaN
  phi | dense output vector of feature attributions
  node_index | the index of the current node in the tree
  unique_depth | how many unique features are above the current node in the tree
  parent_unique_path | a vector of statistics about our current path through the tree
  parent_zero_fraction | what fraction of the parent path weight is coming as 0 (integrated)
  parent_one_fraction | what fraction of the parent path weight is coming as 1 (fixed)
  parent_feature_index | what feature the parent node used to split
  condition | fix one feature to either off (-1) on (1) or not fixed (0 default)
  condition_feature | the index of the feature to fix
  condition_fraction | what 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 constexpr

## ◆ kInvalidNodeId

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

## ◆ kRoot

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

## ◆ param

TreeParam xgboost::RegTree::param

model parameter

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

- /home/runner/work/xgboost/xgboost/include/xgboost/tree_model.h