classificationGAMComponent

Pipeline component for binary classification using generalized additive model (GAM)

Since R2026a

Description

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

Creation

Syntax

component = classificationGAMComponent

component = classificationGAMComponent(Name=Value)

Description

component = classificationGAMComponent creates a pipeline component for a generalized additive model for binary classification.

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

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

Cost — Misclassification cost

[0 1; 1 0] (default) | 2-by-2 numeric matrix | structure

Misclassification cost, specified as a 2-by-2 numeric matrix or a structure.

• If Cost is a 2-by-2 numeric matrix, Cost(i,j) is the cost of classifying a point into class j if its true class is i.

• If Cost is a structure S, it has two fields: S.ClassificationCosts, which contains the cost matrix; and S.ClassNames, which contains the group names and defines the class order of the rows and columns of the cost matrix.

Example: c = classificationGAMComponent(Cost=[0 1; 2 0])

Example: c.Cost = [0 2; 1 0]

Data Types: single | double | struct

InitialLearnRateForInteractions — Initial learning rate of gradient boosting for interaction terms

1 (default) | numeric scalar in (0,1]

Initial learning rate of the gradient boosting for interaction terms, specified as a numeric scalar in the interval (0,1]. For each boosting iteration for interaction trees, the component starts fitting with the initial learning rate. The component halves the learning rate until it finds a rate that improves the model fit.

Example: c = classificationGAMComponent(InitialLearnRateForInteractions=0.1)

Example: c.InitialLearnRateForInteractions = 0.5

Data Types: single | double

InitialLearnRateForPredictors — Initial learning rate of gradient boosting for linear terms

1 (default) | numeric scalar in (0,1]

Initial learning rate of the gradient boosting for linear terms, specified as a numeric scalar in the interval (0,1]. For each boosting iteration for predictor trees, the component starts fitting with the initial learning rate. The component halves the learning rate until it finds a rate that improves the model fit.

Example: c = classificationGAMComponent(InitialLearnRateForPredictors=0.1)

Example: c.InitialLearnRateForPredictors = 0.5

Data Types: single | double

Interactions — Number or list of interaction terms

0 (default) | nonnegative integer scalar | logical matrix | "all"

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

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

• List of interaction terms, specified as a logical matrix — S includes the 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 = classificationGAMComponent(Interactions="all")

Example: c.Interactions = 5

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

MaxNumSplitsPerInteraction — Maximum number of decision splits per interaction tree

4 (default) | positive integer scalar

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

Example: c = classificationGAMComponent(MaxNumSplitsPerInteraction=5)

Example: c.MaxNumSplitsPerInteraction = 3

Data Types: single | double

MaxNumSplitsPerPredictor — Maximum number of decision splits per predictor tree

1 (default) | positive integer scalar

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

Example: c = classificationGAMComponent(MaxNumSplitsPerPredictor=5)

Example: c.MaxNumSplitsPerPredictor = 3

Data Types: single | double

MaxPValue — Maximum p-value for detecting interaction terms

1 (default) | numeric scalar in [0,1]

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

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

Example: c = classificationGAMComponent(MaxPValue=0.05)

Example: c.MaxPValue = 0.1

Data Types: single | double

NumBins — Number of bins for numeric predictors

256 (default) | positive integer scalar | [] (empty)

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

• If you specify NumBins as a positive integer scalar, then the component bins every numeric predictor into at most NumBins equiprobable bins, and then grows trees on the bin indices instead of the original data.

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

Example: c = classificationGAMComponent(NumBins=50)

Example: c.NumBins = 100

Data Types: single | double

NumTreesPerInteraction — Number of trees per interaction term

100 (default) | positive integer scalar

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 = classificationGAMComponent(NumTreesPerInteraction=500)

Example: c.NumTreesPerInteraction = 250

Data Types: single | double

NumTreesPerPredictor — Number of trees per linear term

300 (default) | positive integer scalar

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

Example: c = classificationGAMComponent(NumTreesPerPredictor=500)

Example: c.NumTreesPerPredictor = 100

Data Types: single | double

Prior — Prior probabilities

"empirical" (default) | "uniform" | numeric vector | structure

Prior probabilities for each class, specified as a value in this table.

Value	Description
"empirical"	The class prior probabilities are the class relative frequencies. The class relative frequencies are determined by the second data argument of learn.
"uniform"	All class prior probabilities are equal to 1/K, where K is the number of classes.
numeric vector	A numeric vector with one value for each class. Each element is a class prior probability. The component normalizes the elements such that they sum to 1.
structure	A structure S with two fields: S.ClassNames contains a list of the class names. S.ClassProbs contains a vector of corresponding prior probabilities. The component normalizes the elements such that they sum to 1.

