Skip to contents

Point-wise and simultaneous confidence intervals for smooths

Source: R/confint-methods.R, R/scam-methods.R
confint.gam.Rd

Calculates point-wise confidence or simultaneous intervals for the smooth terms of a fitted GAM.

Usage

# S3 method for class 'gam'
confint(
  object,
  parm,
  level = 0.95,
  data = newdata,
  n = 100,
  type = c("confidence", "simultaneous"),
  nsim = 10000,
  shift = FALSE,
  transform = FALSE,
  unconditional = FALSE,
  frequentist = FALSE,
  overall_uncertainty = TRUE,
  ncores = 1,
  partial_match = FALSE,
  ...,
  newdata = NULL
)

# S3 method for class 'gamm'
confint(object, ...)

# S3 method for class 'gamm4'
confint(object, ...)

# S3 method for class 'scam'
confint(
  object,
  parm = smooths(object),
  ...,
  unconditional = FALSE,
  overall_uncertainty = FALSE
)

Arguments

object

an object of class "gam" or "gamm".

parm

which parameters (smooth terms) are to be given intervals as a vector of terms. If missing, all parameters are considered, although this is not currently implemented.

level

numeric, 0 < level < 1; the confidence level of the point-wise or simultaneous interval. The default is 0.95 for a 95% interval.

data

data frame; new values of the covariates used in the model fit. The selected smooth(s) will be evaluated at the supplied values.

n

numeric; the number of points to evaluate smooths at.

type

character; the type of interval to compute. One of "confidence" for point-wise intervals, or "simultaneous" for simultaneous intervals. "credible" aliases "confidence", for approximate Bayesian credible intervals using the default covariance.

nsim

integer; the number of simulations used in computing the simultaneous intervals.

shift

logical; should the model intercept be added to the smooth? Only the intercept is added; other parametric effects, including factor effects associated with a factor by smooth, are excluded. For full fitted values and their confidence intervals, use fitted_values().

transform

logical; should the smooth be evaluated on a transformed scale? For generalised models, this involves applying the inverse of the link function used to fit the model. Alternatively, the name of, or an actual, function can be supplied to transform the smooth and it's confidence interval.

unconditional

logical; if TRUE (and only if frequentist == FALSE) then the bayesian smoothing parameter uncertainty-corrected covariance matrix is returned, if available. Whether it is available depends on which smoothness selection method was used to fit the model.

frequentist

logical; if FALSE, the default, the bayesian covariance matrix is returned, otherwise the frequentist covariance matrix.

overall_uncertainty

logical; should the uncertainty in the model constant term be included in the standard error of the evaluate values of the smooth?

ncores

number of cores for generating random variables from a multivariate normal distribution. Passed to mvnfast::rmvn(). Parallelization will take place only if OpenMP is supported (but appears to work on Windows with current R).

partial_match

logical; should matching parm use a partial match or an exact match? Can only be used if length(parm) is 1.

...

additional arguments passed to smooth_estimates(), including interval_method to select Gaussian, stored scasm bootstrap, or shape-enforced intervals, and shape_source to choose their initial source. simultaneous_method, simultaneous_domain, and tube_control request and configure continuous-interval tube bands; see simultaneous_bands.

newdata

DEPRECATED! data frame; containing new values of the covariates used in the model fit. The selected smooth(s) will be evaluated at the supplied values.

Value

a tibble with components:

  1. .smooth; character indicating to which term each row relates,

  2. .type; the type of smooth,

  3. .by the name of the by variable if a by smooth, NA otherwise,

  4. one or more vectors of values at which the smooth was evaluated, named as per the variables in the smooth,

  5. zero or more variables containing values of the by variable,

  6. .estimate; estimated value of the smooth,

  7. .se; standard error of the estimated value of the smooth,

  8. .crit; critical value for the 100 * level% confidence interval; NA for bootstrap limits.

  9. .lower_ci; lower limit of the confidence or simultaneous interval,

  10. .upper_ci; upper limit of the confidence or simultaneous interval,

Details

For SCAM fits, confint() returns intervals for smooth functions, with parm selecting smooth labels. It uses transformed-coefficient Gaussian uncertainty conditional on the fitted smoothing parameters. By default, intercept uncertainty is excluded. These intervals do not enforce shape constraints on their limits.

Note

overall_uncertainty applies to both pointwise and simultaneous intervals. Each simultaneous band covers the evaluation points of one fitted smooth by default, or its continuous domain with tube calibration; separate smooths do not form a joint coverage set. Native scasm fits default to overall_uncertainty = FALSE and use stored bootstrap draws for pointwise intervals when available, as in smooth_estimates(). Shifting and transforming a smooth preserves its interval limits, including asymmetric bootstrap limits. Shape-enforced intervals describe unshifted smooth components on the model scale; shift = TRUE and effect transformations are unsupported.

Author

Gavin L. Simpson

Examples

load_mgcv()
dat <- data_sim("eg1", n = 1000, dist = "normal", scale = 2, seed = 2)
mod <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat, method = "REML")

# new data to evaluate the smooths at, say over the middle 50% of range
# of each covariate
middle <- function(x, n = 50, coverage = 0.5) {
  v <- (1 - coverage) / 2
  q <- quantile(x, prob = c(0 + v, 1 - v), type = 8)
  seq(q[1], q[2], length = n)
}
new_data <- sapply(dat[c("x0", "x1", "x2", "x3")], middle)
new_data <- data.frame(new_data)

## point-wise interval for smooth of x2
ci <- confint(mod, parm = "s(x2)", type = "confidence", data = new_data)
ci
#> # A tibble: 50 x 9
#>    .smooth .type .by      x2 .estimate   .se .crit .lower_ci .upper_ci
#>    <chr>   <chr> <chr> <dbl>     <dbl> <dbl> <dbl>     <dbl>     <dbl>
#>  1 s(x2)   TPRS  NA     0.26       5.3  0.18   2.0       5.0       5.7
#>  2 s(x2)   TPRS  NA     0.27       5.1  0.18   2.0       4.8       5.5
#>  3 s(x2)   TPRS  NA     0.28       4.9  0.18   2.0       4.6       5.3
#>  4 s(x2)   TPRS  NA     0.29       4.6  0.18   2.0       4.3       5.0
#>  5 s(x2)   TPRS  NA     0.30       4.3  0.19   2.0       3.9       4.7
#>  6 s(x2)   TPRS  NA     0.32       4.0  0.19   2.0       3.6       4.3
#>  7 s(x2)   TPRS  NA     0.33       3.6  0.20   2.0       3.2       4.0
#>  8 s(x2)   TPRS  NA     0.34       3.2  0.20   2.0       2.9       3.6
#>  9 s(x2)   TPRS  NA     0.35       2.9  0.20   2.0       2.5       3.3
#> 10 s(x2)   TPRS  NA     0.36       2.5  0.19   2.0       2.1       2.9
#> # i 40 more rows