Harmonizing argument names for check_* functions

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: performance
 Title: Assessment of Regression Models Performance
-Version: 0.15.3.6
+Version: 0.15.3.7
 Authors@R:
     c(person(given = "Daniel",
              family = "Lüdecke",

NEWS.md

@@ -6,14 +6,17 @@
   `RMSR` (Root Mean Square Residual) instead of `RMSA`. The `RMSR_corrected`
   column (previously `RMSA_corrected`) is also renamed accordingly.
 
+* First argument in `check_model()`, `check_predictions()` and `check_convergence()`
+  were renamed into `model`.
+
 ## Changes
 
 * `check_model()` now limits the number of data points for models with many
   observations, to reduce the time for rendering the plot via the `maximum_dots`
   argument.
 
 * `check_model()` can now show or hide confidence intervals using the `show_ci`
-  argument. For models with only categorical predictors, cnmfidence intervals
+  argument. For models with only categorical predictors, confidence intervals
   are not shown by default.
 
 ## Bug fixes

R/check_convergence.R

@@ -4,9 +4,10 @@
 #' @description `check_convergence()` provides an alternative convergence
 #'   test for `merMod`-objects.
 #'
-#' @param x A `merMod` or `glmmTMB`-object.
+#' @param model A `merMod` or `glmmTMB`-object.
 #' @param tolerance Indicates up to which value the convergence result is
 #'   accepted. The smaller `tolerance` is, the stricter the test will be.
+#' @param x Deprecated, please use `model` instead.
 #' @param ... Currently not used.
 #'
 #' @return `TRUE` if convergence is fine and `FALSE` if convergence
@@ -50,8 +51,15 @@
 #' check_convergence(model)
 #' }
 #' @export
-check_convergence <- function(x, tolerance = 0.001, ...) {
-  out <- .safe(insight::is_converged(x, tolerance = tolerance, ...))
+check_convergence <- function(model = NULL, tolerance = 0.001, x = NULL, ...) {
+  ## TODO remove deprecation warning later
+  if (!is.null(x) && is.null(model)) {
+    insight::format_warning(
+      "Argument `x` is deprecated; please use `model` instead."
+    )
+    model <- x
+  }
+  out <- .safe(insight::is_converged(model, tolerance = tolerance, ...))
   if (is.null(out)) {
     insight::format_alert("Could not compute convergence information.")
     out <- NA

R/check_model.R

@@ -9,7 +9,7 @@
 #' If `check_model()` doesn't work as expected, try setting `verbose = TRUE` to
 #' get hints about possible problems.
 #'
-#' @param x A model object.
+#' @param model A model object.
 #' @param size_dot,size_line Size of line and dot-geoms.
 #' @param base_size,size_title,size_axis_title Base font size for axis and plot titles.
 #' @param panel Logical, if `TRUE`, plots are arranged as panels; else,
@@ -56,6 +56,8 @@
 #' @param verbose If `FALSE` (default), suppress most warning messages.
 #' @param ... Arguments passed down to the individual check functions, especially
 #' to `check_predictions()` and `binned_residuals()`.
+#' @param x Deprecated, please use `model` instead.
+#'
 #' @inheritParams check_predictions
 #'
 #' @return The data frame that is used for plotting.
@@ -68,7 +70,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.
 #'
@@ -96,7 +98,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
@@ -191,7 +193,7 @@
 #' check_model(m, panel = FALSE)
 #' }
 #' @export
-check_model <- function(x, ...) {
+check_model <- function(model, ...) {
   UseMethod("check_model")
 }
 
@@ -200,8 +202,8 @@
 
 #' @rdname check_model
 #' @export
 check_model.default <- function(
-  x,
+  model,
   panel = TRUE,
   check = "all",
   detrend = TRUE,
@@ -221,14 +223,23 @@
   colors = c("#3aaf85", "#1b6ca8", "#cd201f"),
   theme = see::theme_lucid(),
   verbose = FALSE,
+  x = NULL,
   ...
 ) {
+  ## TODO remove deprecation warning later
+  if (!is.null(x) && is.null(model)) {
+    insight::format_warning(
+      "Argument `x` is deprecated; please use `model` instead."
+    )
+    model <- x
+  }
+
   # check model formula
   if (verbose) {
-    insight::formula_ok(x)
+    insight::formula_ok(model)
   }
 
-  minfo <- insight::model_info(x, verbose = FALSE)
+  minfo <- insight::model_info(model, verbose = FALSE)
 
   # set default for residual_type
   if (is.null(residual_type)) {
@@ -250,10 +261,10 @@
 
   assumptions_data <- tryCatch(
     if (minfo$is_bayesian) {
-      suppressWarnings(.check_assumptions_stan(x, ...))
+      suppressWarnings(.check_assumptions_stan(model, ...))
     } else if (minfo$is_linear) {
       suppressWarnings(.check_assumptions_linear(
-        x,
+        model,
         minfo,
         check,
         residual_type,
@@ -262,7 +273,7 @@
       ))
     } else {
       suppressWarnings(.check_assumptions_glm(
-        x,
+        model,
         minfo,
         check,
         residual_type,
@@ -282,8 +293,8 @@
     insight::format_error(
       paste("`check_model()` returned following error:", cleaned_string),
       paste0(
         "\nIf the error message does not help identifying your problem, another reason why `check_model()` failed might be that models of class `",
-        class(x)[1],
+        class(model)[1],
         "` are not yet supported."
       ) # nolint
     )
@@ -293,7 +304,7 @@
   if (is.null(assumptions_data$QQ) && residual_type == "simulated") {
     insight::format_alert(paste0(
       "Cannot simulate residuals for models of class `",
-      class(x)[1],
+      class(model)[1],
       "`. Please try `check_model(..., residual_type = \"normal\")` instead."
     ))
   }
@@ -309,7 +320,7 @@
   }
 
   # set default for show_dots, based on "model size"
-  n <- .safe(insight::n_obs(x))
+  n <- .safe(insight::n_obs(model))
   if (is.null(show_dots)) {
     show_dots <- is.null(n) || n <= 1e5
   }
@@ -317,12 +328,12 @@
   # tell user about limited dots
   if (!is.null(maximum_dots) && !is.null(n) && n > maximum_dots && verbose) {
     insight::format_alert(
       "The model contains a large number of observations. To ensure efficient rendering, the plot is limited to 2,000 data points. You can use the `maximum_dots` argument to adjust this limit."
     )
   }
 
   # if we have only categorical predictors, we don't show CI by default
-  parameter_types <- .safe(parameters::parameters_type(x))
+  parameter_types <- .safe(parameters::parameters_type(model))
   if (
     !is.null(parameter_types) && all(parameter_types$Type %in% c("intercept", "factor"))
   ) {
@@ -350,7 +361,7 @@
   attr(assumptions_data, "bandwidth") <- bandwidth
   attr(assumptions_data, "type") <- type
   attr(assumptions_data, "maximum_dots") <- maximum_dots
-  attr(assumptions_data, "model_class") <- class(x)[1]
+  attr(assumptions_data, "model_class") <- class(model)[1]
   assumptions_data
 }
 
@@ -377,7 +388,7 @@
 
 #' @export
 check_model.stanreg <- function(
-  x,
+  model,
   panel = TRUE,
   check = "all",
   detrend = TRUE,
@@ -397,10 +408,11 @@
   colors = c("#3aaf85", "#1b6ca8", "#cd201f"),
   theme = see::theme_lucid(),
   verbose = FALSE,
+  x = NULL,
   ...
 ) {
   check_model(
-    bayestestR::bayesian_as_frequentist(x),
+    bayestestR::bayesian_as_frequentist(model),
     size_dot = size_dot,
     size_line = size_line,
     panel = panel,
@@ -419,6 +431,7 @@
     residual_type = residual_type,
     maximum_dots = maximum_dots,
     verbose = verbose,
+    x = x,
     ...
   )
 }
@@ -430,7 +443,7 @@
 
 #' @export
 check_model.model_fit <- function(
-  x,
+  model,
   panel = TRUE,
   check = "all",
   detrend = TRUE,
@@ -450,10 +463,11 @@
   colors = c("#3aaf85", "#1b6ca8", "#cd201f"),
   theme = see::theme_lucid(),
   verbose = FALSE,
+  x = NULL,
   ...
 ) {
   check_model(
-    x$fit,
+    model$fit,
     size_dot = size_dot,
     size_line = size_line,
     panel = panel,
@@ -472,14 +486,15 @@
     type = type,
     residual_type = residual_type,
     verbose = verbose,
+    x = x,
     ...
   )
 }
 
 
 #' @export
 check_model.performance_simres <- function(
-  x,
+  model,
   panel = TRUE,
   check = "all",
   detrend = TRUE,
@@ -499,10 +514,11 @@
   colors = c("#3aaf85", "#1b6ca8", "#cd201f"),
   theme = see::theme_lucid(),
   verbose = FALSE,
+  x = NULL,
   ...
 ) {
   check_model(
-    x$fittedModel,
+    model$fittedModel,
     size_dot = size_dot,
     size_line = size_line,
     panel = panel,
@@ -521,6 +537,7 @@
     type = type,
     residual_type = "simulated",
     verbose = verbose,
+    x = x,
     ...
   )
 }