Categories &

Functions List

Function Reference: fitrgam

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

Fit a Generalised 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
"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"a model specification given as a string in the form "Y ~ terms" where Y represents the reponse 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"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"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"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"a positive scalar to set the tolerance for covergence during training. By defaul, it is set to 1e-3.

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

Example: 1

  

 # 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, "tol", 1e-3)

a =

  RegressionGAM object with properties:

            BaseModel: [1x1 struct]
                  DoF: [1x2 double]
              Formula: [0x0 double]
            IntMatrix: [0x0 double]
         Interactions: [0x0 double]
                Knots: [1x2 double]
            ModelwInt: [0x0 double]
      NumObservations: [1x1 double]
        NumPredictors: [1x1 double]
                Order: [1x2 double]
       PredictorNames: [1x2 cell]
         ResponseName: Y
             RowsUsed: [50x1 double]
                  Tol: [1x1 double]
                    X: [50x2 double]
                    Y: [50x1 double]