Generate fitted values from a estimated GAM

Usage

fitted_values(object, ...)

# S3 method for class 'gam'
fitted_values(
  object,
  data = NULL,
  scale = c("response", "link", "linear predictor"),
  ci_level = 0.95,
  envir = NULL,
  ...,
  interval = c("confidence", "simultaneous"),
  n_sim = 10000,
  n_cores = 1,
  seed = NULL,
  unconditional = FALSE,
  interval_method = c("auto", "gaussian", "bootstrap")
)

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

# S3 method for class 'scam'
fitted_values(object, ..., unconditional = FALSE)

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

Arguments

object: a fitted model. Currently only models fitted by mgcv::gam() and mgcv::bam() are supported.
...: arguments passed to mgcv::predict.gam(). Note that type, newdata, and se.fit are already used and passed on to mgcv::predict.gam().
data: optional data frame of covariate values for which fitted values are to be returned.
scale: character; what scale should the fitted values be returned on? "linear predictor" is a synonym for "link" if you prefer that terminology.
ci_level: numeric; a value between 0 and 1 indicating the coverage of the credible interval.
envir: an optional environment supplying functions and constants used in model expressions. The available model formula environment is used when NULL. Covariate observations should be supplied in data.
interval: character; "confidence" (the default) gives pointwise intervals. "simultaneous" gives simultaneous intervals for predictions at the supplied covariate combinations.
n_sim: positive integer; number of coefficient draws used for simultaneous intervals. Ignored for pointwise intervals.
n_cores: positive integer; number of cores used by mvnfast::rmvn() for simultaneous intervals. Parallel execution requires OpenMP support.
seed: integer or NULL; optional random seed for simultaneous intervals. An explicit seed preserves the caller's random number state. With NULL, the current random number state is used and advanced.
unconditional: logical; include smoothing parameter uncertainty in the Bayesian covariance matrix, if available. Otherwise a warning is issued and the uncorrected covariance is used.
interval_method: character; "auto" uses stored scasm bootstrap draws for pointwise intervals when available and Gaussian intervals otherwise. "gaussian" requests covariance-based limits and "bootstrap" requires stored draws. Simultaneous bootstrap bands are unsupported. Shape-enforced intervals are available for smooth components through smooth_estimates().

Value

A tibble (data frame) whose first m columns contain either the data used to fit the model (if data was NULL), or the variables supplied to data. Four further columns are added:

.fitted: the fitted values on the specified scale,
.se: the standard error of the fitted values (always on the link scale),
.lower_ci, .upper_ci: the limits of the credible interval on the fitted values, on the specified scale.

Models fitted with certain families will include additional variables

mgcv::ocat() models: when scale = "response", the returned object will contain a row column and a category column, which indicate to which row of the data each row of the returned object belongs. Additionally, there will be nrow(data) * n_categories rows in the returned object; each row is the predicted probability for a single category of the response.

Details

Native scasm fits with stored bootstrap draws use mgcv's pointwise limits by default, including its svar.only correction for smoothing bias. interval_method = "gaussian" restores covariance-based limits. .se retains its existing covariance-based meaning. No replicates are generated. Bootstrap limits use existing scalar and location-scale parameter transformations. Unsupported nonlinear family outputs give an error for an explicit bootstrap request; automatic selection warns and uses Gaussian limits. Simultaneous bootstrap bands are not supported. Automatic simultaneous intervals warn when stored bootstrap draws are left unused. The interval_info attribute records the method and correction.

Formula offsets are included in predictions. Offsets supplied only through the fitting function's offset argument are omitted, including when data = NULL: this function evaluates explicit prediction rows internally. In contrast, fitted_samples() retains fitting-argument offsets when its data argument is NULL. Put offsets in the formula to evaluate them at new observations.

With data = NULL, results follow the model's na.action: na.exclude restores excluded observations as NA fitted values, standard errors and interval bounds; na.omit returns only retained observations. Covariates unavailable in the stored model frame are restored as typed NA values. .row indexes the fitting data after any subset was applied.

Supplying data requests predictions at those rows, independently of training exclusions. Missing responses do not prevent prediction. Missing required predictors produce NA results by default. An explicit na.action passed through ... is honoured; with na.omit, .row retains the positions in the supplied data, rather than numbering the remaining rows consecutively.

For supplied prediction data, an informative message identifies combinations of categorical predictor levels absent from the retained fitting observations. Predictions are unchanged: an unobserved combination is not necessarily non-estimable, particularly in additive models. Numeric-by-factor range extrapolation is not checked. Missing predictors and genuinely new factor levels retain their usual prediction behavior.

Simultaneous intervals jointly cover the model's underlying expected responses, or linear predictors on the link scale, at all valid covariate combinations evaluated in this call, with approximate posterior probability ci_level. The fitted values are estimates of these quantities. The combinations may include factor levels and need not form an ordered sequence, curve, or grid. This interpretation also applies to two predictions. With data = NULL, the simultaneous set comprises the retained fitting covariate combinations. Missing predictions do not enter this set. Coverage is not asserted outside this set or between its points. Separate calls define separate simultaneous sets. These are uncertainty intervals for model predictions, not prediction intervals for future observations.

