Diagnosis plots to evaluate a fitted neuralGAM model.

Produce a 2x2 diagnostic panel for a fitted neuralGAM model, mirroring the layout of gratia's appraise() for mgcv GAMs: (top-left) a QQ plot of residuals with optional simulation envelope, (top-right) a histogram of residuals, (bottom-left) residuals vs linear predictor \(\eta\), and (bottom-right) observed vs fitted values on the response scale.

diagnose(
  object,
  data = NULL,
  response = NULL,
  qq_method = c("uniform", "simulate", "normal"),
  n_uniform = 1000,
  n_simulate = 200,
  residual_type = c("deviance", "pearson", "quantile"),
  level = 0.95,
  point_col = "steelblue",
  point_alpha = 0.5,
  hist_bins = 30
)

Arguments

object

A fitted neuralGAM model.

data

Optional data.frame for out-of-sample evaluation. If supplied, response must name the response column.

response

Character scalar giving the response variable name in data (required when data is provided).

qq_method

Character; one of "uniform", "simulate", or "normal" for the QQ reference. See Details.

n_uniform

Integer; number of \(U(0,1)\) replicates for qq_method = "uniform".

n_simulate

Integer; number of simulated datasets for qq_method = "simulate" (also controls the QQ bands).

residual_type

One of "deviance", "pearson", or "quantile". Quantile (Dunn-Smyth) residuals are recommended for discrete families (binomial/poisson) because they are continuous and approximately standard normal under the fitted model, improving QQ diagnostics.

level

Numeric in (0,1); coverage level for the QQ bands when qq_method = "simulate".

point_col

Character; colour for points in scatter/histogram panels.

point_alpha

Numeric in (0,1); point transparency.

hist_bins

Integer; number of bins in the histogram.

Value

A patchwork object combining four ggplot2 plots. You can print it, add titles/themes, or extract individual panels if needed.

Details

The function uses predict.neuralGAM() to obtain the linear predictor (type = "link") and the fitted mean on the response scale (type = "response"). Residuals are computed internally for supported families; by default we use deviance residuals:

• Gaussian: \(r_i = y_i - \hat{\mu}_i\).

• Binomial: \(r_i = \mathrm{sign}(y_i-\hat{\mu}_i)\, \sqrt{2 w_i \{ y_i \log(y_i/\hat{\mu}_i) + (1-y_i)\log[(1-y_i)/(1-\hat{\mu}_i)] \}}\), with optional per-observation weights \(w_i\) (e.g., trials for proportions).

• Poisson: \(r_i = \mathrm{sign}(y_i-\hat{\mu}_i)\, \sqrt{2 w_i \{ y_i \log(y_i/\hat{\mu}_i) - (y_i-\hat{\mu}_i) \}}\), adopting the convention \(y_i \log(y_i/\hat{\mu}_i)=0\) when \(y_i=0\).

For Gaussian models, these plots diagnose symmetry, tail behaviour, and mean/variance misfit similar to standard GLM/GAM diagnostics. For non-Gaussian families (Binomial, Poisson), interpret shapes on the deviance scale, which is approximately normal under a well-specified model. For discrete data, randomized quantile (Dunn-Smyth) residuals are also available and often yield smoother QQ behaviour.

QQ reference methods. qq_method controls how theoretical quantiles are generated (as in gratia):

• "uniform" (default): draw \(U(0,1)\) and map through the inverse CDF of the fitted response distribution at each observation; convert to residuals and average the sorted curves over n_uniform draws. Fast and respects the mean-variance relationship.

• "simulate": simulate n_simulate datasets from the fitted model at the observed covariates, compute residuals, and average the sorted curves; also provides pointwise level bands on the QQ plot.

• "normal": use standard normal quantiles; a fallback when a suitable RNG or inverse CDF is unavailable.

For Poisson models, include offsets for exposure in the linear predictor (e.g., log(E)). The QQ methods use \(\hat{\mu}_i\) with qpois/rpois for "uniform"/"simulate", respectively.

Dependencies

Requires ggplot2 and patchwork.

References

Augustin, N.H., Sauleau, E.A., Wood, S.N. (2012). On quantile-quantile plots for generalized linear models. Computational Statistics & Data Analysis, 56, 2404-2409. https://doi.org/10.1016/j.csda.2012.01.026

Dunn, P.K., Smyth, G.K. (1996). Randomized quantile residuals. Journal of Computational and Graphical Statistics, 5(3), 236-244.

Author

Ines Ortega-Fernandez, Marta Sestelo