Build prediction grids for distributional-parameter summaries

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

Use margin = "mean_reference" for adjusted predictions at named covariate values. Use margin = "empirical" when the target is an average over the fitted covariate distribution after replacing one or more focal predictors.

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

set.seed(20260523)
n <- 48
x <- seq(-1.5, 1.5, length.out = n)
habitat <- factor(rep(c("reef", "sand"), length.out = n))
eta <- 0.4 + 0.7 * x + ifelse(habitat == "reef", 0.25, -0.15)
sigma <- exp(-0.35 + 0.15 * x)
dat <- data.frame(y = eta + rnorm(n, sd = sigma), x = x, habitat = habitat)
fit <- drmTMB(bf(y ~ x + habitat, sigma ~ x), data = dat)

grid <- prediction_grid(
  fit,
  focal = "x",
  at = list(x = c(-1, 0, 1)),
  condition = list(habitat = "reef")
)
predict_parameters(fit, newdata = grid, dpar = c("mu", "sigma"), conf.int = TRUE)
#>   row row_label  dpar            component     type  estimate  std.error
#> 1   1         1    mu             location response 0.3675587 0.13449147
#> 2   2         2    mu             location response 0.8777762 0.11600209
#> 3   3         3    mu             location response 1.3879938 0.16295543
#> 4   1         1 sigma distributional-scale response 0.4962382 0.07395411
#> 5   2         2 sigma distributional-scale response 0.5678679 0.05795775
#> 6   3         3 sigma distributional-scale response 0.6498369 0.09684481
#>    conf.low conf.high conf.level conf.status interval_source  x habitat
#> 1 0.1039602 0.6311571       0.95        wald            wald -1    reef
#> 2 0.6504163 1.1051362       0.95        wald            wald  0    reef
#> 3 1.0686070 1.7073806       0.95        wald            wald  1    reef
#> 4 0.3705408 0.6645755       0.95        wald            wald -1    reef
#> 5 0.4649132 0.6936217       0.95        wald            wald  0    reef
#> 6 0.4852330 0.8702789       0.95        wald            wald  1    reef

empirical_grid <- prediction_grid(
  fit,
  focal = "habitat",
  at = list(habitat = levels(dat$habitat)),
  margin = "empirical"
)
marginal_parameters(fit, newdata = empirical_grid, dpar = "mu", by = "habitat")
#>   dpar component     type habitat  estimate  n   conf.status interval_source
#> 1   mu  location response    reef 0.8777762 48 not_requested   not_available
#> 2   mu  location response    sand 0.1789187 48 not_requested   not_available