Diagnostic residuals for a multivariate gllvmTMB fit — residuals.gllvmTMB

Returns row-wise residual diagnostics for a fitted gllvmTMB_multi model. type = "randomized_quantile" uses exact family CDFs for Gaussian, Poisson, and NB2 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 yet implemented.

Usage

# S3 method for class 'gllvmTMB_multi'
residuals(
  object,
  type = c("randomized_quantile", "simulation_rank"),
  scale = c("normal", "uniform"),
  nsim = NULL,
  ndraws = NULL,
  seed = NULL,
  trait = NULL,
  condition_on_RE = TRUE,
  ...
)

Arguments

object: A gllvmTMB_multi fit.
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, Poisson, and NB2 rows plus simulation-rank residuals from fitted-model draws. Unsupported families are retained with row status rather than promoted to exact residual claims. Broader family coverage and formal residual tests remain 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
# }