From de272d7bd152ac95ad6f5e3ca28e4a6c7157fc27 Mon Sep 17 00:00:00 2001
From: Michael McCarthy <51542091+mccarthy-m-g@users.noreply.github.com>
Date: Thu, 26 Oct 2023 16:21:06 -0700
Subject: [PATCH] Add (temporary?) vignette for basic simulated residuals
 workflow demonstration and discussion

---
 vignettes/simulate_residuals.Rmd | 73 ++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)
 create mode 100644 vignettes/simulate_residuals.Rmd

diff --git a/vignettes/simulate_residuals.Rmd b/vignettes/simulate_residuals.Rmd
new file mode 100644
index 000000000..9909aa5af
--- /dev/null
+++ b/vignettes/simulate_residuals.Rmd
@@ -0,0 +1,73 @@
+---
+title: "Checking simulated residuals"
+output: 
+  rmarkdown::html_vignette:
+    toc: true
+    fig_width: 10.08
+    fig_height: 6
+tags: [r, performance]
+vignette: >
+  \usepackage[utf8]{inputenc}
+  %\VignetteIndexEntry{Checking simulated residuals}
+  %\VignetteEngine{knitr::rmarkdown}
+editor_options: 
+  chunk_output_type: console
+---
+
+```{r}
+devtools::load_all()
+library(DHARMa)
+```
+
+The basic workflow for simulated residual checks using `simulate_residuals()` is as follows.
+
+First, fit a model:
+
+```{r}
+library(glmmTMB)
+
+model <- glmmTMB(
+  count ~ mined + spp + (1 | site),
+  family = poisson,
+  data = Salamanders
+)
+```
+
+Next, simulate residuals from the model:
+
+```{r}
+simulated_residuals <- simulate_residuals(model)
+
+simulated_residuals
+```
+
+<!-- Aside -->
+Note that since this inherits the DHARMa class, all the methods implemented in DHARMa just work, including all the tests:
+
+```{r}
+residuals(simulated_residuals)
+
+DHARMa::testUniformity(simulated_residuals, plot = FALSE)
+```
+<!-- Aside -->
+
+Finally, run specific checks on the simulated residuals:
+
+```{r}
+check_residuals(simulated_residuals)
+```
+
+Or check the entire model. 
+
+```{r, eval=FALSE}
+# TODO (not implemented)
+check_model(simulated_residuals)
+```
+
+The `check_model()` function is the main reason we don't want to prematurely extract the residuals in `simulate_residuals()`, because if we do then the `simulated_residuals` won't contain the model fit (`fittedModel` in the output below), so we won't be able to do all of the checks we would want to do using the model.
+
+```{r}
+str(simulated_residuals, max.level = 1)
+```
+
+It would also mean we would need to reimplement some of the tests from DHARMa (e.g., `DHARMa::testOutliers()`) if we're planning to include those checks as well. We probably don't want to do that, since some of them are fairly involved rather than just being wrappers for tests supplied in base R (e.g., <https://github.com/florianhartig/DHARMa/blob/a04bdfeec75338279152dbc00c3a1825958a226a/DHARMa/R/tests.R#L172>) .