regressionStepwiseLMComponent

R2026b

Pipeline component for stepwise regression with linear model

Since R2026b

Description

regressionStepwiseLMComponent is a pipeline component that creates a linear model using stepwise regression to add or remove predictors. The pipeline component uses the functionality of the stepwiselm function during the learn phase to train the linear model. The component uses the functionality of the predict function during the run phase to perform regression.

Creation

Syntax

component = regressionStepwiseLMComponent

component = regressionStepwiseLMComponent(Name=Value)

Description

component = regressionStepwiseLMComponent creates a pipeline component for a linear model using stepwise regression.

component = regressionStepwiseLMComponent(Name=Value) sets writable Properties using one or more name-value arguments. For example, you can specify the criterion to add or remove terms, model formula, and loss function.

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 = regressionStepwiseLMComponent(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.

Criterion — Criterion to add or remove terms

"sse" (default) | "aic" | "bic" | "rsquared" | "adjrsquared"

Criterion to add or remove terms, specified as one of these values:

• "sse" — p-value for an F-test of the change in the sum of squared error that results from adding or removing the term

• "aic" — Change in the value of the Akaike information criterion (AIC)

• "bic" — Change in the value of the Bayesian information criterion (BIC)

• "rsquared" — Increase in the value of R²

• "adjrsquared" — Increase in the value of adjusted R²

Example: c = regressionStepwiseLMComponent(Criterion="bic")

Example: c.Criterion = "rsquared"

Data Types: char | string

Intercept — Indicator for constant term

true or 1 (default) | false or 0

Indicator for the constant term, or intercept, specified as 1 (true) or 0 (false). If Intercept is true, the component includes the constant term in the model. If Intercept is false, the component removes the constant term from the model.

Use Intercept only when ModelSpecification is a character vector or string scalar, not a formula or matrix.

Example: c = regressionStepwiseLMComponent(Intercept=false)

Example: c.Intercept = true

Data Types: logical

Lower — Specification for terms that cannot be removed

"constant" (default) | string scalar | character vector | terms matrix

Specification for terms that cannot be removed from the model, specified as one of the options for ModelSpecification naming the model.

Example: c = regressionStepwiseLMComponent(Lower="linear")

Example: c.Lower = "constant"

Data Types: single | double | char | string

ModelSpecification — Model specification

"linear" (default) | string scalar or character vector naming the model | t-by-(p + 1) terms matrix | string scalar or character vector formula in the form "y ~ terms"

Model specification, specified as one of the following values.

• A string scalar or character vector containing the model name.

  Value	Model Description
  "constant"	Model contains only a constant (intercept) term
  "linear"	Model contains an intercept and linear term for each predictor
  "interactions"	Model contains an intercept, linear term for each predictor, and all products of pairs of distinct predictors (no squared terms)
  "purequadratic"	Model contains an intercept term and linear and squared terms for each predictor
  "quadratic"	Model contains an intercept term, linear and squared terms for each predictor, and all products of pairs of distinct predictors
  "polyijk"	Model is a polynomial with all terms up to degree i in the first predictor, degree j in the second predictor, and so on. Specify the maximum degree for each predictor by using numerals 0 through 9. The model contains interaction terms, but the degree of each interaction term does not exceed the maximum value of the specified degrees. For example, "poly13" has an intercept and x1, x2, x22, x23, x1*x2, and x1*x22 terms, where x1 and x2 are the first and second predictors, respectively.

• A t-by-(p + 1) terms matrix that specifies the terms in the model, where t is the number of terms, p is the number of predictor variables, and +1 accounts for the response variable. A terms matrix is convenient when the number of predictors is large and you want to generate the terms programmatically. For more information, see Terms Matrix.

• A string scalar or character vector formula in the form

  "y ~ terms",

  where y is the name of the response variable and terms are terms in Wilkinson notation. The variable names in terms must be variable names in the first data argument of learn. For more information, see Formula.

To specify the smallest or largest set of terms in the model, use the Upper and Lower learn parameters.

Example: c = regressionStepwiseLMComponent(ModelSpecification="constant")

Example: c.ModelSpecification = "y ~ x1 + x2 + x3"

Data Types: single | double | char | string

NSteps — Maximum number of steps

no limit (default) | positive integer

Maximum number of steps to take, specified as a positive integer. If you do not specify a value for NSteps, the component takes steps until the model is not improved by adding or removing a term.

Example: c = regressionStepwiseLMComponent(NSteps=5)

Example: c.NSteps = 10

Data Types: single | double

PEnter — Threshold for criterion to add term

numeric scalar

Threshold for the criterion to add a term, specified as a numeric scalar. If you do not specify a value for PEnter, the component uses the default value that corresponds to the value of Criterion.

Criterion	Default Value	Decision
"sse"	0.05	If the p-value of the F-statistic is less than PEnter (p-value to enter), add the term to the model.
"aic"	0	If the change in the AIC of the model is less than PEnter, add the term to the model.
"bic"	0	If the change in the BIC of the model is less than PEnter, add the term to the model.
"rsquared"	0.1	If the increase in the R-squared value of the model is greater than PEnter, add the term to the model.
"adjrsquared"	0	If the increase in the adjusted R-squared value of the model is greater than PEnter, add the term to the model.

To prevent forward stepwise regression, specify PEnter as a value that the component cannot achieve.

• When Criterion is "sse", "aic", or "bic", specify PEnter as –Inf.

• When Criterion is "rsquared" or "adjrsquared", specify PEnter as Inf.

Example: c = regressionStepwiseLMComponent(PEnter=0.075)

Example: c.PEnter = 0

Data Types: single | double

PRemove — Threshold for criterion to remove term

numeric scalar

Threshold for the criterion to remove a term, specified as a numeric scalar. If you do not specify a value for PRemove, the component uses the default value that corresponds to the value of Criterion.

Criterion	Default Value	Decision
"sse"	0.10	If the p-value of the F-statistic is greater than PRemove (p-value to remove), remove the term from the model.
"aic"	0.01	If the change in the AIC of the model is greater than PRemove, remove the term from the model.
"bic"	0.01	If the change in the BIC of the model is greater than PRemove, remove the term from the model.
"rsquared"	0.05	If the increase in the R-squared value of the model is less than PRemove, remove the term from the model.
"adjrsquared"	-0.05	If the increase in the adjusted R-squared value of the model is less than PRemove, remove the term from the model.

At each step, the component also checks whether a term is redundant (linearly dependent) with other terms in the current model. If any term is redundant, the component removes the term, regardless of the criterion value.

To prevent backward stepwise regression, specify PRemove as a value that the component cannot achieve.

• When Criterion is "sse", "aic", or "bic", specify PRemove as Inf.

• When Criterion is "rsquared" or "adjrsquared", specify PRemove as –Inf.

Example: c = regressionStepwiseLMComponent(PRemove=0.05)

Example: c.PRemove = 0.01

Data Types: single | double

Upper — Specification for largest set of terms in fit

"interactions" (default) | string scalar | character vector | terms matrix

Specification for the largest set of terms in the fit, specified as one of the options for ModelSpecification naming the model.

Example: c = regressionStepwiseLMComponent(Upper="quadratic")

Example: c.Upper = "interactions"

Data Types: single | double | 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" or a function handle.

If LossFun is "mse", the component computes the weighted mean squared error.

To specify a custom loss function, use function handle notation. Your function must have this signature

lossvalue = lossfun(Y,Yhat,W)

where lossvalue is a numeric scalar, Y is a vector of observed responses, Yhat is a vector of predicted responses, and W is a numeric vector of observation weights.

Example: c = regressionStepwiseLMComponent(LossFun=@lossfun)

Example: c.LossFun = "mse"

Data Types: char | string | function_handle

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

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

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

Example: c = regressionStepwiseLMComponent(Name="StepwiseLinearModel")

Example: c.Name = "StepwiseLM"

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 = regressionStepwiseLMComponent(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 = regressionStepwiseLMComponent(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 component adds a third input tag to InputTags.

Example: c = regressionStepwiseLMComponent(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 = regressionStepwiseLMComponent(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 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.

Coefficients — Coefficient values

Read-only: table

This property is read-only.

Coefficient values, returned as a table. Coefficients contains one row for each coefficient and these columns:

• Estimate — Estimated coefficient value

• SE — Standard error of the estimate

• tStat — t-statistic for a two-sided test with the null hypothesis that the coefficient is zero

• pValue — p-value for the t-statistic

TrainedModel — Trained model

Read-only: LinearModel object

This property is read-only.

Trained model, returned as a LinearModel 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 Stepwise Regression

Create a regressionStepwiseLMComponent pipeline component.

component = regressionStepwiseLMComponent

component = 
  regressionStepwiseLMComponent with properties:

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

   
Learnables (HasLearned = false)
    Coefficients: []
    TrainedModel: []

   
Structural Parameters (locked)
      UseWeights: 0


Show all parameters

component is a regressionStepwiseLMComponent object that contains two learnables, Coefficients and TrainedModel. These properties remain empty until you pass data to the component during the learn phase.

To stop adding or removing terms after a maximum of five steps, set the NSteps property of the component to 5.

component.NSteps = 5;

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(Weight,Horsepower,Acceleration,MPG);
R = rmmissing(carData);
X = R(:,["Weight","Horsepower","Acceleration"]);
Y = R(:,"MPG");

Train the regressionStepwiseLMComponent object using the learn function.

component = learn(component,X,Y)

component = 
  regressionStepwiseLMComponent with properties:

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

   
Learnables (HasLearned = true)
    Coefficients: [4×4 table]
    TrainedModel: [1×1 LinearModel]

   
Structural Parameters (locked)
      UseWeights: 0

   
Learn Parameters (locked)
          NSteps: 5


Show all parameters

Note that the HasLearned property is set to true, which indicates that the software trained the linear model TrainedModel and set the coefficient values in Coefficients. You can use component to predict response values for new data using the run function.

More About

Terms Matrix

A terms matrix T is a t-by-(p + 1) matrix that specifies the terms in a model, where t is the number of terms, p is the number of predictor variables, and +1 accounts for the response variable. The value of T(i,j) is the exponent of variable j in term i.

For example, suppose that the first data argument of learn includes three predictor variables, x1, x2, and x3, and the second data argument contains the response variable y. Each row of T represents one term:

• [0 0 0 0] — Constant term (intercept)

• [0 1 0 0] — x2; equivalently, x1^0 * x2^1 * x3^0

• [1 0 1 0] — x1*x3

• [2 0 0 0] — x1^2

• [0 1 2 0] — x2*(x3^2)

The 0 at the end of each term represents the response variable y.

Formula

A formula for model specification is a character vector or string scalar of the form "y ~ terms".

• y is the response name.

• terms represents the predictor terms in a model using Wilkinson Notation.

To represent the predictor and response variables, use the variable names of the first two data arguments of learn.

For example, if the first data argument contains the variables "x1","x2",...,"xn" and the second data argument contains the variable "y":

• "y ~ x1 + x2 + x3" specifies a three-variable linear model with an intercept.

• "y ~ x1 + x2 + x3 – 1" specifies a three-variable linear model without an intercept. Note that formulas include a constant (intercept) term by default. To exclude a constant term from the model, you must include –1 in the formula.

Version History

Introduced in R2026b