regressionEnsembleComponent

Pipeline component for regression using ensemble of learners

Since R2026a

Description

regressionEnsembleComponent is a pipeline component that creates an ensemble of learners for regression. The pipeline component uses the functionality of the fitrensemble function during the learn phase to train the regression ensemble model. The component uses the functionality of the predict and loss functions during the run phase to perform regression.

Creation

Syntax

component = regressionEnsembleComponent

component = regressionEnsembleComponent(Name=Value)

Description

component = regressionEnsembleComponent creates a pipeline component for a regression ensemble model.

component = regressionEnsembleComponent(Name=Value) sets writable Properties using one or more name-value arguments. For example, you can specify the ensemble aggregation method, number of learning cycles, and type of weak learners.

Properties

Structural Parameters

The software sets structural parameters when you create the component. You cannot modify structural parameters after creating the component.

UseWeights — Observation weights flag

false or 0 (default) | true or 1

This property is read-only after the component is created.

Observation weights flag, specified as 0 (false) or 1 (true). If UseWeights is true, the component adds a third input "Weights" to the Inputs component property, and a third input tag 3 to the InputTags component property.

Example: c = regressionEnsembleComponent(UseWeights=1)

Data Types: logical

Learn Parameters

The software sets learn parameters when you create the component. You can modify learn parameters using dot notation any time before you use the learn object function. Any unset learn parameters use the corresponding default values.

FResample — Fraction of training set to resample

1 (default) | positive scalar in the range (0,1]

Fraction of the training set to resample for every weak learner, specified as a positive scalar in the range (0,1]. To use FResample, set Resample to "on".

Example: c = regressionEnsembleComponent(FResample=0.75)

Example: c.FResample = 0.5

Data Types: single | double

Learners — Weak learners to use in ensemble

"tree" (default) | tree template object | cell vector of tree template objects

Weak learners to use in the ensemble, specified as "tree", a tree template object, or a cell vector of tree template objects.

• If Learners is "tree", the component uses the default regression tree learners. For the default options, see templateTree.

• If Learners is a tree template object, the component uses the tree template object created by templateTree.

• If Learners is a cell vector of n tree template objects, the component grows n regression trees per learning cycle.

Example: c = regressionEnsembleComponent(Learners=templateTree(MaxNumSplits=5))

Example: c.Learners = "tree"

Data Types: char | string | cell

LearnRate — Learning rate for shrinkage

1 (default) | numeric scalar in the range (0,1]

Learning rate for shrinkage, specified as a numeric scalar in the range (0,1]. If you specify a learning rate below 1, the ensemble learns at a slower rate, but can converge to a better solution.

This property is valid only when Method is "LSBoost".

Example: c = regressionEnsembleComponent(LearnRate=0.1)

Example: c.LearnRate = 0.5

Data Types: single | double

Method — Ensemble aggregation method

"LSBoost (default) | "Bag"

Ensemble aggregation method, specified as "LSBoost" for least squares boosting, or "Bag" for bootstrap aggregation.

Example: c = regressionEnsembleComponent(Method="Bag")

Example: c.Method = "LSBoost"

Data Types: char | string

NumBins — Number of bins for numeric predictors

[](empty) (default) | positive integer scalar

Number of bins for the numeric predictors, specified as a positive integer scalar.

• If NumBins is empty ([]), the component does not bin any predictors.

• If NumBins is a positive integer scalar, the component bins every numeric predictor into at most NumBins equiprobable bins, and grows trees on the bin indices instead of the original data.

Example: c = regressionEnsembleComponent(NumBins=50)

Example: c.NumBins = 20

Data Types: single | double

NumLearningCycles — Number of ensemble learning cycles

100 (default) | positive integer

Number of ensemble learning cycles, specified as a positive integer. At every learning cycle, the component trains one weak learner for every template object in Learners. The component creates the ensemble using all trained learners and stores them in the Trained property of TrainedModel.

Example: c = regressionEnsembleComponent(NumLearningCycles=500)

Example: c.NumLearningCycles = 250

Data Types: single | double

Replace — Flag indicating to sample with replacement

"on" (default) | "off"

Flag indicating to sample with replacement, specified as "on" or "off".

This property is valid only when Method is "Bag" or when Resample is "on" and Method is "LSBoost".

Example: c = regressionEnsembleComponent(Replace="off")

Example: c.Replace = "on"

Data Types: char | string

Resample — Flag indicating to resample

"off" | "on"

Flag indicating to resample, specified as "off" or "on".

• If Method is "LSBoost" and Resample is "on", the component samples training observations using updated weights as the multinomial sampling probabilities. If Resample is "off", the component reweights observations at every learning iteration.

• If Method is "Bag", Resample must be "on". The component resamples a fraction of the training observations specified by FResample, with or without replacement based on the value of Replace.

Example: c = regressionEnsembleComponent(Resample="on")

Example: c.Resample = "off"

Data Types: char | string

Run Parameters

The software sets run parameters when you create the component. You can modify the run parameters using dot notation at any time. Any unset run parameters use the corresponding default values.

LossFun — Loss function

"mse" (default) | function handle

Loss function, specified as "mse" (mean squared error) or a function handle.

To specify a custom loss function, use function handle notation. For more information on custom loss functions, see LossFun.

Example: c = regressionEnsembleComponent(LossFun=@LossFun)

Example: c.LossFun = "mse"

Data Types: char | string | function_handle

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: c = regressionEnsembleComponent(ResponseTransform=@(y)exp(y))

Example: c.ResponseTransform = "exp"

Data Types: char | string | function_handle

UseObsForLearner — Option to use observations for learners

