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 (which can differ from the response 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 whose stable native core columns retain this relative order: row, row_label, dpar, component, type, estimate, conf.status, and interval_source. conf.status is an interval result or availability state; interval_source is interval provenance. Only when conf.int = TRUE, std.error, conf.low, conf.high, and conf.level are included after estimate and before the status/provenance columns. When include_newdata = TRUE, supplied newdata columns are appended after the schema columns and renamed with newdata_ plus, when needed, a stable uniqueness suffix when they collide.

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.

For a sigma/sigma1/sigma2 dpar of a family whose scale is soft-clamped (see drm_control(logsigma_clamp = )), a row whose raw linear predictor already lies outside the clamp band carries conf.status = "clamp_limited" and std.error/conf.low/conf.high of NA: the clamp bent that row, so the raw-predictor Wald interval is not an interval for the reported (clamped) quantity, and where the bend is strong no Wald interval is defined at all. Rows inside the band are unaffected, because the clamp is the identity inside the band and their Wald interval is unchanged. Note the selection this implies: whether a row returns an interval depends on where its estimate fell relative to the band, not on where the truth is, so near the band edge the intervals that are returned are conditioned on that selection (in the package's own check, coverage of the kept "wald" rows fell from 0.985 to 0.882 as the true predictor approached the edge, against 0.98 for the unconditional raw interval). Use check_drm() to see whether a fit's clamp is active, and rescale the response or widen the band (drm_control(logsigma_clamp = )) before trusting scale-parameter intervals on a clamp-active fit.

For native drmTMB fits, the stable core columns retain this relative order: row, row_label, dpar, component, type, estimate, conf.status, and interval_source. conf.status describes the requested interval result or availability; interval_source identifies its provenance. Interval columns appear only when conf.int = TRUE, in the established position after estimate and before conf.status. Supplied newdata columns are appended after the core and optional interval columns, with a newdata_ prefix if their names would collide with this schema and a stable suffix when two supplied names would otherwise collide after prefixing.

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.1466021 0.11052013
#> 2   2         2    mu             location response  0.3691851 0.11291974
#> 3   3         3    mu             location response  0.8849722 0.20454140
#> 4   1         1 sigma distributional-scale response  0.4377977 0.08089409
#> 5   2         2 sigma distributional-scale response  0.6225706 0.07337062
#> 6   3         3 sigma distributional-scale response  0.8853269 0.16358632
#>     conf.low  conf.high conf.level conf.status interval_source  x
#> 1 -0.3632175 0.07001341       0.95        wald            wald -1
#> 2  0.1478664 0.59050368       0.95        wald            wald  0
#> 3  0.4840784 1.28586597       0.95        wald            wald  1
#> 4  0.3047844 0.62886045       0.95        wald            wald -1
#> 5  0.4941668 0.78433863       0.95        wald            wald  0
#> 6  0.6163436 1.27169940       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.8259983 0.1847750 -1.1881508
#> 2   2         2 sigma distributional-scale link -0.4738983 0.1178511 -0.7048822
#> 3   3         3 sigma distributional-scale link -0.1217983 0.1847750 -0.4839508
#>    conf.high conf.level conf.status interval_source
#> 1 -0.4638459       0.95        wald            wald
#> 2 -0.2429144       0.95        wald            wald
#> 3  0.2403541       0.95        wald            wald