Randomized quantile residuals (internal)

drm_quantile_residuals() computes Dunn-Smyth (1996) randomized quantile residuals r_i = qnorm(F(y_i; theta_hat_i)) from the fitted distribution returned by fitted_distribution().

Usage

drm_quantile_residuals(object, seed = NULL, nsim = 1L, response = NULL)

Arguments

object

A drmTMB fit.

seed

Optional single integer. Fixes the Dunn-Smyth randomization reproducibly (discrete/atom families only) without disturbing the caller's RNG stream; see drm_dunn_smyth_u(). Ignored for continuous, atom-free families, where the residual has no randomization to fix.

nsim

Number of independent randomized realizations to draw (Fisher's multi-realization seed envelope). nsim = 1 (default) returns a plain numeric vector. nsim > 1 returns an n-by-nsim matrix, one column per realization, using nsim distinct derived seeds when seed is supplied (seed, seed + 1, ..., seed + nsim - 1). For continuous, atom-free families every column is identical (the residual has no randomization uncertainty to average over); the envelope is only non-degenerate for discrete/atom families.

response

For a bivariate biv_gaussian fit, 1 or 2, selecting which response's marginal residuals to compute; see fitted_distribution(). Must be NULL (the default) for univariate model types.

Value

A numeric vector (nsim = 1) or an n-by-nsim matrix (nsim > 1) of approximately N(0,1) residuals under a correctly specified fixed-effect model. Missing-response rows (see drm_mask_missing_response_values()) are NA.

Details

For continuous, atom-free families F has no jumps, so the residual is exact and deterministic: u_i = F(y_i). For discrete families (fitted_distribution()$discrete) or families with an isolated atom ($has_atom), F has jumps, so a plain F(y_i) residual is not uniform even under the true model. The Dunn-Smyth fix instead draws u_i ~ Uniform(F(y_i-), F(y_i)] via drm_dunn_smyth_u(), where F(y_i-) is the left limit of F at y_i: F(y_i - 1) for a discrete/count family (fd$discrete; the left limit of any discrete distribution's CDF is the CDF at the previous integer, whatever the support – this covers ordinary counts, zero-inflated/hurdle counts, and zero-truncated counts uniformly, since zero-inflation/hurdle mass sits AT an existing lattice point rather than opening a new atom, and a zero-truncated F is 0 below its support). For a continuous-with-isolated-atoms family (fd$has_atom, fd$discrete == FALSE), the left limit is F(y_i) unchanged away from every atom location in fd$atoms (F is continuous there, so the Dunn-Smyth draw degenerates to the plain continuous case automatically) and the exact left limit F(a-) = F(a) - P(Y = a) = F(a) - fd$d(a) at each atom a – exact for both Tweedie's atom at y = 0 and zero_one_beta's atoms at y = 0 and y = 1, with no epsilon offset (see drm_atom_left_limit()).

fitted_distribution()$status == "spike" families (feasibility spikes, not yet DG2/DG3-verified) still compute a residual, but emit a one-time cli::cli_warn() per model_type per session flagging that the residual is exploratory, not DG-verified. status == "unimplemented" families already raise a clear error inside fitted_distribution(), before this function's body runs.

For a bivariate biv_gaussian fit, response (1 or 2) is REQUIRED and selects which response's MARGINAL quantile residuals to compute – exactly the univariate Dunn-Smyth construction above applied to that response's N(mu_k, sigma_k) marginal (rho12 does not enter). Omitting response for a biv_gaussian fit errors clearly, as does supplying it for a univariate fit; see fitted_distribution().