true(N,T) (default) | logical matrix

Option to use observations for learners, specified as a logical matrix of size N-by-T, where N is the number of observations in the first data argument of run, and T is the number of weak learners.

When UseObsForLearner(i,j) is true, the component uses learner j to predict the response of observation i.

Example: c = regressionEnsembleComponent(UseObsForLearner=logical([1 1; 0 1; 1 0]))

Example: c.UseObsForLearner = logical([0 1; 1 1; 1 0])

Data Types: logical

Component Properties

The software sets component properties when you create the component. You can modify the component properties (excluding HasLearnables and HasLearned) using dot notation at any time. You cannot modify the HasLearnables and HasLearned properties directly.

Name — Component identifier

"RegressionEnsemble" (default) | character vector | string scalar

Component identifier, specified as a character vector or string scalar.

Example: c = regressionEnsembleComponent(Name="Ensemble")

Example: c.Name = "EnsembleRegression"

Data Types: char | string

Inputs — Names of input ports

["Predictors","Response"] (default) | character vector | string array | cell array of character vectors

Names of the input ports, specified as a character vector, string array, or cell array of character vectors. If UseWeights is true, the component adds the input port "Weights" to Inputs.

Example: c = regressionEnsembleComponent(Inputs=["X","Y"])

Example: c.Inputs = ["X1","Y1"]

Data Types: char | string | cell

Outputs — Names of output ports

["Predictions","Loss"] (default) | character vector | string array | cell array of character vectors

Names of the output ports, specified as a character vector, string array, or cell array of character vectors.

Example: c = regressionEnsembleComponent(Outputs=["Responses","LossVal"])

Example: c.Outputs = ["X","Y"]

Data Types: char | string | cell

InputTags — Tags that enable automatic connection of component inputs

[1 2] (default) | nonnegative integer vector

Tags that enable the automatic connection of the component inputs with other components or pipelines, specified as a nonnegative integer vector. If you specify InputTags, the number of tags must match the number of inputs in Inputs. If UseWeights is true, the software adds a third input tag to InputTags.

Example: c = regressionEnsembleComponent(InputTags=[0 1])

Example: c.InputTags = [1 0]

Data Types: single | double

OutputTags — Tags that enable automatic connection of component outputs

[1 0] (default) | nonnegative integer vector

Tags that enable the automatic connection of the component outputs with other components or pipelines, specified as a nonnegative integer vector. If you specify OutputTags, the number of tags must match the number of outputs in Outputs.

Example: c = regressionEnsembleComponent(OutputTags=[0 1])

Example: c.OutputTags=[1 2]

Data Types: single | double

HasLearnables — Indicator for learnables

Read-only: 1 (true) (default)

This property is read-only.

Indicator for the learnables, returned as 1 (true). A value of 1 indicates that the component contains Learnables.

Data Types: logical

HasLearned — Indicator showing learning status of component

Read-only: 0 (false) (default) | 1 (true)

This property is read-only.

Indicator showing the learning status of the component, returned as 0 (false) or 1 (true). A value of 1 indicates that the learn object function has been applied to the component, and the Learnables are nonempty.

Data Types: logical

Learnables

The software sets learnables when you use the learn object function. You cannot modify learnables directly.

TrainedModel — Trained model

Read-only: CompactRegressionEnsemble model object

This property is read-only.

Trained model, returned as a CompactRegressionEnsemble model object.

Object Functions

learn	Initialize and evaluate pipeline or component
run	Execute pipeline or component for inference after learning
reset	Reset pipeline or component
series	Connect components in series to create pipeline
parallel	Connect components or pipelines in parallel to create pipeline
view	View diagram of pipeline inputs, outputs, components, and connections

Examples

Create and Train Pipeline Component for Ensemble Regression

Create a regressionEnsembleComponent pipeline component.

component = regressionEnsembleComponent

component = 

  regressionEnsembleComponent with properties:

            Name: "RegressionEnsemble"
          Inputs: ["Predictors"    "Response"]
       InputTags: [1 2]
         Outputs: ["Predictions"    "Loss"]
      OutputTags: [1 0]

   
Learnables (HasLearned = false)
    TrainedModel: []

   
Structural Parameters (locked)
      UseWeights: 0


Show all parameters

component is a regressionEnsembleComponent object that contains one learnable, TrainedModel. This property remains empty until you pass data to the component during the learn phase.

To use a bootstrap ensemble aggregation algorithm, set the Method property of the component to "Bag".

component.Method = "Bag";

Load the carsmall data set and remove missing entries from the data. Separate the predictor and response variables into two tables.

load carsmall
carData = table(Cylinders,Displacement,Horsepower,Weight,MPG);
R = rmmissing(carData);
X = R(:,["Cylinders","Displacement","Horsepower","Weight"]);
Y = R(:,"MPG");

Use the learn object function to train the regressionEnsembleComponent using the car data.

component = learn(component,X,Y)

component = 
  regressionEnsembleComponent with properties:

            Name: "RegressionEnsemble"
          Inputs: ["Predictors"    "Response"]
       InputTags: [1 2]
         Outputs: ["Predictions"    "Loss"]
      OutputTags: [1 0]

   
Learnables (HasLearned = true)
    TrainedModel: [1×1 classreg.learning.regr.CompactRegressionEnsemble]

   
Structural Parameters (locked)
      UseWeights: 0

   
Learn Parameters (locked)
          Method: 'Bag'


Show all parameters

Note that the HasLearned property is set to true, which indicates that the software trained the regression ensemble model TrainedModel. You can use component to predict response values for new data using the run object function.

Version History

Introduced in R2026a