CompactRegressionTree

R2026b

Compact regression tree

Description

CompactRegressionTree is a compact version of a regression tree. The compact version does not include the data used to train the regression tree. Therefore, you cannot perform some tasks, such as cross-validation, using the compact regression tree. Use a compact regression tree to make predictions for new data.

Creation

Create a CompactRegressionTree object from a full RegressionTree model object by using the compact function.

Properties

Tree Properties

CategoricalSplit — Categorical splits

Read-only: n-by-2 cell array

This property is read-only.

Categorical splits, returned as an n-by-2 cell array, where n is the number of categorical splits in the tree. Each row in CategoricalSplit contains the left and right values for a categorical split. For each branch node with categorical split j based on a categorical predictor variable z, the software selects the left child if z is in CategoricalSplit(j,1) and the right child if z is in CategoricalSplit(j,2). The splits are in the same order as the nodes of the tree. Nodes for these splits can be found by running cuttype and selecting 'categorical' cuts from top to bottom.

Data Types: cell

Children — Numbers of child nodes for each node

Read-only: n-by-2 numeric array

This property is read-only.

Numbers of the child nodes for each node in the tree, returned as an n-by-2 numeric array, where n is the number of nodes. Leaf nodes have child node 0.

Data Types: double

CutCategories — Categories used at branches

Read-only: n-by-2 cell array

This property is read-only.

Categories used at the branches in the tree, returned as an n-by-2 cell array, where n is the number of nodes. For each branch node i based on a categorical predictor variable X, the software selects the left child if X is among the categories listed in CutCategories{i,1} and the right child if X is among those listed in CutCategories{i,2}. Both columns of CutCategories are empty for leaf nodes and for branch nodes based on continuous predictors.

CutPoint contains the cut points for 'continuous' cuts, and CutCategories contains the set of categories for 'categorical' cuts.

Data Types: cell

CutPoint — Values used as cut points

Read-only: n-element numeric vector

This property is read-only.

Values used as cut points in the tree, returned as an n-element numeric vector, where n is the number of nodes. For each branch node i based on a continuous predictor variable X, the software selects the left child if X < CutPoint(i) and the right child if X >= CutPoint(i). CutPoint is NaN for leaf nodes and for branch nodes based on categorical predictors.

CutPoint contains the cut points for 'continuous' cuts, and CutCategories contains the set of categories for 'categorical' cuts.

Data Types: double

CutPredictor — Names of variables used for branching in each node

Read-only: n-element cell array

This property is read-only.

Names of the variables used for branching in each node in the tree, returned as an n-element cell array, where n is the number of nodes. These variables are also known as cut variables. For leaf nodes, CutPredictor contains an empty character vector.

CutPoint contains the cut points for 'continuous' cuts, and CutCategories contains the set of categories for 'categorical' cuts.

Data Types: cell

CutPredictorIndex — Indices of variables used for branching in each node

Read-only: n-element numeric array

This property is read-only.

Indices of the variables used for branching in each node in the tree, returned as an n-element numeric array, where n is the number of nodes. For more information, see CutPredictor.

Data Types: double

CutType — Type of cut at each node

Read-only: n-element cell array

This property is read-only.

Type of cut at each node in the tree, returned as an n-element cell array, where n is the number of nodes. For each node i:

• CutType{i} is 'continuous' if the cut is defined in the form X < v for a variable X and cut point v.

• CutType{i} is 'categorical' if the cut is defined by whether a variable X takes a value in a set of categories.

• CutType{i} is '' if i is a leaf node.

CutPoint contains the cut points for 'continuous' cuts, and CutCategories contains the set of categories for 'categorical' cuts.

Data Types: cell

IsBranchNode — Indicator of branch nodes

Read-only: logical vector

This property is read-only.

Indicator of branch nodes, returned as a logical vector that is true for each branch node and false for each leaf node of the tree.

Data Types: logical

NodeError — Mean squared error for each node

Read-only: n-element numeric vector

This property is read-only.

