Marginal summaries of predicted distributional parameters

marginal_parameters() averages predicted distributional parameters over fitted rows or a supplied newdata grid. It is a simple plug-in summary layer built on predict_parameters(), intended for interpretation tables and plotting helpers that need averages rather than row-level predictions.

Usage

marginal_parameters(object, ...)

# S3 method for class 'drmTMB'
marginal_parameters(
  object,
  newdata = NULL,
  dpar = NULL,
  by = NULL,
  type = c("response", "link"),
  ...
)

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 summarise, including fitted random-effect scale model names such as "sd(id)". NULL summarises all fitted distributional parameters.

by

Optional character vector of columns in newdata used to define marginal groups. NULL averages over all prediction rows for each distributional parameter.

type

Prediction scale: "response" or "link".

Value

A data frame with one row per distributional parameter and grouping combination. The returned columns are dpar, component, type, optional by columns, estimate, n, conf.status, and interval_source.

Details

This helper does not compute uncertainty, contrasts, or profile intervals. It reports unweighted averages of already-predicted parameter values. For population-level summaries, supply an explicit newdata grid; with newdata = NULL, the fitted-row prediction contract is the same as predict.drmTMB().

Averaging uses a moment-appropriate scale so that dispersion and correlation summaries stay interpretable. On type = "response", standard-deviation parameters (sigma, sigma1, sigma2, and random-effect sd(...) models) are averaged on the variance scale (the reported value is the root of the mean squared per-row SD), and correlation parameters (rho12) are averaged on the Fisher-z scale. Location and other parameters use the arithmetic mean. On type = "link", all parameters are already on an unconstrained scale, so the arithmetic mean of the linear predictor is reported unchanged. These remain unweighted plug-in summaries, not exact marginal moments of the mixture over rows.

The returned table carries the same interval provenance columns as predict_parameters(). In this first contract, marginal summaries are point estimates with conf.status = "not_requested" and interval_source = "not_available".

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 = "habitat",
  at = list(habitat = levels(dat$habitat)),
  margin = "empirical"
)
marginal_parameters(fit, newdata = grid, dpar = c("mu", "sigma"), by = "habitat")
#>    dpar            component     type habitat  estimate  n   conf.status
#> 1    mu             location response    reef 0.8777762 48 not_requested
#> 2    mu             location response    sand 0.1789187 48 not_requested
#> 3 sigma distributional-scale response    reef 0.5759517 48 not_requested
#> 4 sigma distributional-scale response    sand 0.5759517 48 not_requested
#>   interval_source
#> 1   not_available
#> 2   not_available
#> 3   not_available
#> 4   not_available