Simultaneous intervals use joint Gaussian coefficient draws and a critical value based on the maximum absolute standardized deviation over the supplied rows. Their limits are computed on the link scale and transformed if scale = "response"; .se remains on the link scale. The simulation covariance may be positive semidefinite. Supported families are Gaussian, Poisson, binomial, Gamma, inverse Gaussian, quasi families, negative binomial, Tweedie, beta regression, and scaled t, fitted by gam() or bam() (including the gam component of a gamm() fit), and by scam(). For SCAM models, the Gaussian approximation uses transformed coefficients conditional on the fitted smoothing parameters. Other families support pointwise intervals only.

Response-scale simultaneous intervals support the identity, log, logit, probit, cloglog, cauchit, square-root, inverse, and inverse-squared links. Intervals crossing an inverse-link domain boundary are rejected; use scale = "link" for these intervals or for other links.

terms and exclude in ... retain mgcv::predict.gam() semantics and apply to both prediction and interval calculation. If terms are selected or excluded, intervals concern that selected quantity, not necessarily the full expected response. Use the link scale for sums of smooth contributions, and consider the intercept and offset treatment when selecting terms.

Note

For most families, regardless of the scale on which the fitted values are returned, the se component of the returned object is on the link (linear predictor) scale, not the response scale. An exception is the mgcv::ocat() family, for which the se is on the response scale if scale = "response".

Examples

load_mgcv()
sim_df <- data_sim("eg1", n = 400, dist = "normal", scale = 2, seed = 2)
m <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = sim_df, method = "REML")
fv <- fitted_values(m)
fv
#> # A tibble: 400 x 9
#>     .row       x0        x1         x2       x3  .fitted      .se .lower_ci
#>    <int>    <dbl>     <dbl>      <dbl>    <dbl>    <dbl>    <dbl>     <dbl>
#>  1     1 0.184882 0.617142  0.415244   0.132410  8.73875 0.354677   8.04360
#>  2     2 0.702374 0.569064  0.531439   0.365331  7.62581 0.337779   6.96378
#>  3     3 0.573326 0.153970  0.00324621 0.454532  3.12106 0.591862   1.96103
#>  4     4 0.168052 0.0348332 0.252100   0.537114 11.1124  0.402378  10.3237 
#>  5     5 0.943839 0.997953  0.155229   0.185495 14.0533  0.452947  13.1655 
#>  6     6 0.943475 0.835574  0.878840   0.449276  6.13080 0.364521   5.41635
#>  7     7 0.129159 0.586562  0.203511   0.256527 12.4838  0.355808  11.7864 
#>  8     8 0.833449 0.339117  0.583528   0.618458  6.25215 0.344700   5.57655
#>  9     9 0.468019 0.166883  0.804473   0.880744  4.21463 0.372003   3.48552
#> 10    10 0.549984 0.807410  0.264717   0.317747 15.5283  0.369999  14.8031 
#> # i 390 more rows
#> # i 1 more variable: .upper_ci <dbl>

# Simultaneous intervals for two arbitrary covariate combinations
fitted_values(m, data = sim_df[c(1, 20), ], interval = "simultaneous",
  n_sim = 1000, seed = 42)
#> # A tibble: 2 x 15
#>    .row       y        x0       x1       x2       x3       f       f0      f1
#>   <int>   <dbl>     <dbl>    <dbl>    <dbl>    <dbl>   <dbl>    <dbl>   <dbl>
#> 1     1 7.12834 0.184882  0.617142 0.415244 0.132410 8.38643 1.09743  3.43592
#> 2     2 2.93507 0.0749794 0.797900 0.874521 0.203225 5.57766 0.466765 4.93227
#> # i 6 more variables: f2 <dbl>, f3 <dbl>, .fitted <dbl>, .se <dbl>,
#> #   .lower_ci <dbl>, .upper_ci <dbl>

# A selected sum of smooth contributions on the link scale
fitted_values(m, data = sim_df[c(1, 20), ], scale = "link",
  terms = c("s(x2)", "s(x3)"), interval = "simultaneous",
  n_sim = 1000, seed = 42)
#> # A tibble: 2 x 15
#>    .row       y        x0       x1       x2       x3       f       f0      f1
#>   <int>   <dbl>     <dbl>    <dbl>    <dbl>    <dbl>   <dbl>    <dbl>   <dbl>
#> 1     1 7.12834 0.184882  0.617142 0.415244 0.132410 8.38643 1.09743  3.43592
#> 2     2 2.93507 0.0749794 0.797900 0.874521 0.203225 5.57766 0.466765 4.93227
#> # i 6 more variables: f2 <dbl>, f3 <dbl>, .fitted <dbl>, .se <dbl>,
#> #   .lower_ci <dbl>, .upper_ci <dbl>