If you set UseWeights to true, the component renormalizes the weights to add up to the value of the prior probability in the respective class.

Example: c = classificationGAMComponent(Prior="uniform")

Example: c.Prior = "empirical"

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

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.

IncludeInteractions — Flag to include interaction terms

1 (true) | 0 (false)

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 = classificationGAMComponent(IncludeInteractions=true)

Example: c.IncludeInteractions = false

Data Types: logical

LossFun — Loss function

"binodeviance" | "classifcost" | "classiferror" | "exponential" | "hinge" | "logit" | "mincost" | "quadratic" | function handle

Loss function, specified as a built-in loss function name or a function handle.

This table lists the available built-in loss functions.

Value	Description
"binodeviance"	Binomial deviance
"classifcost"	Observed misclassification cost
"classiferror"	Misclassified rate in decimal
"exponential"	Exponential loss
"hinge"	Hinge loss
"logit"	Logistic loss
"mincost"	Minimal expected misclassification cost (for classification scores that are posterior probabilities)
"quadratic"	Quadratic loss

To specify a custom loss function, use function handle notation. For more information on custom loss functions, see LossFun.

The default value is "mincost" if the value of ScoreTransform is "logit". Otherwise, the default value is "classiferror".

Example: c = classificationGAMComponent(LossFun="classifcost")

Example: c.LossFun = "hinge"

Data Types: char | string | function_handle

ScoreTransform — Score transformation

"none" (default) | "doublelogit" | "invlogit" | "ismax" | "logit" | "identity" | "sign" | "symmetric" | "symmetricismax" | "symmetriclogit" | function handle

Score transformation, specified as a built-in function name or a function handle.

This table summarizes the available built-in score transform functions.

Value	Description
"doublelogit"	1/(1 + e–2x)
"invlogit"	log(x / (1 – x))
"ismax"	Sets the score for the class with the largest score to 1, and sets the scores for all other classes to 0
"logit"	1/(1 + e–x)
"none" or "identity"	x (no transformation)
"sign"	–1 for x < 0 0 for x = 0 1 for x > 0
"symmetric"	2x – 1
"symmetricismax"	Sets the score for the class with the largest score to 1, and sets the scores for all other classes to –1
"symmetriclogit"	2/(1 + e–x) – 1

To specify a custom score transform function, use function handle notation. The function must accept a matrix containing the original scores and return a matrix of the same size containing the transformed scores.

Example: c = classificationGAMComponent(ScoreTransform="logit")

Example: c.ScoreTransform = "symmetric"

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

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

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

Example: c = classificationGAMComponent(Name="GAM")

Example: c.Name = "GAMClassifier"

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 software adds the input port "Weights" to Inputs.

Example: c = classificationGAMComponent(Inputs=["X","Y"])

Example: c.Inputs = ["X1","Y1"]

Data Types: char | string | cell

Outputs — Names of output ports

["Predictions","Scores","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 = classificationGAMComponent(Outputs=["Class","ClassScore","LossVal"])

Example: c.Outputs = ["X","Y","Z"]

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 = classificationGAMComponent(InputTags=[0 1])

Example: c.InputTags = [1 0]

Data Types: single | double

OutputTags — Tags that enable automatic connection of component outputs

[1 0 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 = classificationGAMComponent(OutputTags=[1 0 4])

Example: c.OutputTags = [1 2 0]

Data Types: single | double

HasLearnables — Indicator for learnables

Read-only: 1 (true) (default)

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

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.

TrainedModel — Trained model

Read-only: CompactClassificationGAM model object

This property is read-only.

Trained model, returned as a CompactClassificationGAM model 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 GAM Classification

Create a ClassificationGAMComponent component.

component = classificationGAMComponent

component = 
  classificationGAMComponent with properties:

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

   
Learnables (HasLearned = false)
    TrainedModel: []

   
Structural Parameters (locked)
      UseWeights: 0


Show all parameters

component is a classificationGAMComponent 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".

comp.Interactions = "all";

Load the ionosphere data set and save the data in two tables.

load ionosphere
X = array2table(X);
Y = array2table(Y);

Train the classificationGAMComponent object.

component = learn(comp,X,Y)

component = 
  classificationGAMComponent with properties:

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

   
Learnables (HasLearned = true)
    TrainedModel: [1×1 classreg.learning.classif.CompactClassificationGAM]

   
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 generalized additive model TrainedModel. You can use component to classify new data using the run function.

Version History

Introduced in R2026a