Categories &

Functions List

Function Reference: fitcgam

statistics: Mdl = fitcgam (X, Y)
statistics: Mdl = fitcgam (…, name, value)

Fit a Generalized Additive Model (GAM) for binary classification.

Mdl = fitcgam (X, Y) returns a GAM classification model, Mdl, with X being the predictor data, and Y the binary class labels of observations in X.

  • X must be a N×P numeric matrix of predictor data where rows correspond to observations and columns correspond to features or variables.
  • Y is N×1 numeric vector containing binary class labels, typically 0 or 1.

Mdl = fitcgam (…, name, value) returns a GAM classification model with additional options specified by Name-Value pair arguments listed below.

Model Parameters

NameValue
'FitMethod'A character vector selecting the weak learner, either 'boostedtrees' or 'splines'. The default is 'boostedtrees', which boosts one shallow decision tree per predictor and is the scheme MATLAB uses. 'splines' boosts a smoothing spline per predictor instead and is an Octave extension. The two take different options and an option meant for one is refused by the other rather than ignored, so the rows below say which engine each belongs to.
'PredictorNames'A cell array of character vectors specifying the names of the predictors. The length of this array must match the number of columns in X.
'ResponseName'A character vector specifying the name of the response variable.
'ClassNames'Names of the classes in the class labels, Y, used for fitting the Discriminant model. ClassNames are of the same type as the class labels in Y.
'Cost'A N×R numeric matrix containing misclassification cost for the corresponding instances in X where R is the number of unique categories in Y. If an instance is correctly classified into its category the cost is calculated to be 1, otherwise 0. cost matrix can be altered use Mdl.cost = somecost. default value cost = ones(rows(X),numel(unique(Y))).
'Formula'(spline option) A model specification given as a string in the form 'Y ~ terms' where Y represents the response variable and terms the predictor variables. The formula can be used to specify a subset of variables for training model. For example: 'Y ~ x1 + x2 + x3 + x4 + x1:x2 + x2:x3' specifies four linear terms for the first four columns of for predictor data, and x1:x2 and x2:x3 specify the two interaction terms for 1st-2nd and 3rd-4th columns respectively. Only these terms will be used for training the model, but X must have at least as many columns as referenced in the formula. If Predictor Variable names have been defined, then the terms in the formula must reference to those. When 'formula' is specified, all terms used for training the model are referenced in the IntMatrix field of the obj class object as a matrix containing the column indexes for each term including both the predictors and the interactions used.
'Interactions'A logical matrix, a positive integer scalar, or the string 'all' for defining the interactions between predictor variables. When given a logical matrix, it must have the same number of columns as X and each row corresponds to a different interaction term combining the predictors indexed as true. Each interaction term is appended as a column vector after the available predictor column in X. When 'all' is defined, then all possible combinations of interactions are appended in X before training. At the moment, parsing a positive integer has the same effect as the 'all' option. When 'interactions' is specified, only the interaction terms appended to X are referenced in the IntMatrix field of the obj class object.
'Knots'(spline option) A scalar or a row vector with the same columns as X. It defines the knots for fitting a polynomial when training the GAM. As a scalar, it is expanded to a row vector. The default value is 5, hence expanded to ones (1, columns (X)) * 5. You can parse a row vector with different number of knots for each predictor variable to be fitted with, although not recommended.
'Order'(spline option) A scalar or a row vector with the same columns as X. It defines the order of the polynomial when training the GAM. As a scalar, it is expanded to a row vector. The default values is 3, hence expanded to ones (1, columns (X)) * 3. You can parse a row vector with different number of polynomial order for each predictor variable to be fitted with, although not recommended.
'DoF'(spline option) A scalar or a row vector with the same columns as X. It defines the degrees of freedom for fitting a polynomial when training the GAM. As a scalar, it is expanded to a row vector. The default value is 8, hence expanded to ones (1, columns (X)) * 8. You can parse a row vector with different degrees of freedom for each predictor variable to be fitted with, although not recommended.

Source Code: fitcgam

The rows above marked as spline options require 'FitMethod', 'splines'. The remaining options belong to the boosted-tree engine and require 'FitMethod', 'boostedtrees', which is the default.

NameValue
'NumTreesPerPredictor'A positive integer, the number of boosting rounds of the predictor phase. It is a budget rather than a count: a fit that stops improving ends earlier and reports so. The default is 300.
'NumTreesPerInteraction'A positive integer, the same budget for the interaction phase. The default is 100.
'MaxNumSplitsPerPredictor'A positive integer, the largest number of splits any one predictor tree may make. The default is 1, which makes each tree a stump.
'MaxNumSplitsPerInteraction'The same limit for a tree over a pair of predictors. The default is 4.
'InitialLearnRateForPredictors'A value greater than 0 and at most 1, the step a round of the predictor phase starts at. A round that fails to improve the fit is retried at half the step, so this is an initial value rather than a fixed one. The default is 1.
'InitialLearnRateForInteractions'The same for the interaction phase. The default is 1.
'MaxPValue'A value between 0 and 1. A candidate pair of predictors is kept only if its interaction test gives a p-value no larger than this. The default is 1, which keeps every pair asked for.
'Verbose'A non-negative integer. Greater than zero prints a trace of the fit. The default is 0.
'NumPrint'A positive integer, how often the trace reports: the first round and then every NumPrint rounds. The default is 10.

Source Code: fitcgam

You can parse either a 'Formula' or an 'Interactions' optional parameter. Parsing both parameters will result an error. Accordingly, you can only pass up to two parameters among 'Knots', 'Order', and 'DoF' to define the required polynomial for training the GAM model.

See also: ClassificationGAM

Source Code: fitcgam

Train a GAM classifier for binary classification using specific data and plot the decision boundaries.

Define specific data

 X = [1, 2; 2, 3; 3, 3; 4, 5; 5, 5; ...
     6, 7; 7, 8; 8, 8; 9, 9; 10, 10];
 Y = [0; 0; 0; 0; 0; ...
     1; 1; 1; 1; 1];

Train the GAM model

 obj = fitcgam (X, Y, 'Interactions', 'all');

Create a grid of values for prediction

 x1 = [min(X(:,1)):0.1:max(X(:,1))];
 x2 = [min(X(:,2)):0.1:max(X(:,2))];
 [x1G, x2G] = meshgrid (x1, x2);
 XGrid = [x1G(:), x2G(:)];
 pred = predict (obj, XGrid);

Plot decision boundaries and data points

 predNumeric = str2double (pred);
 gidx = predNumeric > 0.5;
 figure
 scatter (XGrid(gidx,1), XGrid(gidx,2), 'markerfacecolor', 'magenta');
 hold on
 scatter (XGrid(! gidx,1), XGrid(! gidx,2), 'markerfacecolor', 'red');
 plot (X(Y == 0, 1), X(Y == 0, 2), 'ko', X(Y == 1, 1), X(Y == 1, 2), 'kx');
 xlabel ('Feature 1');
 ylabel ('Feature 2');
 title ('Generalized Additive Model (GAM) Decision Boundary');
 legend ({'Class 1 Region', 'Class 0 Region', ...
       'Class 1 Samples', 'Class 0 Samples'}, ...
       'location', 'northwest')
 axis tight
 hold off
plotted figure