RegressionTree
R2026bBinary decision tree for regression
Description
RegressionTree is a decision tree with binary splits for
regression. Use the predict function of
RegressionTree to predict responses for new data. Because the
RegressionTree object contains the data used for training, you can
also use the object to compute resubstitution predictions.
Creation
Create a RegressionTree object by using fitrtree.
Properties
Tree Properties
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
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
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
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
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
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
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 formX < vfor a variableXand cut pointv.CutType{i}is'categorical'if the cut is defined by whether a variableXtakes a value in a set of categories.CutType{i}is''ifiis a leaf node.
CutPoint contains the cut points for
'continuous' cuts, and CutCategories
contains the set of categories for 'categorical' cuts.
Data Types: cell
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
This property is read-only.
Parameters used to train the tree, returned as a
TreeParams object. To access the parameters, use
dot notation. For example, for a tree model Mdl, you
can display the split criterion by entering
Mdl.ModelParameters.SplitCriterion. To display
all parameter values, enter
Mdl.ModelParameters.
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
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
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
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
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
This property is read-only.
Number of nodes in the tree, returned as a positive integer.
Data Types: double
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
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
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
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
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
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
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
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
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
Predictor Properties
This property is read-only.
Bin edges for numeric predictors, returned as a cell array of p numeric vectors, where p is the number of predictors. Each vector includes the bin edges for a numeric predictor. The element in the cell array for a categorical predictor is empty because the software does not bin categorical predictors.
The software bins numeric predictors only if you specify the NumBins
name-value argument as a positive integer scalar when training a model with tree learners.
The BinEdges property is empty if the NumBins value
is empty (default).
You can reproduce the binned predictor data Xbinned by using the
BinEdges property of the trained model
mdl.
X = mdl.X; % Predictor data
Xbinned = zeros(size(X));
edges = mdl.BinEdges;
% Find indices of binned predictors.
idxNumeric = find(~cellfun(@isempty,edges));
if iscolumn(idxNumeric)
idxNumeric = idxNumeric';
end
for j = idxNumeric
x = X(:,j);
% Convert x to array if x is a table.
if istable(x)
x = table2array(x);
end
% Group x into bins by using the discretize function.
xbinned = discretize(x,[-inf; edges{j}; inf]);
Xbinned(:,j) = xbinned;
endXbinned contains the bin indices, ranging from 1
to the number of bins, for the numeric predictors. Xbinned values are 0
for categorical predictors. If X contains NaNs, then
the corresponding Xbinned values are NaNs.Data Types: cell
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
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
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
This property is read-only.
Predictor values, returned as a real matrix or table. Each column of
X represents one variable (predictor), and each row represents
one observation.
Data Types: double | table
Response Properties
This property is read-only.
Name of the response variable, returned as a character vector.
Data Types: char
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
This property is read-only.
Response data, returned as a numeric column vector with the same number of rows as
X. Each entry in Y is the response to the
data in the corresponding row of X.
Data Types: double
Other Data Properties
This property is read-only.
Cross-validation optimization of hyperparameters, returned as a SupervisedLearningBayesianOptimization object or a table of
hyperparameters and associated values. This property is nonempty if the
OptimizeHyperparameters name-value argument is nonempty when
you create the model. The value of
HyperparameterOptimizationResults depends on the setting of the
Optimizer option in the
HyperparameterOptimizationOptions value when you create the
model.
Value of Optimizer Option | Value of HyperparameterOptimizationResults |
|---|---|
"bayesopt" (default) | SupervisedLearningBayesianOptimization object |
"gridsearch" or "randomsearch" | Table of hyperparameters used, observed objective function values (cross-validation loss), and observation ranks from lowest (best) to highest (worst) |
This property is read-only.
Number of observations in the training data, returned as a positive integer.
NumObservations can be less than the number of rows of input data
when there are missing values in the input data or response data.
Data Types: double
This property is read-only.
Rows of the original predictor data X used for fitting, returned as
an n-element logical vector, where n is the number
of rows of X. If the software uses all rows of X
to create the object, then RowsUsed is an empty array
([]).
Data Types: logical
This property is read-only.
Scaled weights in the tree, returned as a numeric vector. W has
length n, the number of rows in the training data.
Data Types: double
Object Functions
compact | Reduce size of machine learning model |
crossval | Cross-validate machine learning model |
cvloss | Regression error by cross-validation for regression tree model |
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 |
prune | Produce sequence of regression subtrees by pruning regression tree |
resubLoss | Resubstitution loss for regression tree model |
resubPredict | Predict response of regression tree by resubstitution |
shapley | Shapley values |
surrogateAssociation | Mean predictive measure of association for surrogate splits in regression tree |
view | View regression tree |
Examples
Load the sample data.
load carsmallTrain a regression tree using the sample data. The response variable is MPG (miles per gallon).
Mdl = fitrtree([Weight,Cylinders],MPG, ... CategoricalPredictors=2,MinParentSize=20, ... PredictorNames=["W","C"])
Mdl =
RegressionTree
PredictorNames: {'W' 'C'}
ResponseName: 'Y'
CategoricalPredictors: 2
ResponseTransform: 'none'
NumObservations: 94
Properties, Methods
Mdl is a RegressionTree object that contains one numeric predictor (W) and one categorical predictor (C).
Predict the mileage of cars that weigh 4000 pounds and have 4, 6, or 8 cylinders.
predictedMPG = predict(Mdl,[4000 4; 4000 6; 4000 8])
predictedMPG = 3×1
19.2778
19.2778
14.3889
References
[1] Breiman, L., J. Friedman, R. Olshen, and C. Stone. Classification and Regression Trees. Boca Raton, FL: CRC Press, 1984.
Extended Capabilities
Usage notes and limitations:
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
predictfunction.When you train a regression tree model by using
fitrtree, the following restrictions apply.The value of the
ResponseTransformname-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
Surrogatename-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, orcell). You cannot use theCategoricalPredictorsname-value argument. To include categorical predictors in a model, preprocess them by usingdummyvarbefore fitting the model.
For more information, see Introduction to Code Generation for Statistics and Machine Learning Functions.
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.
Usage notes and limitations:
The following object functions fully support GPU arrays:
The following object functions offer limited support for GPU arrays:
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 R2011aIf you perform Bayesian hyperparameter optimization by using a supervised learning fit
function, the optimization results are stored in a SupervisedLearningBayesianOptimization object. In previous releases, the
optimization results are stored in a BayesianOptimization object.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)