regressionGLMComponent

R2026b

Pipeline component for regression using generalized linear model

Since R2026b

expand all in page

    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.

    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.

    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

    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

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

    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

    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 function, specified as a link function name, numeric scalar, or structure.

    Link Function NameLink FunctionMean (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μ = Xb1/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

    Model specification, specified as one of the following values.

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

      ValueModel 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 = regressionGLMComponent(ModelSpecification="constant")

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

    Data Types: single | double | char | string

    Maximum number of iterations, specified as a positive integer.

    Example: c = regressionGLMComponent(MaxIter=50)

    Example: c.MaxIter = 200

    Data Types: single | double

    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

    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.

    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.

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

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

    Example: c.Name = "GLMRegression"

    Data Types: char | string

    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

    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

    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

    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

    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

    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.

    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

    This property is read-only.

    Trained model, returned as a GeneralizedLinearModel object.

    Object Functions

    learnInitialize and evaluate pipeline or component
    runExecute pipeline or component for inference after learning
    resetReset pipeline or component
    seriesConnect components in series to create pipeline
    parallelConnect components or pipelines in parallel to create pipeline
    viewView diagram of pipeline inputs, outputs, components, and connections

    Examples

    collapse all

    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

    Version History

    Introduced in R2026b

    See Also

    |

    Topics