regressionLMComponent

R2026b

Pipeline component for regression using linear model

Since R2026b

Description

regressionLMComponent is a pipeline component that creates a linear regression model. The pipeline component uses the functionality of the fitlm 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 = regressionLMComponent

component = regressionLMComponent(Name=Value)

Description

component = regressionLMComponent creates a pipeline component for a linear regression model.

component = regressionLMComponent(Name=Value) sets writable Properties using one or more name-value arguments. For example, you can specify the robust weight function, 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 = regressionLMComponent(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.

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 = regressionLMComponent(Intercept=false)

Example: c.Intercept = true

Data Types: logical

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.

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

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

Data Types: single | double | char | string

RobustOpts — Robust fitting type

"off" (default) | "on" | string scalar | character vector | function handle | structure

Robust fitting type, specified as one of the following values.

• "off" — No robust fitting. The component uses ordinary least squares.

• "on" — The component performs fitting using the "bisquare" weight function with the default tuning constant.

• String scalar or character vector — Name of a robust fitting weight function from the table below. The component uses the corresponding default tuning constant specified in the table.

• Function handle — Custom weight function that accepts a vector r of scaled residuals, and returns a vector of weights the same size as r. The component uses a tuning constant of 1 for function handles.

• Structure — Structure with two fields, RobustWgtFun and Tune.

  • The RobustWgtFun field contains the name of a robust weight function from the table below or a function handle of a custom weight function.

  • The Tune field contains a tuning constant. If you do not set the Tune field, the component uses the corresponding default tuning constant.

Weight Function	Description	Default Tuning Constant
"andrews"	w = (abs(r)<pi) .* sin(r) ./ r	1.339
"bisquare"	w = (abs(r)<1) .* (1 - r.^2).^2 (also called biweight)	4.685
"cauchy"	w = 1 ./ (1 + r.^2)	2.385
"fair"	w = 1 ./ (1 + abs(r))	1.400
"huber"	w = 1 ./ max(1, abs(r))	1.345
"logistic"	w = tanh(r) ./ r	1.205
"ols"	Ordinary least squares (no weighting function)	None
"talwar"	w = 1 * (abs(r)<1)	2.795
"welsch"	w = exp(-(r.^2))	2.985

The value r in the weight functions is

r = resid/(tune*s*sqrt(1–h)),

where resid is the vector of residuals from the previous iteration, tune is the tuning constant, h is the vector of leverage values from a least-squares fit, and s is an estimate of the standard deviation of the error term given by

s = MAD/0.6745.

MAD is the median absolute deviation of the residuals from their median. The constant 0.6745 makes the estimate unbiased for the normal distribution. If the first data argument of learn has p columns, the component excludes the smallest p absolute deviations when computing the median.

For robust fitting, the component uses M-estimation to formulate estimating equations, and solves them using the method of Iteratively Reweighted Least Squares (IRLS).

Example: c = regressionLMComponent(RobustOpts="andrews")

Example: c.RobustOpts = "on"

Data Types: char | string | struct | function_handle

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 = regressionLMComponent(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

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

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

Example: c = regressionLMComponent(Name="LinearModel")

Example: c.Name = "LMRegression"

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 = regressionLMComponent(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 = regressionLMComponent(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 = regressionLMComponent(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 = regressionLMComponent(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 Regression Using Linear Model

Create a regressionLMComponent pipeline component.

component = regressionLMComponent

component = 
  regressionLMComponent with properties:

            Name: "RegressionLM"
          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 regressionLMComponent object that contains two learnables, Coefficients and TrainedModel. These properties remain empty until you pass data to the component during the learn phase.

To use a model that contains all products of predictors, set the ModelSpecification property of the component to "interactions".

component.ModelSpecification = "interactions";

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 regressionLMComponent object using the learn function.

component = learn(component,X,Y)

component = 
  regressionLMComponent with properties:

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

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

   
Structural Parameters (locked)
            UseWeights: 0

   
Learn Parameters (locked)
    ModelSpecification: "interactions"


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