Diagnostic residuals for a multivariate gllvmTMB fit
Source: R/predictive-diagnostics.R
residuals.gllvmTMB_multi.RdReturns row-wise residual diagnostics for a fitted gllvmTMB_multi
model. type = "randomized_quantile" uses exact family CDFs for
Gaussian, binomial, Poisson, lognormal, Gamma, NB2, Beta, betabinomial,
Student-t, zero-truncated Poisson, zero-truncated NB2, NB1, and
ordinal-probit rows. type = "simulation_rank" uses fitted-model
simulations and is available as a fallback for checking the same row
contract when an exact family CDF is not implemented for a family;
its own family coverage (what simulate.gllvmTMB_multi() can draw from)
is tracked separately and is not extended here.
Arguments
- object
A
gllvmTMB_multifit.- type
"randomized_quantile"for exact family-CDF randomized quantile residuals where implemented, or"simulation_rank"for simulation-rank residuals from fitted-model draws.- scale
"normal"returns normal-quantile residuals;"uniform"returns the randomized PIT value.- nsim, ndraws
Number of fitted-model draws for
type = "simulation_rank". Ignored by exact randomized-quantile residuals.- seed
Optional RNG seed.
- trait
Optional character vector of trait names to keep.
- condition_on_RE
Logical. Passed to
simulate.gllvmTMB_multi()for simulation-rank residuals.- ...
Currently unused.
Value
A data frame with row metadata (.row, trait, family_id,
family, link_id), observed, randomized PIT value u,
residual, status, scale, and method metadata. The attribute
method records the residual engine.
Details
Rows are retained even when a residual cannot be computed. Inspect the
status column before treating residuals as complete.
Scope: exact family-CDF randomized-quantile residuals for Gaussian,
binomial, Poisson, lognormal, Gamma, NB2, Beta, betabinomial, Student-t,
zero-truncated Poisson, zero-truncated NB2, NB1, and ordinal-probit rows,
plus simulation-rank residuals from fitted-model draws. Tweedie, the
delta/hurdle families (delta_lognormal, delta_gamma), and
multinomial are deliberately not implemented: tweedie has no closed-form
CDF without a new dependency, the delta/hurdle families mix a point mass
at zero with a continuous part and need an explicit design decision for
splitting the point mass, and multinomial's categories are unordered so a
randomized-quantile residual is undefined without inventing an ordering.
Unsupported families are retained with row status rather than promoted
to exact residual claims. Formal residual calibration beyond the current
family-specific recovery checks remains later validation work.
The returned data frame also carries attr(x, "gllvmTMB_diagnostic")
with check_gllvmTMB() output and the fitted object's fit_health
snapshot.
Examples
# \donttest{
set.seed(2)
n <- 24
df <- data.frame(
unit = factor(rep(seq_len(n), each = 2)),
trait = factor(rep(c("a", "b"), n)),
value = rpois(2 * n, lambda = 2)
)
fit <- gllvmTMB(
value ~ 0 + trait + latent(0 + trait | unit, d = 1),
data = df,
trait = "trait",
unit = "unit",
family = poisson()
)
residuals(fit, type = "randomized_quantile", seed = 1)
#> .row trait trait_id family_id family link_id observed cdf_lower cdf_upper
#> 1 1 a 1 2 poisson 0 1 0.10499062 0.3416273
#> 2 2 b 2 2 poisson 0 3 0.76813044 0.9129160
#> 3 3 a 1 2 poisson 0 2 0.31439381 0.5768116
#> 4 4 b 2 2 poisson 0 1 0.19731887 0.5175544
#> 5 5 a 1 2 poisson 0 4 0.77412148 0.9013579
#> 6 6 b 2 2 poisson 0 4 0.91994318 0.9758190
#> 7 7 a 1 2 poisson 0 0 0.00000000 0.1117267
#> 8 8 b 2 2 poisson 0 3 0.76296626 0.9100441
#> 9 9 a 1 2 poisson 0 2 0.32057566 0.5841030
#> 10 10 b 2 2 poisson 0 2 0.51497657 0.7753180
#> 11 11 a 1 2 poisson 0 2 0.31439381 0.5768116
#> 12 12 b 2 2 poisson 0 1 0.19731887 0.5175544
#> 13 13 a 1 2 poisson 0 3 0.55932770 0.7703492
#> 14 14 b 2 2 poisson 0 1 0.20109169 0.5236416
#> 15 15 a 1 2 poisson 0 1 0.10499062 0.3416273
#> 16 16 b 2 2 poisson 0 3 0.76813044 0.9129160
#> 17 17 a 1 2 poisson 0 5 0.88034887 0.9524780
#> 18 18 b 2 2 poisson 0 1 0.20869639 0.5356975
#> 19 19 a 1 2 poisson 0 2 0.30824353 0.5694717
#> 20 20 b 2 2 poisson 0 0 0.00000000 0.1989070
#> 21 21 a 1 2 poisson 0 2 0.31439381 0.5768116
#> 22 22 b 2 2 poisson 0 1 0.19731887 0.5175544
#> 23 23 a 1 2 poisson 0 3 0.55932770 0.7703492
#> 24 24 b 2 2 poisson 0 1 0.20109169 0.5236416
#> 25 25 a 1 2 poisson 0 1 0.10222320 0.3353531
#> 26 26 b 2 2 poisson 0 2 0.50883616 0.7702809
#> 27 27 a 1 2 poisson 0 1 0.09949914 0.3291040
#> 28 28 b 2 2 poisson 0 1 0.19356700 0.5114295
#> 29 29 a 1 2 poisson 0 5 0.87607647 0.9502611
#> 30 30 b 2 2 poisson 0 0 0.00000000 0.2103090
#> 31 31 a 1 2 poisson 0 0 0.00000000 0.1060307
#> 32 32 b 2 2 poisson 0 1 0.18983705 0.5052682
#> 33 33 a 1 2 poisson 0 3 0.58139764 0.7879871
#> 34 34 b 2 2 poisson 0 4 0.91728119 0.9747419
#> 35 35 a 1 2 poisson 0 2 0.32057566 0.5841030
#> 36 36 b 2 2 poisson 0 2 0.51497657 0.7753180
#> 37 37 a 1 2 poisson 0 3 0.55932770 0.7703492
#> 38 38 b 2 2 poisson 0 1 0.20109169 0.5236416
#> 39 39 a 1 2 poisson 0 2 0.31439381 0.5768116
#> 40 40 b 2 2 poisson 0 1 0.19731887 0.5175544
#> 41 41 a 1 2 poisson 0 5 0.88034887 0.9524780
#> 42 42 b 2 2 poisson 0 1 0.20869639 0.5356975
#> 43 43 a 1 2 poisson 0 0 0.00000000 0.1060307
#> 44 44 b 2 2 poisson 0 1 0.18983705 0.5052682
#> 45 45 a 1 2 poisson 0 4 0.76809655 0.8976883
#> 46 46 b 2 2 poisson 0 3 0.78308756 0.9210420
#> 47 47 a 1 2 poisson 0 5 0.88034887 0.9524780
#> 48 48 b 2 2 poisson 0 1 0.20869639 0.5356975
#> u residual status scale method seed
#> 1 0.16781971 -0.96281688 ok normal exact_family_cdf 1
#> 2 0.82200861 0.92304689 ok normal exact_family_cdf 1
#> 3 0.46472072 -0.08854761 ok normal exact_family_cdf 1
#> 4 0.48815928 -0.02968463 ok normal exact_family_cdf 1
#> 5 0.79978277 0.84084556 ok normal exact_family_cdf 1
#> 6 0.97014143 1.88287631 ok normal exact_family_cdf 1
#> 7 0.10554547 -1.25057125 ok normal exact_family_cdf 1
#> 8 0.86015498 1.08101589 ok normal exact_family_cdf 1
#> 9 0.48636441 -0.03418601 ok normal exact_family_cdf 1
#> 10 0.53106210 0.07793997 ok normal exact_family_cdf 1
#> 11 0.36844520 -0.33597409 ok normal exact_family_cdf 1
#> 12 0.25385861 -0.66239637 ok normal exact_family_cdf 1
#> 13 0.70430428 0.53682074 ok normal exact_family_cdf 1
#> 14 0.32498431 -0.45380577 ok normal exact_family_cdf 1
#> 15 0.28716336 -0.56169079 ok normal exact_family_cdf 1
#> 16 0.84019011 0.99523955 ok normal exact_family_cdf 1
#> 17 0.93211005 1.49169204 ok normal exact_family_cdf 1
#> 18 0.53305079 0.08294103 ok normal exact_family_cdf 1
#> 19 0.40751942 -0.23393063 ok normal exact_family_cdf 1
#> 20 0.15463933 -1.01673678 ok normal exact_family_cdf 1
#> 21 0.55967709 0.15015057 ok normal exact_family_cdf 1
#> 22 0.26525444 -0.62722938 ok normal exact_family_cdf 1
#> 23 0.69684486 0.51534741 ok normal exact_family_cdf 1
#> 24 0.24158947 -0.70119881 ok normal exact_family_cdf 1
#> 25 0.16452032 -0.97604807 ok normal exact_family_cdf 1
#> 26 0.60978366 0.27875522 ok normal exact_family_cdf 1
#> 27 0.10257362 -1.26702249 ok normal exact_family_cdf 1
#> 28 0.31511379 -0.48140655 ok normal exact_family_cdf 1
#> 29 0.94059418 1.55978098 ok normal exact_family_cdf 1
#> 30 0.07157846 -1.46413551 ok normal exact_family_cdf 1
#> 31 0.05111527 -1.63413485 ok normal exact_family_cdf 1
#> 32 0.37895881 -0.30821647 ok normal exact_family_cdf 1
#> 33 0.68335806 0.47710987 ok normal exact_family_cdf 1
#> 34 0.92798138 1.46092060 ok normal exact_family_cdf 1
#> 35 0.53861115 0.09693540 ok normal exact_family_cdf 1
#> 36 0.68900616 0.49303525 ok normal exact_family_cdf 1
#> 37 0.72692937 0.60355241 ok normal exact_family_cdf 1
#> 38 0.23590890 -0.71952453 ok normal exact_family_cdf 1
#> 39 0.50430844 0.01079986 ok normal exact_family_cdf 1
#> 40 0.32902356 -0.44261101 ok normal exact_family_cdf 1
#> 41 0.93956299 1.55111546 ok normal exact_family_cdf 1
#> 42 0.42028580 -0.20116240 ok normal exact_family_cdf 1
#> 43 0.08301487 -1.38507432 ok normal exact_family_cdf 1
#> 44 0.36428195 -0.34703650 ok normal exact_family_cdf 1
#> 45 0.83674386 0.98116316 ok normal exact_family_cdf 1
#> 46 0.89198273 1.23714154 ok normal exact_family_cdf 1
#> 47 0.88203173 1.18520467 ok normal exact_family_cdf 1
#> 48 0.36475115 -0.34578765 ok normal exact_family_cdf 1
# }