regressionGLMComponent

R2026b

Pipeline component for regression using generalized linear model

Since R2026b

Description

regressionGLMComponent is a pipeline component that creates a generalized linear regression model. The pipeline component uses the functionality of the fitglm function during the learn phase to train the generalized linear model. The component uses the functionality of the predict function during the run phase to perform regression.

Creation

Syntax

component = regressionGLMComponent

component = regressionGLMComponent(Name=Value)

Description

component = regressionGLMComponent creates a pipeline component for a generalized linear regression model.

example

component = regressionGLMComponent(Name=Value) sets writable Properties using one or more name-value arguments. For example, you can specify the distribution of the response variable, link function, and loss function.

Properties

expand all

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

`BinomialSize` — Number of trials for binomial distribution
`1` (default) | string scalar | character vector | numeric scalar | numeric vector

Number of trials for the binomial distribution (that is, the sample size), specified as a string scalar, character vector, numeric scalar, or numeric vector.

String scalar or character vector containing a variable name — The component uses the values in the specified variable as the number of trials for each observation.
Numeric scalar — All observations have the same specified number of trials.
Numeric vector the same length as the response variable — The component uses the values in the numeric vector as the number of trials for each corresponding observation.

This property is valid only when Distribution is "binomial".

Example: c = regressionGLMComponent(BinomialSize="X1")

Example: c.BinomialSize = 10

Data Types: single | double | char | string

`B0` — Initial values for coefficient estimates
numeric vector

Initial values for the coefficient estimates, specified as a numeric vector. The default values are initial fitted values derived from the input data.

Example: c = regressionGLMComponent(B0=[0.5 4 1 -0.3])

Example: c.B0 = [6 -3 0.5 2]

Data Types: single | double

`DispersionFlag` — Indicator to compute dispersion parameter
`false` or `0` (default) | `true` or `1`

Indicator to compute the dispersion parameter for binomial and Poisson distributions, specified as 0 (false) or 0 (true).

If DispersionFlag is true, the component estimates the dispersion parameter when computing standard errors. The estimated dispersion parameter value is the sum of squared Pearson residuals divided by the degrees of freedom for error (DFE).
If DispersionFlag is false, the component uses the theoretical value of 1 when computing standard errors.

This property is valid only when Distribution is "binomial" or "poisson". For other distributions, the component always estimates the dispersion.

Example: c = regressionGLMComponent(DispersionFlag=true)

Example: c.DispersionFlag = 0

Data Types: logical

`Distribution` — Distribution of response variable
`"normal"` (default) | `"binomial"` | `"poisson"` | `"gamma"` | `"inverse gaussian"`

Distribution of the response variable, specified as "normal", "binomial", "poisson", "gamma", or "inverse gaussian".

Example: c = regressionGLMComponent(Distribution="gamma")

Example: c.Distribution = "poisson"

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

Example: c.Intercept = true

Data Types: logical

`LikelihoodPenalty` — Penalty for likelihood estimate
`"none"` (default) | `"jeffreys-prior"`

Penalty for the likelihood estimate, specified as "none" or "jeffreys-prior".

If LikelihoodPenalty is "none", the component does not apply a penalty to the likelihood estimate.
If LikelihoodPenalty is "jeffreys-prior", the component uses Jeffreys prior to penalize the likelihood estimate.

For logistic models, setting LikelihoodPenalty to "jeffreys-prior" is called Firth's regression. Use this option to reduce the coefficient estimate bias when you have a small number of samples, or when you are performing binomial (logistic) regression on a separable data set.

Example: c = regressionGLMComponent(LikelihoodPenalty="jeffreys-prior")

Example: c.LikelihoodPenalty = "none"

Data Types: char | string

`Link` — Link function
canonical link function (default) | string scalar or character vector | numeric scalar | structure

Link function, specified as a link function name, numeric scalar, or structure.

