add residuals method

Author: strengejacke

NAMESPACE

@@ -517,6 +517,7 @@ S3method(r2_tjur,nestedLogit)
 S3method(residuals,BFBayesFactor)
 S3method(residuals,check_normality_numeric)
 S3method(residuals,iv_robust)
+S3method(residuals,performance_simres)
 S3method(rstudent,check_normality_numeric)
 S3method(test_bf,ListModels)
 S3method(test_bf,default)

R/simulate_residuals.R

@@ -8,6 +8,13 @@
 #' @param x A model object.
 #' @param iterations Number of simulations to run.
 #' @param ... Arguments passed on to [`DHARMa::simulateResiduals()`].
+#' @param object A `performance_simres` object, as returned by `simulate_residuals()`.
+#' @param quantile_function A function to apply to the residuals. If `NULL`, the
+#' residuals are returned as is. If not `NULL`, the residuals are passed to this
+#' function. This is useful for returning normally distributed residuals, for
+#' example: `residuals(x, quantile_function = qnorm)`.
+#' @param outlier_values A vector of length 2, specifying the values to replace
+#' `-Inf` and `Inf` with, respectively.
 #'
 #' @return Simulated residuals, which can be further processed with
 #' [`check_residuals()`]. The returned object is of class `DHARMa` and
@@ -50,6 +57,9 @@
 #' m <- lm(mpg ~ wt + cyl + gear + disp, data = mtcars)
 #' simulate_residuals(m)
 #'
+#' # extract residuals
+#' head(residuals(simulate_residuals(m)))
+#'
 #' @export
 simulate_residuals <- function(x, iterations = 250, ...) {
   insight::check_if_installed("DHARMa")
@@ -93,6 +103,24 @@ plot.performance_simres <- function(x, ...) {
 }
 
 
+# methods --------------------------
+
+#' @rdname simulate_residuals
+#' @export
+residuals.performance_simres <- function(object, quantile_function = NULL, outlier_values = NULL, ...) {
+  if (is.null(quantile_function)) {
+    res <- object$scaledResiduals
+  } else {
+    res <- quantile_function(object$scaledResiduals)
+    if (!is.null(outlier_values)) {
+      res[res == -Inf] <- outlier_values[1]
+      res[res == Inf] <- outlier_values[2]
+    }
+  }
+  res
+}
+
+
 # helper functions ---------------------
 
 .simres_statistics <- function(x, statistic_fun, alternative = "two.sided") {

man/simulate_residuals.Rd

@@ -61,13 +61,18 @@ simulated_residuals <- simulate_residuals(model)
 simulated_residuals
 ```
 
+The raw residuals can be extracted using `residuals()`:
+
+```{r}
+head(residuals(simulated_residuals))
+```
+
+
 <!-- Aside -->
 Note that since this inherits the DHARMa class, all the methods implemented in DHARMa just work, including all the tests:
 
 ```{r}
 library(DHARMa)
-residuals(simulated_residuals)
-
 DHARMa::testUniformity(simulated_residuals, plot = FALSE)
 ```
 <!-- Aside -->