Fix overdispersion plot for glmmTMB and mixed models: correct residual scale and family variance formulas

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: performance
 Title: Assessment of Regression Models Performance
-Version: 0.17.0.1
+Version: 0.17.0.2
 Authors@R:
     c(person(given = "Daniel",
              family = "Lüdecke",

NEWS.md

@@ -1,3 +1,17 @@
+# performance (devel)
+
+## Bug fixes
+
+* The overdispersion plot in `check_model()` now uses simulated residuals (based
+  on the *DHARMa* package) for `glmmTMB` models and mixed models. This fixes
+  wonky-looking overdispersion plots for these model types (#654).
+
+* Fixed the expected variance calculation in `.expected_variance()` so that
+  `glmmTMB` `nbinom1` and `nbinom2` families use the correct formulas from the
+  glmmTMB documentation: `nbinom1`: V = μ(1 + φ); `nbinom2`: V = μ(1 + μ/φ).
+  Previously, glmmTMB `nbinom1` models incorrectly used the `nbinom2` formula
+  because it matched a more general `is_negbin` branch first (#654).
+
 # performance 0.17.0
 
 ## Changes

R/check_model.R

@@ -34,14 +34,14 @@
 #' `TRUE` for linear models or when `residual_type = "normal"`. Defaults to
 #' `FALSE` for QQ plots based on simulated residuals (i.e. when
 #' `residual_type = "simulated"`).
-#' @param residual_type Character, indicating the type of residuals to be used.
-#' For non-Gaussian models, the default is `"simulated"`, which uses simulated
-#' residuals. These are based on [`simulate_residuals()`] and thus uses the
-#' **DHARMa** package to return randomized quantile residuals. For Gaussian
-#' models, the default is `"normal"`, which uses the default residuals from
-#' the model. Setting `residual_type = "normal"` for non-Gaussian models will
-#' use a half-normal Q-Q plot of the absolute value of the standardized deviance
-#' residuals.
+#' @param residual_type Character, indicating the type of residuals to be used
+#' for QQ-plots and overdispersion tests. For non-Gaussian models, the default
+#' is `"simulated"`, which uses simulated residuals. These are based on
+#' [`simulate_residuals()`] and thus uses the **DHARMa** package to return
+#' randomized quantile residuals. For Gaussian models, the default is
+#' `"normal"`, which uses the default residuals from the model. Setting
+#' `residual_type = "normal"` for non-Gaussian models will use a half-normal Q-Q
+#' plot of the absolute value of the standardized deviance residuals.
 #' @param show_dots Logical, if `TRUE`, will show data points in the plot. Set
 #' to `FALSE` for models with many observations, if generating the plot is too
 #' time-consuming. By default, `show_dots = NULL`. In this case `check_model()`
@@ -269,6 +269,11 @@ check_model.default <- function(
 
   minfo <- insight::model_info(model, verbose = FALSE)
 
+  # validate argument
+  if (!is.null(residual_type)) {
+    insight::validate_argument(residual_type, c("normal", "simulated"))
+  }
+
   # set default for residual_type
   if (is.null(residual_type)) {
     residual_type <- ifelse(minfo$is_linear && !minfo$is_gam, "normal", "simulated")
@@ -278,7 +283,11 @@ check_model.default <- function(
   # exceptions here as they appear, but for now, `check_model()` also
   # automatically falls back to normal Q-Q plot for all models not supported
   # by DHARMa
-  if (minfo$family %in% c("quasipoisson", "quasibinomial")) {
+  if (
+    minfo$family %in%
+      c("quasipoisson", "quasibinomial") ||
+      !requireNamespace("DHARMa", quietly = TRUE)
+  ) {
     residual_type <- "normal"
   }
 
@@ -732,7 +741,11 @@ check_model.DHARMa <- check_model.performance_simres
 
   # misspecified dispersion and zero-inflation --------------
   if (isTRUE(model_info$is_count) && any(c("all", "overdispersion") %in% check)) {
-    dat$OVERDISPERSION <- .model_diagnostic_overdispersion(model)
+    dat$OVERDISPERSION <- .model_diagnostic_overdispersion(
+      model,
+      residual_type = residual_type,
+      ...
+    )
   }
 
   dat <- insight::compact_list(dat)