Statistics: fitrgam

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

| Name | Value
--- | --- | ---
| `"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]