Evaluate smooths at covariate values — smooth

Evaluate a smooth at a grid of evenly spaced value over the range of the covariate associated with the smooth. Alternatively, a set of points at which the smooth should be evaluated can be supplied. smooth_estimates() is a new implementation of evaluate_smooth(), and replaces that function, which has been removed from the package.

Usage

smooth_estimates(object, ...)

# S3 method for class 'gam'
smooth_estimates(
  object,
  select = NULL,
  smooth = deprecated(),
  n = 100,
  n_2d = 50,
  n_3d = 16,
  n_4d = 4,
  data = NULL,
  unconditional = FALSE,
  frequentist = FALSE,
  overall_uncertainty = TRUE,
  dist = NULL,
  unnest = TRUE,
  partial_match = FALSE,
  clip = FALSE,
  envir = NULL,
  ...
)

Arguments

object: an object of class "gam" or "gamm".
...: arguments passed to other methods.
select: character; select which smooth's posterior to draw from. The default (NULL) means the posteriors of all smooths in model will be sampled from. If supplied, a character vector of requested terms.
smooth: Use select instead.
n: numeric; the number of points over the range of the covariate at which to evaluate a univariate smooth.
n_2d: numeric; the number of points along each of the first two axes of a smooth surface, including surface panels of higher-dimensional smooths. The default is 50 in plotting and plot-preparation functions. If NULL, use n instead. Ignored when evaluation data are supplied. Factor levels are retained, and curves with only one continuous covariate use n.
n_3d, n_4d: numeric; the number of points along the third axis of a 3D smooth (n_3d, default 16), or each axis after the first two for smooths of dimension four or higher (n_4d, default 4). If NULL, use n for those axes. The first two surface axes use n_2d.
data: a data frame of covariate values at which to evaluate the smooth.
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?
dist: numeric; if greater than 0, this is used to determine when a location is too far from data to be plotted when plotting 2-D smooths. The data are scaled into the unit square before deciding what to exclude, and dist is a distance within the unit square. See mgcv::exclude.too.far() for further details.
unnest: logical; unnest the smooth objects?
partial_match: logical; in the case of character select, should select match partially against smooths? If partial_match = TRUE, select must only be a single string, a character vector of length 1.
clip: logical; should evaluation points be clipped to the boundary of a soap film smooth? The default is FALSE, which will return NA for any point that is deemed to lie outside the boundary of the soap film.
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.

Value

A data frame (tibble), which is of class "smooth_estimates".

Details

For explicit data, missing covariates needed by a smooth produce NA estimates and standard errors at those positions. Missing values in variables unrelated to that smooth do not discard its otherwise evaluable rows.

Raw data may contain x for a smooth such as s(log(x)); gratia evaluates the expression before constructing the prediction matrix. An evaluated column named "log(x)" can be supplied instead. When both are supplied, the raw inputs take precedence, except for stored model frames and grids prepared by gratia. Automatic grids are evenly spaced in the smooth coordinate (log(x)), and returned coordinate columns retain that name.

Stored evaluated columns allow automatic plotting even when a local function used to fit the model is no longer available. Evaluating that function at new raw data requires envir; training values are never substituted for new observations. Arbitrary transformations are not inverted to recover raw data.

Examples

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

## evaluate all smooths
smooth_estimates(m1)
#> # A tibble: 400 x 9
#>    .smooth .type .by   .estimate      .se         x0    x1    x2    x3
#>    <chr>   <chr> <chr>     <dbl>    <dbl>      <dbl> <dbl> <dbl> <dbl>
#>  1 s(x0)   TPRS  NA    -0.966542 0.316118 0.00710904    NA    NA    NA
#>  2 s(x0)   TPRS  NA    -0.925391 0.297170 0.0171157     NA    NA    NA
#>  3 s(x0)   TPRS  NA    -0.884233 0.279256 0.0271224     NA    NA    NA
#>  4 s(x0)   TPRS  NA    -0.843050 0.262594 0.0371291     NA    NA    NA
#>  5 s(x0)   TPRS  NA    -0.801824 0.247376 0.0471358     NA    NA    NA
#>  6 s(x0)   TPRS  NA    -0.760536 0.233728 0.0571425     NA    NA    NA
#>  7 s(x0)   TPRS  NA    -0.719175 0.221701 0.0671492     NA    NA    NA
#>  8 s(x0)   TPRS  NA    -0.677736 0.211261 0.0771559     NA    NA    NA
#>  9 s(x0)   TPRS  NA    -0.636220 0.202303 0.0871626     NA    NA    NA
#> 10 s(x0)   TPRS  NA    -0.594641 0.194685 0.0971693     NA    NA    NA
#> # i 390 more rows

## or selected smooths
smooth_estimates(m1, select = c("s(x0)", "s(x1)"))
#> # A tibble: 200 x 7
#>    .smooth .type .by   .estimate      .se         x0    x1
#>    <chr>   <chr> <chr>     <dbl>    <dbl>      <dbl> <dbl>
#>  1 s(x0)   TPRS  NA    -0.966542 0.316118 0.00710904    NA
#>  2 s(x0)   TPRS  NA    -0.925391 0.297170 0.0171157     NA
#>  3 s(x0)   TPRS  NA    -0.884233 0.279256 0.0271224     NA
#>  4 s(x0)   TPRS  NA    -0.843050 0.262594 0.0371291     NA
#>  5 s(x0)   TPRS  NA    -0.801824 0.247376 0.0471358     NA
#>  6 s(x0)   TPRS  NA    -0.760536 0.233728 0.0571425     NA
#>  7 s(x0)   TPRS  NA    -0.719175 0.221701 0.0671492     NA
#>  8 s(x0)   TPRS  NA    -0.677736 0.211261 0.0771559     NA
#>  9 s(x0)   TPRS  NA    -0.636220 0.202303 0.0871626     NA
#> 10 s(x0)   TPRS  NA    -0.594641 0.194685 0.0971693     NA
#> # i 190 more rows

# parallel processing of smooths
if (requireNamespace("mirai") && requireNamespace("carrier")) {
  library("mirai")
  daemons(2)                          # only low for CRAN requirements
  smooth_estimates(m1)
}
#> Loading required namespace: carrier
#> # A tibble: 400 x 9
#>    .smooth .type .by   .estimate      .se         x0    x1    x2    x3
#>    <chr>   <chr> <chr>     <dbl>    <dbl>      <dbl> <dbl> <dbl> <dbl>
#>  1 s(x0)   TPRS  NA    -0.966542 0.316118 0.00710904    NA    NA    NA
#>  2 s(x0)   TPRS  NA    -0.925391 0.297170 0.0171157     NA    NA    NA
#>  3 s(x0)   TPRS  NA    -0.884233 0.279256 0.0271224     NA    NA    NA
#>  4 s(x0)   TPRS  NA    -0.843050 0.262594 0.0371291     NA    NA    NA
#>  5 s(x0)   TPRS  NA    -0.801824 0.247376 0.0471358     NA    NA    NA
#>  6 s(x0)   TPRS  NA    -0.760536 0.233728 0.0571425     NA    NA    NA
#>  7 s(x0)   TPRS  NA    -0.719175 0.221701 0.0671492     NA    NA    NA
#>  8 s(x0)   TPRS  NA    -0.677736 0.211261 0.0771559     NA    NA    NA
#>  9 s(x0)   TPRS  NA    -0.636220 0.202303 0.0871626     NA    NA    NA
#> 10 s(x0)   TPRS  NA    -0.594641 0.194685 0.0971693     NA    NA    NA
#> # i 390 more rows