CRAN Release 0.11.0

CRAN-SUBMISSION

@@ -1,3 +1,3 @@
-Version: 0.10.9
-Date: 2024-02-17 07:56:08 UTC
-SHA: 051016febd197937ad083266b630c871fa9e1623
+Version: 0.11.0
+Date: 2024-03-22 21:30:58 UTC
+SHA: 051b9bb2b7721c632ce145f85c55aa55c8eebf90

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: performance
 Title: Assessment of Regression Models Performance
-Version: 0.10.9.10
+Version: 0.11.0
 Authors@R: 
     c(person(given = "Daniel",
              family = "Lüdecke",
@@ -154,4 +154,3 @@ Config/Needs/website:
     r-lib/pkgdown,
     easystats/easystatstemplate
 Config/rcmdcheck/ignore-inconsequential-notes: true
-Remotes: easystats/see

NAMESPACE

@@ -72,6 +72,7 @@ S3method(check_normality,htest)
 S3method(check_normality,lmerModLmerTest)
 S3method(check_normality,merMod)
 S3method(check_normality,numeric)
+S3method(check_normality,performance_simres)
 S3method(check_outliers,BFBayesFactor)
 S3method(check_outliers,DHARMa)
 S3method(check_outliers,character)
@@ -517,6 +518,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)

NEWS.md

@@ -1,4 +1,4 @@
-# performance 0.10.10
+# performance 0.11.0
 
 ## New supported models
 

R/check_model.R

@@ -59,7 +59,7 @@
 #'
 #' @details For Bayesian models from packages **rstanarm** or **brms**,
 #' models will be "converted" to their frequentist counterpart, using
 #' [`bayestestR::bayesian_as_frequentist`](https://easystats.github.io/bayestestR/reference/convert_bayesian_as_frequentist.html).
 #' A more advanced model-check for Bayesian models will be implemented at a
 #' later stage.
 #'
@@ -87,7 +87,7 @@
 #' plots are helpful to check model assumptions, they do not necessarily indicate
 #' so-called "lack of fit", e.g. missed non-linear relationships or interactions.
 #' Thus, it is always recommended to also look at
 #' [effect plots, including partial residuals](https://strengejacke.github.io/ggeffects/articles/introduction_partial_residuals.html).
 #'
 #' @section Homogeneity of Variance:
 #' This plot checks the assumption of equal variance (homoscedasticity). The
@@ -144,12 +144,13 @@
 #' inside the error bounds. See [`binned_residuals()`] for further details.
 #'
 #' @section Residuals for (Generalized) Linear Models:
-#' Plots that check the normality of residuals (Q-Q plot) or the homogeneity of
-#' variance use standardized Pearson's residuals for generalized linear models,
-#' and standardized residuals for linear models. The plots for the normality of
-#' residuals (with overlayed normal curve) and for the linearity assumption use
-#' the default residuals for `lm` and `glm` (which are deviance residuals for
-#' `glm`).
+#' Plots that check the homogeneity of variance use standardized Pearson's
+#' residuals for generalized linear models, and standardized residuals for
+#' linear models. The plots for the normality of residuals (with overlayed
+#' normal curve) and for the linearity assumption use the default residuals
+#' for `lm` and `glm` (which are deviance residuals for `glm`). The Q-Q plots
+#' use simulated residuals (see [`simulate_residuals()`]) for non-Gaussian
+#' models and standardized residuals for linear models.
 #'
 #' @section Troubleshooting:
 #' For models with many observations, or for more complex models in general,

R/check_model_diagnostics.R

@@ -301,7 +301,7 @@
   d <- data.frame(Predicted = predicted)
 
   # residuals based on simulated residuals - but we want normally distributed residuals
-  d$Residuals <- stats::residuals(simres, quantileFunction = stats::qnorm, ...)
+  d$Residuals <- stats::residuals(simres, quantile_function = stats::qnorm, ...)
   d$Res2 <- d$Residuals^2
   d$StdRes <- insight::get_residuals(model, type = "pearson")
 

R/check_normality.R

@@ -92,6 +92,23 @@ check_normality.glm <- function(x, ...) {
   invisible(out)
 }
 
+# simulated residuals ----------
+
+#' @export
+check_normality.performance_simres <- function(x, ...) {
+  # check for normality of residuals
+  res <- stats::residuals(x, quantile_function = stats::qnorm)
+  p.val <- .check_normality(res[!is.infinite(res) & !is.na(res)], x)
+
+  attr(p.val, "data") <- x
+  attr(p.val, "object_name") <- insight::safe_deparse_symbol(substitute(x))
+  attr(p.val, "effects") <- "fixed"
+  class(p.val) <- unique(c("check_normality", "see_check_normality", class(p.val)))
+
+  p.val
+}
+
+
 # numeric -------------------
 
 #' @export

R/check_overdispersion.R

@@ -62,19 +62,10 @@
 #'  multilevel/hierarchical models. Cambridge; New York: Cambridge University
 #'  Press.
 #'
-#' @examplesIf getRversion() >= "4.0.0" && require("glmmTMB", quietly = TRUE)
-#'
-#' library(glmmTMB)
-#' data(Salamanders)
+#' @examplesIf getRversion() >= "4.0.0" && require("glmmTMB")
+#' data(Salamanders, package = "glmmTMB")
 #' m <- glm(count ~ spp + mined, family = poisson, data = Salamanders)
 #' check_overdispersion(m)
-#'
-#' m <- glmmTMB(
-#'   count ~ mined + spp + (1 | site),
-#'   family = poisson,
-#'   data = Salamanders
-#' )
-#' check_overdispersion(m)
 #' @export
 check_overdispersion <- function(x, ...) {
   UseMethod("check_overdispersion")

R/check_residuals.R

@@ -19,7 +19,8 @@
 #'
 #' @inheritSection simulate_residuals Tests based on simulated residuals
 #'
-#' @seealso [`simulate_residuals()`] and [`check_predictions()`].
+#' @seealso [`simulate_residuals()`], [`check_zeroinflation()`],
+#' [`check_overdispersion()`] and [`check_predictions()`].
 #'
 #' @return The p-value of the test statistics.
 #'

R/check_zeroinflation.R

@@ -30,7 +30,7 @@
 #'
 #' @section Tests based on simulated residuals:
 #' For certain models, resp. model from certain families, tests are based on
-#' simulated residuals (see [`simulated_residual()`]). These are usually more
+#' simulated residuals (see [`simulate_residuals()`]). These are usually more
 #' accurate for testing such models than the traditionally used Pearson residuals.
 #' However, when simulating from more complex models, such as mixed models or
 #' models with zero-inflation, there are several important considerations.

R/simulate_residuals.R

@@ -8,17 +8,25 @@
 #' @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
 #' `performance_simres`.
 #'
-#' @seealso [`check_residuals()`] and [`check_predictions()`].
+#' @seealso [`check_residuals()`], [`check_zeroinflation()`],
+#' [`check_overdispersion()`] and [`check_predictions()`].
 #'
 #' @details This function is a small wrapper around [`DHARMa::simulateResiduals()`].
 #' It basically only sets `plot = FALSE` and adds an additional class attribute
 #' (`"performance_sim_res"`), which allows using the DHARMa object in own plotting
-#' functions in the **see** package. See also `vignette("DHARMa")`. There is a
+#' functions from 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:
@@ -50,6 +58,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")
@@ -78,9 +89,10 @@ print.performance_simres <- function(x, ...) {
   # DHARMa's method.
   msg <- paste0(
     "Simulated residuals from a model of class `", class(x$fittedModel)[1],
-    "` based on ", x$nSim, " simulations. Use `check_residuals()` to check ",
-    "uniformity of residuals. It is recommended to refer to `?DHARMa::simulateResiudals`",
-    " and `vignette(\"DHARMa\")` for more information about different settings",
+    "` based on ", x$nSim, " simulations. Use `check_residuals()` to check",
+    " uniformity of residuals or `residuals()` to extract simulated residuals.",
+    " It is recommended to refer to `?DHARMa::simulateResiudals` and",
+    " `vignette(\"DHARMa\")` for more information about different settings",
     " in particular situations or for particular models.\n"
   )
   cat(insight::format_message(msg))
@@ -93,6 +105,37 @@ plot.performance_simres <- function(x, ...) {
 }
 
 
+# methods --------------------------
+
+#' @rdname simulate_residuals
+#' @export
+residuals.performance_simres <- function(object, quantile_function = NULL, outlier_values = NULL, ...) {
+  # check for DHARMa argument names
+  dots <- list(...)
+  if (!is.null(dots$quantileFunction)) {
+    quantile_function <- dots$quantileFunction
+  }
+  if (!is.null(dots$outlierValues)) {
+    outlier_values <- dots$outlierValues
+  }
+
+  if (is.null(quantile_function)) {
+    res <- object$scaledResiduals
+  } else {
+    res <- quantile_function(object$scaledResiduals)
+    if (!is.null(outlier_values)) {
+      # check for correct length of outlier_values
+      if (length(outlier_values) != 2) {
+        insight::format_error("`outlier_values` must be a vector of length 2.")
+      }
+      res[res == -Inf] <- outlier_values[1]
+      res[res == Inf] <- outlier_values[2]
+    }
+  }
+  res
+}
+
+
 # helper functions ---------------------
 
 .simres_statistics <- function(x, statistic_fun, alternative = "two.sided") {