Fitted distribution accessor

fitted_distribution() returns an object carrying, for each row of the fitted data (or newdata), the fitted distributional-parameter estimates from predict_parameters() together with density (d), CDF (p), and quantile (q) functions evaluated at those fitted parameters. Downstream consumers (quantile residuals, predict(type = "quantile"), exceedance()) are meant to route through this accessor rather than re-deriving the public-to-native parameter conversion.

Usage

fitted_distribution(object, ...)

# S3 method for class 'drmTMB'
fitted_distribution(object, newdata = NULL, response = NULL, ...)

Arguments

object

A drmTMB fit.

...

Reserved for future options.

newdata

Optional data frame for prediction. If omitted, fitted rows are used.

response

For a bivariate biv_gaussian fit, 1 or 2, selecting which response's marginal distribution to return. Required for biv_gaussian; must be NULL (the default) for univariate model types.

Value

An object of class "drm_fitted_distribution": a list with model_type, status, discrete, has_atom, atoms (numeric vector of isolated atom locations, numeric(0) when none – see drm_family_dpq()'s header comment), params (wide data frame of per-row native dpar estimates), and d, p, q (one-argument functions bound to params).

Details

fitted_distribution() only supports model_types with a promoted entry in drm_family_dpq(): as of DO-T3 batch D all 18 fitted model_type values are promoted (status = "reference"), including bivariate "biv_gaussian" (see the response argument below). newdata support inherits the same limitation as predict_parameters(): fixed-effect, population-level predictions only. For meta-analysis gaussian fits (meta_V()), the known sampling variance is taken from the fit for fitted rows (newdata = NULL); when newdata is supplied it must carry a V column giving the per-row known sampling variance, or an error is raised (rather than silently assuming 0). Ordinary (non-meta) fits need no V column. For binomial and beta_binomial fits, fitted rows reuse the fitted trials denominator; newdata must carry a trials column giving the per-row denominator, mirroring the meta_V() V-column contract. For cumulative_logit fits, the fitted ordinal cutpoints are attached as CP1..CPk columns (constant across rows, including newdata rows – the cutpoints do not depend on covariates).

response selects which response a bivariate biv_gaussian fit's returned distribution describes: 1 for (mu1, sigma1), 2 for (mu2, sigma2). It is required for biv_gaussian (an error names the two valid values if omitted) and is not used for univariate model_types (passing a non-NULL value errors, rather than being silently ignored). The returned distribution is the MARGINAL of that one response – exactly N(mu_k, sigma_k), independent of rho12 – never the joint bivariate distribution; there is no response = "joint" option. newdata for a biv_gaussian fit inherits any known bivariate sampling covariance as V_known = 0 (marginal-only scope, matching DO-T2's original predict(type = "quantile") documentation); fitted rows correctly use response k's slice of a meta_V() fit's known sampling variance.

Examples

dat <- data.frame(y = c(0.2, 0.5, 1.1, 1.4), x = c(-1, -0.5, 0, 0.5))
fit <- drmTMB(bf(y ~ x, sigma ~ 1), data = dat)
fd <- fitted_distribution(fit)
fd$p(dat$y)
#> [1] 0.67263923 0.08985589 0.91014372 0.32735991