Link Function Name	Link Function	Mean (Inverse) Function
`"identity"`	f(μ) = μ	μ = Xb
`"log"`	f(μ) = log(μ)	μ = exp(Xb)
`"logit"`	f(μ) = log(μ/(1 – μ))	μ = exp(Xb) / (1 + exp(Xb))
`"probit"`	f(μ) = Φ^–1(μ), where Φ is the cumulative distribution function of the standard normal distribution	μ = Φ(Xb)
`"comploglog"`	f(μ) = log(–log(1 – μ))	μ = 1 – exp(–exp(Xb))
`"reciprocal"`	f(μ) = 1/μ	μ = 1/(Xb)
`p` (a number)	f(μ) = μ^p	μ = Xb^1/p
`S` (a structure) with three fields. Each field contains a function handle that accepts a vector of inputs and returns a vector of the same size: `S.Link` — The link function `S.Inverse` — The inverse link function `S.Derivative` — The derivative of the link function	f(μ) = `S.Link`(μ)	μ = `S.Inverse`(Xb)

The link function defines the relationship f(μ) = X*b between the mean response μ and the linear combination of predictors X*b.

The default value of Link is the canonical link function based on the value of Distribution. For more information, see Canonical Link Function.

Example: c = regressionGLMComponent(Link="logit")

Example: c.Link = 2

Data Types: single | double | char | string | struct

