docs

R/check_model.R

@@ -116,7 +116,9 @@
 #' the line. For generalized linear models and when `residual_type = "normal"`,
 #' a half-normal Q-Q plot of the absolute value of the standardized deviance
 #' residuals is shown, however, the interpretation of the plot remains the same.
-#' See [`check_normality()`] for further details.
+#' See [`check_normality()`] for further details. Usually, for generalized linear
+#' (mixed) models, a test for uniformity of residuals based on simulated residuals
+#' is conducted (see next section).
 #'
 #' @section Uniformity of Residuals:
 #' Fore non-Gaussian models, when `residual_type = "simulated"` (the default

R/check_overdispersion.R

@@ -42,6 +42,8 @@
 #' the overdispersion test is based on [`simulate_residuals()`] (which is identical
 #' to `check_overdispersion(simulate_residuals(model))`).
 #'
+#' @inheritSection check_zeroinflation Tests based on simulated residuals
+#'
 #' @section How to fix Overdispersion:
 #' Overdispersion can be fixed by either modeling the dispersion parameter, or
 #' by choosing a different distributional family (like Quasi-Poisson, or

R/check_residuals.R

@@ -14,6 +14,8 @@
 #' @details Uniformity of residuals is checked using a Kolmogorov-Smirnov test.
 #' There is a `plot()` method to visualize the distribution of the residuals.
 #'
+#' @inheritSection simulate_residuals Tests based on simulated residuals
+#'
 #' @seealso [`simulate_residuals()`]
 #'
 #' @return The p-value of the test statistics.

R/check_zeroinflation.R

@@ -28,6 +28,18 @@
 #' [`simulate_residuals()`], i.e. `check_zeroinflation(simulate_residuals(model))`
 #' is internally called if necessary.
 #'
+#' @section Tests based on simulated residuals:
+#' For certain models, resp. model from certain families, tests are based on
+#' [`simulated_residuals()`]. These are usually more accurate for tests than the
+#' traditionally used Pearson residuals. However, when simulating from more
+#' complex model, such as mixed models or models with zero-inflation, there are
+#' several important considerations. Arguments specified in `...` are passed to
+#' [`simulate_residuals()`], which relies on [`DHARMa::simulateResiduals()`] (and
+#' therefore, arguments in `...` are passed further down to _DHARMa_). It is
+#' recommended to read the 'Details' in `?DHARMa::simulateResiduals` closely to
+#' understand the implications of the simulation process and which arguments
+#' should be modified to get the most accurate results.
+#'
 #' @family functions to check model assumptions and and assess model quality
 #'
 #' @examplesIf require("glmmTMB") && require("DHARMa")

R/simulate_residuals.R

@@ -21,6 +21,19 @@
 #' functions in the **see** package. See also `vignette("DHARMa")`. There is a
 #' `plot()` method to visualize the distribution of the residuals.
 #'
+#' @section Tests based on simulated residuals:
+#' For certain models, resp. model from certain families, tests like
+#' [`check_zeroinflation()`] or [`check_overdispersion()`] are based on
+#' `simulated_residuals()`. These are usually more accurate for such tests than
+#' the traditionally used Pearson residuals. However, when simulating from more
+#' complex model, such as mixed models or models with zero-inflation, there are
+#' several important considerations. `simulate_residuals()` relies on
+#' [`DHARMa::simulateResiduals()`], and additional arguments specified in `...`
+#' are passed further down to that function. It is recommended to read the
+#' 'Details' in `?DHARMa::simulateResiduals` closely to understand the
+#' implications of the simulation process and which arguments should be modified
+#' to get the most accurate results.
+#'
 #' @references
 #'
 #' - Hartig, F., & Lohse, L. (2022). DHARMa: Residual Diagnostics for Hierarchical