regressionGAMComponent

Pipeline component for generalized additive model (GAM) for regression

Since R2026a

expand all in page

    Description

    regressionGAMComponent is a pipeline component that creates a generalized additive model (GAM) for regression. The pipeline component uses the functionality of the fitrgam function during the learn phase to train the GAM regression model. The component uses the functionality of the predict and loss functions during the run phase to perform regression.

    Creation

    Syntax

    component = regressionGAMComponent
    component = regressionGAMComponent(Name=Value)

    Description

    component = regressionGAMComponent creates a pipeline component for a GAM regression model.

    example

    component = regressionGAMComponent(Name=Value) sets writable Properties using one or more name-value arguments. For example, you can specify the number of interaction terms, maximum p-value, and number of bins.

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

    Initial learning rate of the gradient boosting for the interaction terms, specified as a numeric scalar in the range (0,1]. The component uses this rate for the interaction terms throughout the training process.

    Training a model using a small learning rate requires more learning iterations, but often achieves better accuracy.

    Example: c = regressionGAMComponent(InitialLearnRateForInteractions=0.1)

    Example: c.InitialLearnRateForInteractions = 0.5

    Data Types: single | double

    Learning rate of the gradient boosting for the linear terms, specified as a numeric scalar in the range (0,1]. The component uses this rate for the linear terms throughout the training process.

    Training a model using a small learning rate requires more learning iterations, but often achieves better accuracy.

    Example: c = regressionGAMComponent(InitialLearnRateForPredictors=0.1)

    Example: c.InitialLearnRateForPredictors=0.5

    Data Types: single | double

    Number or list of the interaction terms to include in the candidate set S, specified as a nonnegative integer scalar, a logical matrix, or "all".

    • Nonnegative integer scalar — S includes the specified number of important interaction terms, which the component selects based on the p-values of the terms.

    • Logical matrix — S includes a list of the interaction terms specified by a t-by-p logical matrix, where t is the number of interaction terms, and p is the number of predictors. The number of predictors is determined by the first data argument of learn.

    • "all" — S includes all possible pairs of interaction terms.

    The component identifies the interaction terms in S whose p-values are not greater than MaxPValue and uses them to build a set of interaction trees.

    Example: c = regressionGAMComponent(Interactions="all")

    Example: c.Interactions = 5

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

    Maximum number of decision splits per interaction tree, specified as a positive integer scalar.

    Example: c = regressionGAMComponent(MaxNumSplitsPerInteraction=5)

    Example: c.MaxNumSplitsPerInteraction = 3

    Data Types: single | double

    Maximum number of decision splits per predictor tree, specified as a positive integer scalar.

    Example: c = regressionGAMComponent(MaxNumSplitsPerPredictor=5)

    Example: c.MaxNumSplitsPerPredictor = 3

    Data Types: single | double

    Maximum p-value for detecting interaction terms, specified as a numeric scalar in the range [0,1].

    The component first finds the candidate set S of interaction terms from Interactions. The component identifies the interaction terms whose p-values are not greater than MaxPValue and uses them to build a set of interaction trees.

    Example: c = regressionGAMComponent(MaxPValue=0.05)

    Example: c.MaxPValue = 0.1

    Data Types: single | double

    Number of bins for the numeric predictors, specified as a positive integer scalar or [] (empty).

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

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

    Example: c = regressionGAMComponent(NumBins=50)

    Example: c.NumBins = 100

    Data Types: single | double

    Number of trees per interaction term, specified as a positive integer scalar.

    NumTreesPerInteraction is equivalent to the number of gradient boosting iterations for the interaction terms for predictors. At each iteration, the component adds a set of interaction trees to the model, one tree for each interaction term.

    Example: c = regressionGAMComponent(NumTreesPerInteraction=500)

    Example: c.NumTreesPerInteraction = 250

    Data Types: single | double

    Number of trees per linear term, specified as a positive integer scalar.

    NumTreesPerPredictor is equivalent to the number of gradient boosting iterations for the linear terms for predictors. At each iteration, the component adds a set of predictor trees to the model, one tree for each linear term.

    Example: c = regressionGAMComponent(NumTreesPerPredictor=500)

    Example: c.NumTreesPerPredictor = 100

    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.

    Flag to include the interaction terms of the model, specified as 1 (true) or 0 (false).

    The default value is true if the Interactions property of TrainedModel contains interaction terms, and false otherwise.

    Example: c = regressionGAMComponent(IncludeInteractions=true)

    Example: c.IncludeInteractions = false

    Data Types: logical

    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 = regressionGAMComponent(LossFun=@LossFun)

    Example: c.LossFun = "mse"

    Data Types: char | string | function_handle

    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 = regressionGAMComponent(ResponseTransform=@(y)exp(y))

    Example: c.ResponseTransform = "exp"

    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 = regressionGAMComponent(Name="GAM")

    Example: c.Name = "GAMRegression"

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

    Example: c = regressionGAMComponent(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 = regressionGAMComponent(OutputTags=[0 1])

    Example: c.OutputTags=[1 2]

    Data Types: single | double

    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

    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.

    Trained model, returned as a CompactRegressionGAM model 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 regressionGAMComponent pipeline component.

    component = regressionGAMComponent
    component = 

  regressionGAMComponent with properties:

            Name: "RegressionGAM"
          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 regressionGAMComponent object that contains one learnable, TrainedModel. This property remains empty until you pass data to the component during the learn phase.

    To include all possible pairs of interaction terms, set the Interactions property of the component to "all".

    component.Interactions = "all";

    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 regressionGAMComponent using the car data.

    component = learn(component,X,Y)
    component = 
  regressionGAMComponent with properties:

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

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

   
Structural Parameters (locked)
      UseWeights: 0

   
Learn Parameters (locked)
    Interactions: 'all'


Show all parameters

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

    Version History

    Introduced in R2026a

    See Also

    | |