Mean squared error for each node in the tree, returned as an n-element numeric vector, where n is the number of nodes in the tree.

Data Types: double

NodeMean — Mean observation values for each node

Read-only: n-element numeric vector

This property is read-only.

Mean observation values for each node in the tree, returned as an n-element numeric vector, where n is the number of nodes in the tree. Every element in NodeMean is the average of the true Y values over all observations in the node.

Data Types: double

NodeProbability — Proportion of observations that satisfy conditions for node

Read-only: n-element numeric vector

This property is read-only.

Proportion of the observations in the original data that satisfy the conditions for each node in the tree, returned as an n-element numeric vector, where n is the number of nodes in the tree.

Data Types: double

NodeRisk — Risk for each node

Read-only: n-element numeric vector

This property is read-only.

Risk for each node in the tree, returned as an n-element numeric vector, where n is the number of nodes in the tree. The risk for each node is the node error weighted by the node probability.

Data Types: double

NodeSize — Size of nodes

Read-only: n-element numeric vector

This property is read-only.

Size of the nodes in the tree, returned as an n-element numeric vector, where n is the number of nodes in the tree. The size of a node is the number of training observations that satisfy the conditions for the node.

Data Types: double

NumNodes — Number of nodes

Read-only: positive integer

This property is read-only.

Number of nodes in the tree, returned as a positive integer.

Data Types: double

Parent — Number of parents for each node

Read-only: n-element integer vector

This property is read-only.

Number of parents for each node in the tree, returned as an n-element integer vector, where n is the number of nodes in the tree. The parent of the root node is 0.

Data Types: double

PruneAlpha — Alpha values for pruning tree

Read-only: numeric vector

This property is read-only.

Alpha values for pruning the tree, returned as a numeric vector with one element per pruning level. If the pruning level ranges from 0 to M, then PruneAlpha has M + 1 elements sorted in ascending order. PruneAlpha(1) is for pruning level 0 (no pruning), PruneAlpha(2) is for pruning level 1, and so on.

For more information, see How Decision Trees Create a Pruning Sequence.

Data Types: double

PruneList — Pruning levels of each node

Read-only: integer vector

This property is read-only.

Pruning levels of each node in the tree, returned as an integer vector with NumNodes elements. The pruning levels range from 0 (no pruning) to M, where M is the distance between the deepest leaf and the root node.

For details, see Pruning.

Data Types: double

SurrogateCutCategories — Categories used for surrogate splits

Read-only: n-element cell array

This property is read-only.

Categories used for the surrogate splits, returned as an n-element cell array, where n is the number of nodes in the tree. For each node k, SurrogateCutCategories{k} is a cell array. The length of SurrogateCutCategories{k} is equal to the number of surrogate predictors at the node. Every element of SurrogateCutCategories{k} is either an empty character vector for a continuous surrogate predictor, or a two-element cell array with categories for a categorical surrogate predictor. The first element of the array lists categories assigned to the left child by the surrogate split, and the second element lists categories assigned to the right child. The order of the surrogate split variables at each node matches the order of the variables in SurrogateCutPredictor. The optimal-split variable at this node does not appear. For nonbranch (leaf) nodes, SurrogateCutCategories contains an empty cell.

Data Types: cell

SurrogateCutFlip — Numeric cut assignments used for surrogate splits

Read-only: n-element cell array

This property is read-only.

Numeric cut assignments used for the surrogate splits in the tree, returned as an n-element cell array, where n is the number of nodes in the tree. For each node k, SurrogateCutFlip{k} is a numeric vector. The length of SurrogateCutFlip{k} is equal to the number of surrogate predictors at the node. Every element of SurrogateCutFlip{k} is either zero for a categorical surrogate predictor, or a numeric cut assignment for a continuous surrogate predictor. The numeric cut assignment is either –1 or +1. For every surrogate split with a numeric cut C based on a continuous predictor variable Z, the software selects the left child if Z < C and the cut assignment for the surrogate split is +1, or if Z ≥ C and the cut assignment is –1. Similarly, the software selects the right child if Z ≥ C and the cut assignment for the surrogate split is +1, or if Z < C and the cut assignment is –1. The order of the surrogate split variables at each node matches the order of the variables in SurrogateCutPredictor. The optimal-split variable at this node does not appear. For nonbranch (leaf) nodes, SurrogateCutFlip contains an empty array.

