Predict distributional parameters in long format — predict

predict_parameters() returns predicted distributional parameters from a drmTMB fit in one long data frame. It is a compact data surface for interpretation tables, plotting helpers, and marginalisation helpers: the same grid can hold location or mean, scale, shape, probability, and coscale quantities.

Usage

predict_parameters(object, ...)

# S3 method for class 'drmTMB'
predict_parameters(
  object,
  newdata = NULL,
  dpar = NULL,
  type = c("response", "link"),
  include_newdata = TRUE,
  conf.int = FALSE,
  conf.level = 0.95,
  ...
)

Arguments

object: A drmTMB fit.
...: Reserved for future options.
newdata: Optional data frame for prediction. If omitted, fitted rows are used.
dpar: Optional character vector of distributional parameters to predict, such as "mu", "sigma", "nu", "rho12", "sigma1", or "sigma2", plus fitted random-effect scale model names such as "sd(id)". NULL predicts all fitted distributional parameters.
type: Prediction scale: "response" or "link".
include_newdata: Logical; when TRUE and newdata is supplied, append the supplied covariate columns to the returned table.
conf.int: Logical; include Wald fixed-effect confidence intervals when available for the supplied prediction grid.
conf.level: Confidence level for Wald intervals when conf.int = TRUE.

Value

A data frame with columns row, row_label, dpar, component, type, estimate, conf.status, and interval_source. When conf.int = TRUE, std.error, conf.low, conf.high, and conf.level are also included. When include_newdata = TRUE, supplied newdata columns are appended after those core columns.

Details

The helper calls predict.drmTMB() for each requested distributional parameter. With newdata = NULL, predictions use the fitted rows. With newdata supplied, predictions are fixed-effect, population-level predictions for those rows, matching predict.drmTMB(). Use this table when the reader needs distributional-parameter values on an explicit covariate grid. Use marginal_parameters() when the target is an average over rows rather than a row-by-row prediction table.

By default, the table includes interval provenance columns with conf.status = "not_requested" and interval_source = "not_available". When conf.int = TRUE and newdata is supplied for ordinary fixed-effect distributional parameters, the helper adds Wald fixed-effect intervals from the fitted coefficient covariance and records the requested confidence level. These are population-level intervals for the supplied grid. Link-scale intervals are computed on the linear predictor scale; response-scale intervals use the model link and a delta method standard error. They do not include random-effect mode uncertainty, profile-likelihood uncertainty, or uncertainty for direct random-effect scale models.

Examples

set.seed(20260522)
n <- 36
x <- seq(-1.5, 1.5, length.out = n)
sigma <- exp(-0.35 + 0.2 * x)
dat <- data.frame(
  y = 0.4 + 0.7 * x + rnorm(n, sd = sigma),
  x = x
)
fit <- drmTMB(bf(y ~ x, sigma ~ x), data = dat)
grid <- data.frame(x = c(-1, 0, 1))
pred <- predict_parameters(
  fit,
  newdata = grid,
  dpar = c("mu", "sigma"),
  conf.int = TRUE
)
pred
#>   row row_label  dpar            component     type   estimate  std.error
#> 1   1         1    mu             location response -0.1466025 0.11051977
#> 2   2         2    mu             location response  0.3691856 0.11291954
#> 3   3         3    mu             location response  0.8849738 0.20454109
#> 4   1         1 sigma distributional-scale response  0.4377963 0.08089359
#> 5   2         2 sigma distributional-scale response  0.6225693 0.07337032
#> 6   3         3 sigma distributional-scale response  0.8853262 0.16358602
#>     conf.low  conf.high conf.level conf.status interval_source  x
#> 1 -0.3632173 0.07001226       0.95        wald            wald -1
#> 2  0.1478674 0.59050388       0.95        wald            wald  0
#> 3  0.4840806 1.28586697       0.95        wald            wald  1
#> 4  0.3047837 0.62885773       0.95        wald            wald -1
#> 5  0.4941660 0.78433665       0.95        wald            wald  0
#> 6  0.6163433 1.27169789       0.95        wald            wald  1

predict_parameters(
  fit,
  newdata = grid,
  dpar = "sigma",
  type = "link",
  include_newdata = FALSE,
  conf.int = TRUE
)
#>   row row_label  dpar            component type   estimate std.error   conf.low
#> 1   1         1 sigma distributional-scale link -0.8260016 0.1847745 -1.1881529
#> 2   2         2 sigma distributional-scale link -0.4739004 0.1178508 -0.7048838
#> 3   3         3 sigma distributional-scale link -0.1217991 0.1847749 -0.4839512
#>    conf.high conf.level conf.status interval_source
#> 1 -0.4638502       0.95        wald            wald
#> 2 -0.2429169       0.95        wald            wald
#> 3  0.2403529       0.95        wald            wald