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 exact family-CDF plumbing 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.10499059 0.3416273
#> 2 2 b 2 2 poisson 0 3 0.76813044 0.9129160
#> 3 3 a 1 2 poisson 0 2 0.31439379 0.5768116
#> 4 4 b 2 2 poisson 0 1 0.19731887 0.5175544
#> 5 5 a 1 2 poisson 0 4 0.77412149 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.32057563 0.5841030
#> 10 10 b 2 2 poisson 0 2 0.51497657 0.7753180
#> 11 11 a 1 2 poisson 0 2 0.31439379 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.10499059 0.3416273
#> 16 16 b 2 2 poisson 0 3 0.76813044 0.9129160
#> 17 17 a 1 2 poisson 0 5 0.88034890 0.9524780
#> 18 18 b 2 2 poisson 0 1 0.20869639 0.5356975
#> 19 19 a 1 2 poisson 0 2 0.30824350 0.5694717
#> 20 20 b 2 2 poisson 0 0 0.00000000 0.1989070
#> 21 21 a 1 2 poisson 0 2 0.31439379 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.10222317 0.3353530
#> 26 26 b 2 2 poisson 0 2 0.50883616 0.7702809
#> 27 27 a 1 2 poisson 0 1 0.09949912 0.3291039
#> 28 28 b 2 2 poisson 0 1 0.19356701 0.5114295
#> 29 29 a 1 2 poisson 0 5 0.87607650 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.1060306
#> 32 32 b 2 2 poisson 0 1 0.18983705 0.5052682
#> 33 33 a 1 2 poisson 0 3 0.58139762 0.7879871
#> 34 34 b 2 2 poisson 0 4 0.91728119 0.9747419
#> 35 35 a 1 2 poisson 0 2 0.32057563 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.31439379 0.5768116
#> 40 40 b 2 2 poisson 0 1 0.19731887 0.5175544
#> 41 41 a 1 2 poisson 0 5 0.88034890 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.1060306
#> 44 44 b 2 2 poisson 0 1 0.18983705 0.5052682
#> 45 45 a 1 2 poisson 0 4 0.76809656 0.8976883
#> 46 46 b 2 2 poisson 0 3 0.78308755 0.9210420
#> 47 47 a 1 2 poisson 0 5 0.88034890 0.9524780
#> 48 48 b 2 2 poisson 0 1 0.20869639 0.5356975
#> u residual status scale method seed
#> 1 0.16781968 -0.96281702 ok normal exact_family_cdf 1
#> 2 0.82200861 0.92304689 ok normal exact_family_cdf 1
#> 3 0.46472069 -0.08854769 ok normal exact_family_cdf 1
#> 4 0.48815928 -0.02968463 ok normal exact_family_cdf 1
#> 5 0.79978278 0.84084559 ok normal exact_family_cdf 1
#> 6 0.97014143 1.88287628 ok normal exact_family_cdf 1
#> 7 0.10554544 -1.25057145 ok normal exact_family_cdf 1
#> 8 0.86015498 1.08101590 ok normal exact_family_cdf 1
#> 9 0.48636438 -0.03418610 ok normal exact_family_cdf 1
#> 10 0.53106209 0.07793996 ok normal exact_family_cdf 1
#> 11 0.36844518 -0.33597416 ok normal exact_family_cdf 1
#> 12 0.25385861 -0.66239637 ok normal exact_family_cdf 1
#> 13 0.70430427 0.53682073 ok normal exact_family_cdf 1
#> 14 0.32498431 -0.45380578 ok normal exact_family_cdf 1
#> 15 0.28716331 -0.56169094 ok normal exact_family_cdf 1
#> 16 0.84019011 0.99523955 ok normal exact_family_cdf 1
#> 17 0.93211007 1.49169218 ok normal exact_family_cdf 1
#> 18 0.53305078 0.08294101 ok normal exact_family_cdf 1
#> 19 0.40751939 -0.23393069 ok normal exact_family_cdf 1
#> 20 0.15463933 -1.01673678 ok normal exact_family_cdf 1
#> 21 0.55967706 0.15015049 ok normal exact_family_cdf 1
#> 22 0.26525444 -0.62722938 ok normal exact_family_cdf 1
#> 23 0.69684486 0.51534740 ok normal exact_family_cdf 1
#> 24 0.24158947 -0.70119882 ok normal exact_family_cdf 1
#> 25 0.16452029 -0.97604820 ok normal exact_family_cdf 1
#> 26 0.60978366 0.27875522 ok normal exact_family_cdf 1
#> 27 0.10257360 -1.26702262 ok normal exact_family_cdf 1
#> 28 0.31511379 -0.48140655 ok normal exact_family_cdf 1
#> 29 0.94059420 1.55978114 ok normal exact_family_cdf 1
#> 30 0.07157846 -1.46413553 ok normal exact_family_cdf 1
#> 31 0.05111525 -1.63413500 ok normal exact_family_cdf 1
#> 32 0.37895881 -0.30821646 ok normal exact_family_cdf 1
#> 33 0.68335804 0.47710983 ok normal exact_family_cdf 1
#> 34 0.92798138 1.46092057 ok normal exact_family_cdf 1
#> 35 0.53861112 0.09693531 ok normal exact_family_cdf 1
#> 36 0.68900616 0.49303524 ok normal exact_family_cdf 1
#> 37 0.72692937 0.60355240 ok normal exact_family_cdf 1
#> 38 0.23590889 -0.71952454 ok normal exact_family_cdf 1
#> 39 0.50430840 0.01079978 ok normal exact_family_cdf 1
#> 40 0.32902356 -0.44261102 ok normal exact_family_cdf 1
#> 41 0.93956301 1.55111561 ok normal exact_family_cdf 1
#> 42 0.42028579 -0.20116243 ok normal exact_family_cdf 1
#> 43 0.08301485 -1.38507449 ok normal exact_family_cdf 1
#> 44 0.36428195 -0.34703649 ok normal exact_family_cdf 1
#> 45 0.83674387 0.98116320 ok normal exact_family_cdf 1
#> 46 0.89198272 1.23714151 ok normal exact_family_cdf 1
#> 47 0.88203176 1.18520481 ok normal exact_family_cdf 1
#> 48 0.36475115 -0.34578767 ok normal exact_family_cdf 1
# }