Data Types: cell

SurrogateCutPoint — Numeric values used for surrogate splits

Read-only: n-element cell array

This property is read-only.

Numeric values used for the surrogate splits in the tree, returned as an n-element cell array, where n is the number of nodes in the tree. For each node k, SurrogateCutPoint{k} is a numeric vector. The length of SurrogateCutPoint{k} is equal to the number of surrogate predictors at the node. Every element of SurrogateCutPoint{k} is either NaN for a categorical surrogate predictor, or a numeric cut for a continuous surrogate predictor. For every surrogate split with a numeric cut C based on a continuous predictor variable Z, the software selects the left child if Z < C and the SurrogateCutFlip value for the surrogate split is +1, or if Z ≥ C and the SurrogateCutFlip value is –1. Similarly, the software selects the right child if Z ≥ C and the SurrogateCutFlip value for the surrogate split is +1, or if Z < C and the SurrogateCutFlip value is –1. The order of the surrogate split variables at each node matches the order of the variables in SurrogateCutPredictor. The optimal-split variable at this node does not appear. For nonbranch (leaf) nodes, SurrogateCutPoint contains an empty cell.

Data Types: cell

SurrogateCutPredictor — Names of variables used for surrogate splits

Read-only: n-element cell array

This property is read-only.

Names of the variables used for the surrogate splits in each node in the tree, returned as an n-element cell array, where n is the number of nodes in the tree. Every element of SurrogateCutPredictor is a cell array containing the names of the surrogate split variables at the node. The variables are sorted in descending order by the predictive measure of association with the optimal predictor, and only variables with the positive predictive measure are included. The optimal-split variable at this node does not appear. For nonbranch (leaf) nodes, SurrogateCutPredictor contains an empty cell.

Data Types: cell

SurrogateCutType — Types of surrogate splits at each node

Read-only: n-element cell array

This property is read-only.

Types of the surrogate splits at each node in the tree, returned as an n-element cell array, where n is the number of nodes in the tree. For each node k, SurrogateCutType{k} is a cell array containing the types of the surrogate split variables at the node. The variables are sorted in descending order by the predictive measure of association with the optimal predictor, and only variables with the positive predictive measure are included. The order of the surrogate split variables at each node matches the order of the variables in SurrogateCutPredictor. The optimal-split variable at this node does not appear. For nonbranch (leaf) nodes, SurrogateCutType contains an empty cell.

The surrogate split type is 'continuous' if the cut is defined in the form Z < V for a variable Z and cut point V, or 'categorical' if the cut is defined by whether Z takes a value in a set of categories.

Data Types: cell

SurrogatePredictorAssociation — Predictive measures of association for surrogate splits

Read-only: n-element cell array

This property is read-only.

Predictive measures of association for the surrogate splits in the tree, returned as an n-element cell array, where n is the number of nodes in the tree. For each node k, SurrogatePredictorAssociation{k} is a numeric vector. The length of SurrogatePredictorAssociation{k} is equal to the number of surrogate predictors at the node. Every element of SurrogatePredictorAssociation{k} contains the predictive measure of association between the optimal split and the surrogate split. The order of the surrogate split variables at each node matches the order of the variables in SurrogateCutPredictor. The optimal-split variable at this node does not appear. For nonbranch (leaf) nodes, SurrogatePredictorAssociation contains an empty cell.

Data Types: cell

Data Properties

CategoricalPredictors — Categorical predictor indices

Read-only: vector of positive integers | []

This property is read-only.

