CompactRegressionEnsemble

R2026b

Compact regression ensemble

Description

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

Creation

Create a CompactRegressionEnsemble object from a full RegressionEnsemble or RegressionBaggedEnsemble model object by using the compact object function.

Properties

expand all

Ensemble Properties

`CombineWeights` — Method used to combine weak learner weights
Read-only: `'WeightedAverage'` | `'WeightedSum'`

This property is read-only.

Method used to combine weak learner weights, returned as 'WeightedAverage' or 'WeightedSum'.

Data Types: char

`NumTrained` — Number of trained weak learners
Read-only: positive integer

This property is read-only.

Number of trained weak learners in the ensemble, returned as a positive integer.

Data Types: double

`Trained` — Trained weak learners
Read-only: cell vector

This property is read-only.

Trained weak learners, returned as a cell vector. The entries of the cell vector contain the corresponding compact regression models.

Data Types: cell

`TrainedWeights` — Trained weak learner weights
Read-only: numeric vector

This property is read-only.

Trained weak learner weights, returned as a numeric vector. TrainedWeights has NumTrained elements, where NumTrained is the number of weak learners in the ensemble. The ensemble computes the predicted response by aggregating weighted predictions from its learners.

Data Types: double

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 raw response values
`"none"` (default) | function handle | function name

Function for transforming raw response values, specified as a function handle or function name. The default is "none", which means @(y)y, or no transformation. The function must accept a vector (the original response values) and return a vector of the same size (the transformed response values).

Example: Suppose you create a function handle that applies an exponential transformation to an input vector by using myfunction = @(y)exp(y). Then, you can specify the response transformation as ResponseTransform=myfunction.

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 ensemble model
`partialDependence`	Compute partial dependence
`plotPartialDependence`	Create partial dependence plot (PDP) and individual conditional expectation (ICE) plots
`predict`	Predict responses using regression ensemble model
`predictorImportance`	Estimates of predictor importance for regression ensemble of decision trees
`removeLearners`	Remove members of compact regression ensemble
`shapley`	Shapley values

Examples

collapse all

Reduce Size of Regression Ensemble

Open Live Script

Create a compact regression ensemble for efficiently making predictions on new data.

Load the carsmall data set. Consider a model that explains a car's fuel economy (MPG) using its weight (Weight) and number of cylinders (Cylinders).

load carsmall
X = [Weight Cylinders];
Y = MPG;

Train a boosted ensemble of 100 regression trees using the default LSBoost method. Specify that Cylinders is a categorical variable.

Mdl = fitrensemble(X,Y,PredictorNames=["W","C"], ...
    CategoricalPredictors=2)

Mdl = 
  RegressionEnsemble
           PredictorNames: {'W'  'C'}
             ResponseName: 'Y'
    CategoricalPredictors: 2
        ResponseTransform: 'none'
          NumObservations: 94
               NumTrained: 100
                   Method: 'LSBoost'
             LearnerNames: {'Tree'}
     ReasonForTermination: 'Terminated normally after completing the requested number of training cycles.'
                  FitInfo: [100×1 double]
       FitInfoDescription: {2×1 cell}
           Regularization: []


  Properties, Methods

Mdl is a RegressionEnsemble model object that includes the training data.

Create a compact version of Mdl.

CMdl = compact(Mdl)

CMdl = 
  CompactRegressionEnsemble
           PredictorNames: {'W'  'C'}
             ResponseName: 'Y'
    CategoricalPredictors: 2
        ResponseTransform: 'none'
               NumTrained: 100


  Properties, Methods

CMdl is a CompactRegressionEnsemble model object. CMdl is similar to Mdl, but does not store the training data.

Compare the amount of memory used by Mdl and CMdl.

mdlInfo = whos("Mdl");
cMdlInfo = whos("CMdl");
[mdlInfo.bytes cMdlInfo.bytes]

ans = 1×2

      511340      485035

Mdl uses more memory than CMdl.

CMdl.Trained stores the trained regression trees (CompactRegressionTree model objects) that compose Mdl.

Display a graph of the first tree in the compact ensemble.

view(CMdl.Trained{1},Mode="graph");

Figure Regression tree viewer contains an axes object and other objects of type uimenu, uicontrol. The axes object contains 36 objects of type line, text. One or more of the lines displays its values using only markers

By default, fitrensemble grows shallow trees for boosted ensembles of trees.

Predict the fuel economy of a typical car using the compact ensemble.

typicalX = [mean(X(:,1)) mode(X(:,2))];
predMeanX = predict(CMdl,typicalX)

predMeanX = 
26.2520

Tips

For a compact ensemble of regression trees Mdl, the Trained property contains a cell vector of Mdl.NumTrained CompactRegressionTree model objects. For a textual or graphical display of tree t in the cell vector, enter
```
view(Mdl.Trained{t})
```

Extended Capabilities

expand all

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

The predict function supports code generation.
To integrate the prediction of an ensemble into Simulink^®, you can use the RegressionEnsemble Predict block in the Statistics and Machine Learning Toolbox™ library or a MATLAB^® Function block with the predict function.
When you train an ensemble by using fitrensemble, the following restrictions apply.
- The value of the ResponseTransform name-value argument cannot be an anonymous function.
- Code generation limitations for regression trees also apply to ensembles of regression trees. You cannot use surrogate splits; that is, the value of the Surrogate name-value argument must be "off".
For fixed-point code generation, the following additional restrictions apply.
- When you train an ensemble by using fitrensemble, the value of the ResponseTransform name-value argument must be "none" (default).
- Categorical predictors (logical, categorical, char, string, or cell) are not supported. 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:
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 R2011a

CompactRegressionEnsemble

Description

Creation

Properties

Ensemble Properties

CombineWeights — Method used to combine weak learner weights Read-only: 'WeightedAverage' | 'WeightedSum'

NumTrained — Number of trained weak learners Read-only: positive integer

Trained — Trained weak learners Read-only: cell vector

TrainedWeights — Trained weak learner weights Read-only: numeric vector

Data Properties

CategoricalPredictors — Categorical predictor indices Read-only: vector of positive integers | []

ExpandedPredictorNames — Expanded predictor names Read-only: cell array of character vectors

PredictorNames — Predictor names Read-only: cell array of character vectors

ResponseName — Name of response variable Read-only: character vector

ResponseTransform — Function for transforming raw response values "none" (default) | function handle | function name

Object Functions

Examples

Reduce Size of Regression Ensemble

Tips

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

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

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

Version History

See Also

`CombineWeights` — Method used to combine weak learner weights
Read-only: `'WeightedAverage'` | `'WeightedSum'`

`NumTrained` — Number of trained weak learners
Read-only: positive integer

`Trained` — Trained weak learners
Read-only: cell vector

`TrainedWeights` — Trained weak learner weights
Read-only: numeric vector

`CategoricalPredictors` — Categorical predictor indices
Read-only: vector of positive integers | `[]`

`ExpandedPredictorNames` — Expanded predictor names
Read-only: cell array of character vectors

`PredictorNames` — Predictor names
Read-only: cell array of character vectors

`ResponseName` — Name of response variable
Read-only: character vector

`ResponseTransform` — Function for transforming raw response values
`"none"` (default) | function handle | function name

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

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

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