Add autocorrelation testing for simulated residuals and use simulated residuals for Poisson mixed models

[Copilot]

This PR addresses key issues raised in #595, #643, and #654 regarding the revision of check_model() functionality, focusing on improving diagnostic accuracy for generalized linear mixed models.

Changes

1. Autocorrelation Testing for Simulated Residuals

Implements check_autocorrelation() method for simulated residuals objects, addressing the gap noted in #654:

# Now works with simulated residuals
library(glmmTMB)
data(Salamanders, package = "glmmTMB")

m <- glmmTMB(count ~ spp + (1|site), family = poisson, data = Salamanders)
simres <- simulate_residuals(m)
check_autocorrelation(simres)

The new method uses DHARMa::testTemporalAutocorrelation() for robust temporal autocorrelation testing. Users can optionally provide a time argument to specify temporal ordering if data are not already ordered by time.

2. Simulated Residuals for Poisson Mixed Models

Previously, Poisson mixed models used Pearson residuals for overdispersion and zero-inflation tests, which could be inaccurate (see #464). This PR ensures these models now use simulated residuals, consistent with how zero-inflated and negative binomial models are handled:

• check_overdispersion.merMod(): Now includes info$is_poisson in conditions for using simulated residuals
• check_zeroinflation.default(): Adds (model_info$is_mixed && model_info$is_poisson) condition

This change improves accuracy and maintains consistency across model types.

3. Documentation and Testing

• Updated documentation to clearly explain when simulated residuals are used
• Added comprehensive tests for autocorrelation with simulated residuals
• Updated existing test for Poisson mixed model overdispersion to reflect new output format
• Added TODO comment noting that overdispersion plots could be updated in future work

Breaking Changes

The output structure for check_overdispersion() when applied to Poisson mixed models changes:

Before:

list(
  chisq_statistic = ...,
  dispersion_ratio = ...,
  residual_df = ...,
  p_value = ...
)

After:

list(
  dispersion_ratio = ...,
  p_value = ...
)

Rationale: Simulated residuals don't use chi-squared test statistics. This change provides more accurate dispersion estimates for Poisson mixed models.

Future Work

As noted in the original issues, the overdispersion diagnostic plots (called via plot.check_overdisp()) still use classical residuals. A TODO comment has been added to flag this for future improvement, which would require coordination with the see package for visualization updates.

Closes #595
Related to #643, #654, #698

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Revising check_model()</issue_title>
<issue_description>Relates to #595 and #643, which I would like to merge for reasons of clarity of the discussion. Here I post the remaining things we might address.
</issue_description>

<agent_instructions>I think the implementation works quite well now for the first methods. The plot() method works fine for the Q-Q plots (easystats/see#329). Things we should consider:

• We would have to update the plot for overdispersion/zero-inflation checks (see DHARMa implementation for new check_residuals() function #643 (comment)). This is still based on the classical residuals, not the simulated ones. I have played around with revising the current code, copying the function .diag_overdispersion into a new .new_diag_overdispersion (see

  performance/R/check_model_diagnostics.R

  Line 296 in ad60db1

  .new_diag_overdispersion <- function(model, ...) {

  ). This did not really work - do you have any ideas how we can have new plots for overdispersion/zero-inflation? I found these plots quite informative and would like to keep them, beside the Q-Q plot. See also discussion here.

• check_zeroinflation() and check_overdispersion() now rely on simulate_residuals() for zero-inflated or negative binomial models etc., so only the really "simple" models that returned identical results to DHARMa-tests still use the old code. Only Poisson mixed models also use the "old" code, which still could be inaccurate (see check_overdispersion underestimates dispersion in mixed models #464) - do we want to use simulate_residuals() in general for mixed models when calling check_zeroinflation() and check_overdispersion()?

• How do we want to deal with y axis limits when detrend = TRUE in Q-Q plots? (see DHARMa implementation for new check_residuals() function #643 (comment))

• A method for check_autocorrelation() is not yet implemented. Since the DHARMa tests require additional information, I'm not sure about how to best implement such methods.

There is already an open pull request (#698), but you may open another one.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@strengejacke (moving discussion to #698)

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.