Categorical predictor indices, returned as a vector of positive integers. CategoricalPredictors contains index values indicating that the corresponding predictors are categorical. The index values are between 1 and p, where p is the number of predictors used to train the model. If none of the predictors are categorical, then this property is empty ([]).

Data Types: single | double

ExpandedPredictorNames — Expanded predictor names

Read-only: cell array of character vectors

This property is read-only.

Expanded predictor names, returned as a cell array of character vectors.

If the model uses encoding for categorical variables, then ExpandedPredictorNames includes the names that describe the expanded variables. Otherwise, ExpandedPredictorNames is the same as PredictorNames.

Data Types: cell

PredictorNames — Predictor names

Read-only: cell array of character vectors

This property is read-only.

Predictor names, returned as a cell array of character vectors. The order of the entries in PredictorNames is the same as in the training data.

Data Types: cell

ResponseName — Name of response variable

Read-only: character vector

This property is read-only.

Name of the response variable, returned as a character vector.

Data Types: char

ResponseTransform — Function for transforming predicted response values

"none" | function handle

Function for transforming the predicted response values, specified as "none" or a function handle. "none" means no transformation; equivalently, "none" means @(x)x. A function handle must accept a matrix of response values and return a matrix of the same size.

To change the function for transforming the predicted response values, use dot notation. For example, for a model Mdl and a function function that you define, you can specify:

Mdl.ResponseTransform = @function;

Data Types: char | string | function_handle

Object Functions

gather	Gather properties of Statistics and Machine Learning Toolbox object from GPU
lime	Local interpretable model-agnostic explanations (LIME)
loss	Regression error for regression tree model
nodeVariableRange	Retrieve variable range of decision tree node
partialDependence	Compute partial dependence
plotPartialDependence	Create partial dependence plot (PDP) and individual conditional expectation (ICE) plots
predict	Predict responses using regression tree model
predictorImportance	Estimates of predictor importance for regression tree
shapley	Shapley values
surrogateAssociation	Mean predictive measure of association for surrogate splits in regression tree
update	Update model parameters for code generation
view	View regression tree

Examples

Reduce Size of Regression Tree

Load the sample data.

load carsmall

Create a regression tree for the sample data.

tree = fitrtree([Weight,Cylinders],MPG, ...
    MinParentSize=20, ...
    PredictorNames=["W","C"]);

Reduce the size of the regression tree.

ctree = compact(tree);

Compare the size of the compact tree to the size of the original tree.

t = whos("tree"); % t.bytes = size of tree in bytes
c = whos("ctree"); % c.bytes = size of ctree in bytes
[c.bytes t.bytes]

ans = 1×2

        4226        7473

The compact tree is smaller than the original tree.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The predict and update functions support code generation.

• To integrate the prediction of a regression tree model into Simulink^®, you can use the RegressionTree Predict block in the Statistics and Machine Learning Toolbox™ library or a MATLAB^® Function block with the predict function.

• When you train a regression tree model by using fitrtree, the following restrictions apply.

  • The value of the ResponseTransform name-value argument cannot be an anonymous function. For fixed-point code generation, the value must be "none" (default).

  • You cannot use surrogate splits; that is, the value of the Surrogate name-value argument must be "off".

  • Fixed-point code generation and code generation with a coder configurer do not support categorical predictors (logical, categorical, char, string, or cell). You cannot use the CategoricalPredictors name-value argument. To include categorical predictors in a model, preprocess them by using dummyvar before fitting the model.

For more information, see Introduction to Code Generation for Statistics and Machine Learning Functions.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Usage notes and limitations:

• The following object functions fully support GPU arrays:

  • gather

  • nodeVariableRange

  • predictorImportance

  • surrogateAssociation

• The following object functions offer limited support for GPU arrays:

  • loss

  • partialDependence

  • plotPartialDependence

  • predict

  • view

• The object functions execute on a GPU if at least one of the following applies:

  • The model was fitted with GPU arrays.

  • The predictor data that you pass to the object function is a GPU array.

  • The response data that you pass to the object function is a GPU array.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced in R2011a