Categories &

Functions List

Function Reference: fitrgam

statistics: obj = fitrgam (X, Y)
statistics: obj = fitrgam (X, Y, name, value)

Fit a Generalized Additive Model (GAM) for regression.

obj = fitrgam (X, Y) returns an object of class RegressionGAM, with matrix X containing the predictor data and vector Y containing the continuous response data.

  • X must be a N×P numeric matrix of input data where rows correspond to observations and columns correspond to features or variables. X will be used to train the GAM model.
  • Y must be N×1 numeric vector containing the response data corresponding to the predictor data in X. Y must have same number of rows as X.

obj = fitrgam (…, name, value) returns an object of class RegressionGAM with additional properties specified by Name-Value pair arguments listed below.

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.
'predictors'Predictor Variable names, specified as a row vector cell of strings with the same length as the columns in X. If omitted, the program will generate default variable names (x1, x2, ..., xn) for each column in X.
'responsename'Response Variable Name, specified as a string. If omitted, the default value is '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.
'tol'(spline option) a positive scalar to set the tolerance for convergence during training. By default, it is set to 1e-3.

Source Code: fitrgam

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

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: RegressionGAM, regress, regress_gp

Source Code: fitrgam 

 rng (42);

Train a RegressionGAM Model for synthetic values

 f1 = @(x) cos (3 *x);
 f2 = @(x) x .^ 3;

generate x1 and x2 for f1 and f2

 x1 = 2 * rand (50, 1) - 1;
 x2 = 2 * rand (50, 1) - 1;

calculate y

 y = f1(x1) + f2(x2);

add noise

 y = y + y .* 0.2 .* rand (50,1);
 X = [x1, x2];

create an object

 a = fitrgam (X, y, 'FitMethod', 'splines', 'tol', 1e-3)
a =

  RegressionGAM

             ResponseName: 'Y'
          NumObservations: 50
            NumPredictors: 2
        ResponseTransform: 'none'
                Intercept: 0.0671178
                    Knots: [5 5]
                    Order: [3 3]
                      Tol: 0.001