Skip to contents

Build prediction grids for distributional-parameter summaries

Source: R/prediction-grid.R
prediction_grid.Rd

prediction_grid() creates explicit newdata grids for predict_parameters() and marginal_parameters(). It does not fit, predict, average, or plot. The helper records which terms were varied, which terms were fixed, and which grid rule was used so later interpretation and plotting helpers do not hide those choices.

Usage

prediction_grid(object, ...)

# S3 method for class 'drmTMB'
prediction_grid(
  object,
  focal = NULL,
  at = list(),
  condition = list(),
  margin = c("mean_reference", "empirical"),
  n = 50L,
  weights = c("equal", "proportional"),
  ...
)

Arguments

object

A drmTMB fit that retained its fitted model data.

...

Reserved for future options.

focal

Optional character vector of predictor names to vary.

at

Optional named list of values for focal predictors. Focal numeric predictors without an at entry use an evenly spaced sequence over the fitted range. Focal factors without an at entry use all fitted levels.

condition

Optional named list of non-focal predictors to hold at supplied values.

margin

Grid rule. "mean_reference" returns one row for each focal combination with nuisance predictors set to reference values. "empirical" crosses focal combinations with the fitted model rows.

n

Number of points for automatically generated numeric focal grids.

weights

Metadata label for later marginalisation helpers. The current function records the choice but does not compute weighted summaries.

Value

A data frame with class drm_prediction_grid. The ordinary columns are valid newdata columns for the fitted model. Attribute "prediction_grid" stores focal_terms, conditioned_terms, margin, weights, grid_source, reference_terms, predictor_terms, n_source_rows, and n_grid_rows.

Details

With margin = "mean_reference", focal terms vary across the requested grid and all other predictors are set to reference values: numeric predictors use their fitted-row mean, factors use their first fitted level, character predictors use their first fitted value with fitted levels preserved, and logical predictors use their first fitted value unless supplied through condition.

With margin = "empirical", focal terms are crossed with the fitted model rows. Non-focal predictors keep their observed fitted-row values unless supplied through condition. This produces a counterfactual-style grid that can be passed to marginal_parameters(..., by = focal_terms) for simple empirical averaging.

Examples

dat <- data.frame(
  y = c(0.2, 0.5, 1.1, 1.4, 1.8, 2.2),
  x = c(-1, -0.5, 0, 0.5, 1, 1.5),
  habitat = factor(rep(c("reef", "kelp"), each = 3))
)
fit <- drmTMB(bf(y ~ x + habitat, sigma ~ x), data = dat)

grid <- prediction_grid(
  fit,
  focal = "x",
  at = list(x = c(0, 1)),
  condition = list(habitat = "reef")
)
predict_parameters(fit, newdata = grid, dpar = c("mu", "sigma"))
#>   row row_label  dpar            component     type     estimate   conf.status
#> 1   1         1    mu             location response 1.098369e+00 not_requested
#> 2   2         2    mu             location response 1.898370e+00 not_requested
#> 3   1         1 sigma distributional-scale response 2.033703e-03 not_requested
#> 4   2         2 sigma distributional-scale response 4.455709e-07 not_requested
#>   interval_source x habitat
#> 1   not_available 0    reef
#> 2   not_available 1    reef
#> 3   not_available 0    reef
#> 4   not_available 1    reef