`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 x₁, x₂, x₂², x₂³, x₁x₂, and x₁x₂² terms, where x₁ and x₂ 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 = regressionGLMComponent(ModelSpecification="constant")

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

Data Types: single | double | char | string

`MaxIter` — Maximum number of iterations
`100` (default) | positive integer

Maximum number of iterations, specified as a positive integer.

Example: c = regressionGLMComponent(MaxIter=50)

Example: c.MaxIter = 200

Data Types: single | double

`Offset` — Offset variable
`[]` (default) | string scalar | character vector | numeric vector

Offset variable in the model, specified as a string scalar of character vector containing a variable name in the first data argument of learn, or a numeric vector of the same length as the variable.

The component uses Offset as an additional predictor with a coefficient value fixed at 1. In other words, the formula for fitting is

f(μ)= Offset + X*b,

where f is the link function, μ is the mean response, and X*b is the linear combination of predictors X. The Offset predictor has coefficient 1.

Example: c = regressionGLMComponent(Offset="X1")

Example: c.Offset = "X2"

Data Types: single | double | char | string

`TolX` — Parameter termination tolerance
positive scalar

Parameter termination tolerance, specified as a positive scalar.

Example: c = regressionGLMComponent(TolX=1e-6)

Example: c.TolX = 1e-4

Data Types: single | double

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 = regressionGLMComponent(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
`"RegressionGLM"` (default) | character vector | string scalar

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

Example: c = regressionGLMComponent(Name="GeneralizedLinearModel")

Example: c.Name = "GLMRegression"

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 = regressionGLMComponent(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 = regressionGLMComponent(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 = regressionGLMComponent(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 = regressionGLMComponent(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: `GeneralizedLinearModel` object

This property is read-only.

Trained model, returned as a GeneralizedLinearModel 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

collapse all

Create and Train Pipeline Component for Regression Using Generalized Linear Model

Create a regressionGLMComponent pipeline component.

component = regressionGLMComponent

component = 
  regressionGLMComponent with properties:

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

To specify a gamma response variable distribution, set the Distribution property of the component to "gamma".

component.Distribution = "gamma";

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

component = learn(component,X,Y)

component = 
  regressionGLMComponent with properties:

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

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

   
Structural Parameters (locked)
      UseWeights: 0

   
Learn Parameters (locked)
    Distribution: "gamma"


Show all parameters

Note that the HasLearned property is set to true, which indicates that the software trained the generalized 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

expand all

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.

Canonical Link Function

The default link function for a generalized linear model is the canonical link function and depends on the value of Distribution.

Distribution	Canonical Link Function Name	Link Function	Mean (Inverse) Function
`"normal"`	`"identity"`	f(μ) = μ	μ = Xb
`"binomial"`	`"logit"`	f(μ) = log(μ/(1 – μ))	μ = exp(Xb) / (1 + exp(Xb))
`"poisson"`	`"log"`	f(μ) = log(μ)	μ = exp(Xb)
`"gamma"`	`–1`	f(μ) = 1/μ	μ = 1/(Xb)
`"inverse gaussian"`	`–2`	f(μ) = 1/μ²	μ = (Xb)^–1/2

Version History

Introduced in R2026b

regressionGLMComponent

Description

Creation

Syntax

Description

Properties

Structural Parameters

UseWeights — Observation weights flag false or 0 (default) | true or 1

Learn Parameters

BinomialSize — Number of trials for binomial distribution 1 (default) | string scalar | character vector | numeric scalar | numeric vector

B0 — Initial values for coefficient estimates numeric vector

DispersionFlag — Indicator to compute dispersion parameter false or 0 (default) | true or 1

Distribution — Distribution of response variable "normal" (default) | "binomial" | "poisson" | "gamma" | "inverse gaussian"

Intercept — Indicator for constant term true or 1 (default) | false or 0

LikelihoodPenalty — Penalty for likelihood estimate "none" (default) | "jeffreys-prior"

Link — Link function canonical link function (default) | string scalar or character vector | numeric scalar | structure

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"

MaxIter — Maximum number of iterations 100 (default) | positive integer

Offset — Offset variable [] (default) | string scalar | character vector | numeric vector

TolX — Parameter termination tolerance positive scalar

Run Parameters

LossFun — Loss function "mse" (default) | function handle

Component Properties

Name — Component identifier "RegressionGLM" (default) | character vector | string scalar

Inputs — Names of input ports ["Predictors","Response"] (default) | character vector | string array | cell array of character vectors

Outputs — Names of output ports ["Predictions","Loss"] (default) | character vector | string array | cell array of character vectors

InputTags — Tags that enable automatic connection of component inputs [1 2] (default) | nonnegative integer vector

OutputTags — Tags that enable automatic connection of component outputs [1 0] (default) | nonnegative integer vector

HasLearnables — Indicator for learnables Read-only: 1 (true) (default)

HasLearned — Indicator showing learning status of component Read-only: 0 (false) (default) | 1 (true)

Learnables

Coefficients — Coefficient values Read-only: table

TrainedModel — Trained model Read-only: GeneralizedLinearModel object

Object Functions

Examples

Create and Train Pipeline Component for Regression Using Generalized Linear Model

More About

Terms Matrix

Formula

Canonical Link Function

Version History

See Also

Topics

`UseWeights` — Observation weights flag
`false` or `0` (default) | `true` or `1`

`BinomialSize` — Number of trials for binomial distribution
`1` (default) | string scalar | character vector | numeric scalar | numeric vector

`B0` — Initial values for coefficient estimates
numeric vector

`DispersionFlag` — Indicator to compute dispersion parameter
`false` or `0` (default) | `true` or `1`

`Distribution` — Distribution of response variable
`"normal"` (default) | `"binomial"` | `"poisson"` | `"gamma"` | `"inverse gaussian"`

`Intercept` — Indicator for constant term
`true` or `1` (default) | `false` or `0`

`LikelihoodPenalty` — Penalty for likelihood estimate
`"none"` (default) | `"jeffreys-prior"`

`Link` — Link function
canonical link function (default) | string scalar or character vector | numeric scalar | structure

`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"`

`MaxIter` — Maximum number of iterations
`100` (default) | positive integer

`Offset` — Offset variable
`[]` (default) | string scalar | character vector | numeric vector

`TolX` — Parameter termination tolerance
positive scalar

`LossFun` — Loss function
`"mse"` (default) | function handle

`Name` — Component identifier
`"RegressionGLM"` (default) | character vector | string scalar

`Inputs` — Names of input ports
`["Predictors","Response"]` (default) | character vector | string array | cell array of character vectors

`Outputs` — Names of output ports
`["Predictions","Loss"]` (default) | character vector | string array | cell array of character vectors

`InputTags` — Tags that enable automatic connection of component inputs
`[1 2]` (default) | nonnegative integer vector

`OutputTags` — Tags that enable automatic connection of component outputs
`[1 0]` (default) | nonnegative integer vector

`HasLearnables` — Indicator for learnables
Read-only: `1` (`true`) (default)

`HasLearned` — Indicator showing learning status of component
Read-only: `0` (`false`) (default) | `1` (`true`)

`Coefficients` — Coefficient values
Read-only: table

`TrainedModel` — Trained model
Read-only: `GeneralizedLinearModel` object