compare_models.gam: Compare two fitted GAM models

In dScoreTest: Debiased Score Tests for Goodness of Fit and Model Comparison

Compare two fitted GAM models

Description

Debiased score test of the null fit.0 against the alternative fit.1, both fitted with mgcv::gam. GLM fit.1 is used to hunt for signal that fit.0 potentially misses.

Usage

## S3 method for class 'gam'
compare_models(
  fit.0,
  fit.1,
  hunt.style = "optimal",
  trim.outlier.hunt = TRUE,
  splits = c(0.5, 0.5),
  verbose = FALSE,
  ...
)

Arguments

fit.0	The null model as a fitted mgcv::gam object.
fit.1	The alternative model as a fitted mgcv::gam object. Must be a supermodel of fit.0: every predictor variable in fit.0's formula must also appear in fit.1's. fit.0 and fit.1 must be fit on the same rows in the same order.
hunt.style	Hunting algorithm with the following options. 'optimal': optimal hunting (default). See hunt_optimal. 'wls': a simpler hunting using weighted least squares, which can be less powerful. See hunt_wls.
trim.outlier.hunt	If TRUE (default), extreme values produced by the hunted function will be trimmed using Tukey's IQR rule.
splits	Numeric vector of length 2 or 3 giving the relative sizes of the sample splits; rescaled internally to sum to one. Default is c(0.5, 0.5), which splits data into two halves for hunt and test respectively. Though typically unnecessary in practice, one can also specify a 3-way split for hunt, debiasing and test respectively.
verbose	Default FALSE; information is printed if set to TRUE.
...	Unused; present for S3 generic/method consistency.

Details

Nesting is checked by predictor-variable name only, not by basis span: two models with the same predictors but different smooth specifications (e.g. s(x, k = 5) vs s(x, k = 20)) will pass the check. The test remains meaningful as long as fit.1's class contains the relevant alternative directions. Factor predictors, offset() terms, weights arguments, and multi-column responses are not supported.

Value

An object of class "dScoreTest": a list whose key elements are the debiased test statistic t.stat and the one-sided p-value p.val (right tail of the standard normal), along with the test-set score residuals, the hunted direction, and the call. It has print, summary and plot methods.

Examples

 set.seed(42)
 dat <- mgcv::gamSim(eg=1, n=500, dist="normal", scale=1)
 dat <- dat[, 1:5]
 
 # test fit.0 against fit.1: well-specified (f3 = 0) and should not be rejected
 fit.0  <- mgcv::gam(y ~ s(x0) + s(x1) + s(x2), data = dat)
 fit.1  <- mgcv::gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat)
 compare_models(fit.0, fit.1)
 plot(compare_models(fit.0, fit.1))
 anova(fit.0, fit.1)

 # mis-specified model: drops f2 and should be rejected
 fit.00 <- mgcv::gam(y ~ s(x0) + s(x1) + s(x3), data = dat)
 compare_models(fit.00, fit.1)
 plot(compare_models(fit.00, fit.1))
 compare_models(fit.00, fit.1, hunt.style="wls")
 anova(fit.00, fit.1)

dScoreTest documentation built on Sept. 3, 2026, 1:06 a.m.