Fit a neuralGAM model

Fits a Generalized Additive Model where smooth terms are modeled by keras neural networks. In addition to point predictions, the model can optionally estimate uncertainty bands via Monte Carlo Dropout across forward passes.

neuralGAM(
  formula,
  data,
  family = "gaussian",
  num_units = 64,
  learning_rate = 0.001,
  activation = "relu",
  kernel_initializer = "glorot_normal",
  kernel_regularizer = NULL,
  bias_regularizer = NULL,
  bias_initializer = "zeros",
  activity_regularizer = NULL,
  loss = "mse",
  uncertainty_method = c("none", "epistemic"),
  alpha = 0.05,
  forward_passes = 100,
  dropout_rate = 0.1,
  validation_split = NULL,
  w_train = NULL,
  bf_threshold = 0.001,
  ls_threshold = 0.1,
  max_iter_backfitting = 10,
  max_iter_ls = 10,
  seed = NULL,
  verbose = 1,
  ...
)

Arguments

formula

Model formula. Smooth terms must be wrapped in s(...). You can specify per-term NN settings, e.g.: y ~ s(x1, num_units = 1024) + s(x3, num_units = c(1024, 512)).

data

Data frame containing the variables.

family

Response distribution: "gaussian", "binomial", "poisson".

num_units

Default hidden layer sizes for smooth terms (integer or vector). Mandatory unless every s(...) specifies its own num_units.

learning_rate

Learning rate for Adam optimizer.

activation

Activation function for hidden layers. Either a string understood by tf$keras$activations$get() or a function.

kernel_initializer, bias_initializer

Initializers for weights and biases.

kernel_regularizer, bias_regularizer, activity_regularizer

Optional Keras regularizers.

loss

Loss function to use. Can be any Keras built-in (e.g., "mse", "mae", "huber", "logcosh") or a custom function, passed directly to keras::compile().

uncertainty_method

Character string indicating the type of uncertainty to estimate. One of:

• "none" (default): no uncertainty estimation.

• "epistemic": MC Dropout for mean uncertainty (CIs)

alpha

Significance level for prediction intervals, e.g. 0.05 for 95% coverage.

forward_passes

Integer. Number of MC-dropout forward passes used when uncertainty_method %in% c("epistemic","both").

dropout_rate

Dropout probability in smooth-term NNs (0,1).

• During training: acts as a regularizer.

• During prediction (if uncertainty_method is "epistemic"): enables MC Dropout sampling.

validation_split

Optional fraction of training data used for validation.

w_train

Optional training weights.

bf_threshold

Convergence criterion of the backfitting algorithm. Defaults to 0.001

ls_threshold

Convergence criterion of the local scoring algorithm. Defaults to 0.1

max_iter_backfitting

An integer with the maximum number of iterations of the backfitting algorithm. Defaults to 10.

max_iter_ls

An integer with the maximum number of iterations of the local scoring Algorithm. Defaults to 10.

seed

Random seed.

verbose

Verbosity: 0 silent, 1 progress messages.

...

Additional arguments passed to keras::optimizer_adam().

Value

An object of class "neuralGAM", a list with elements including:

muhat

Numeric vector of fitted mean predictions (training data).

partial

Data frame of partial contributions \(g_j(x_j)\) per smooth term.

y

Observed response values.

eta

Linear predictor \(\eta = \eta_0 + \sum_j g_j(x_j)\).

lwr,upr

Lower/upper confidence interval bounds (response scale)

x

Training covariates (inputs).

model

List of fitted Keras models, one per smooth term (+ "linear" if present).

eta0

Intercept estimate \(\eta_0\).

family

Model family.

stats

Data frame of training/validation losses per backfitting iteration.

mse

Training mean squared error.

formula

Parsed model formula (via get_formula_elements()).

history

List of Keras training histories per term.

globals

Global hyperparameter defaults.

alpha

PI significance level (if trained with uncertainty).

build_pi

Logical; whether the model was trained with uancertainty estimation enabled

uncertainty_method

Type of predictive uncertainty used ("none","epistemic").

var_epistemic

Matrix of per-term epistemic variances (if computed).

Author

Ines Ortega-Fernandez, Marta Sestelo.

Examples

# \dontrun{

library(neuralGAM)
dat <- sim_neuralGAM_data()
train <- dat$train
test  <- dat$test

# Per-term architecture and confidence intervals
ngam <- neuralGAM(
  y ~ s(x1, num_units = c(128,64), activation = "tanh") +
       s(x2, num_units = 256),
  data = train,
  uncertainty_method = "epistemic",
  forward_passes = 10,
  alpha = 0.05
)
#> [1] "Initializing neuralGAM..."
#> Hint: To use tensorflow with `py_require()`, call `py_require("tensorflow")` at the start of the R session
#> Error in validate_activation(activation): Invalid activation 'tanh'. Use a valid tf.keras activation name or an R function.
ngam
#> Error: object 'ngam' not found
# }