Harmonizing argument names for check_* functions (#886)

Author: strengejacke

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.
 
+* The first argument in `check_model()`, `check_predictions()` and
+  `check_convergence()` was renamed to `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,16 @@
 #' 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
+  }
+  .is_model_valid(model)
+  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.
@@ -191,7 +193,7 @@
 #' check_model(m, panel = FALSE)
 #' }
 #' @export
-check_model <- function(x, ...) {
+check_model <- function(model = NULL, ...) {
   UseMethod("check_model")
 }
 
@@ -201,7 +203,7 @@ check_model <- function(x, ...) {
 #' @rdname check_model
 #' @export
 check_model.default <- function(
-  x,
+  model = NULL,
   panel = TRUE,
   check = "all",
   detrend = TRUE,
@@ -221,14 +223,23 @@ check_model.default <- function(
   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 @@ check_model.default <- function(
 
   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 @@ check_model.default <- function(
       ))
     } else {
       suppressWarnings(.check_assumptions_glm(
-        x,
+        model,
         minfo,
         check,
         residual_type,
@@ -283,7 +294,7 @@ check_model.default <- function(
       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 @@ check_model.default <- function(
   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 @@ check_model.default <- function(
   }
 
   # 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
   }
@@ -322,7 +333,7 @@ check_model.default <- function(
   }
 
   # 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 @@ check_model.default <- function(
   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 @@ plot.check_model <- function(x, ...) {
 
 #' @export
 check_model.stanreg <- function(
-  x,
+  model = NULL,
   panel = TRUE,
   check = "all",
   detrend = TRUE,
@@ -397,10 +408,19 @@ check_model.stanreg <- function(
   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(
-    bayestestR::bayesian_as_frequentist(x),
+    model = .safe(bayestestR::bayesian_as_frequentist(model)),
     size_dot = size_dot,
     size_line = size_line,
     panel = panel,
@@ -430,7 +450,7 @@ check_model.brmsfit <- check_model.stanreg
 
 #' @export
 check_model.model_fit <- function(
-  x,
+  model = NULL,
   panel = TRUE,
   check = "all",
   detrend = TRUE,
@@ -450,10 +470,19 @@ check_model.model_fit <- function(
   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(
-    x$fit,
+    model$fit,
     size_dot = size_dot,
     size_line = size_line,
     panel = panel,
@@ -479,7 +508,7 @@ check_model.model_fit <- function(
 
 #' @export
 check_model.performance_simres <- function(
-  x,
+  model = NULL,
   panel = TRUE,
   check = "all",
   detrend = TRUE,
@@ -499,10 +528,19 @@ check_model.performance_simres <- function(
   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(
-    x$fittedModel,
+    model$fittedModel,
     size_dot = size_dot,
     size_line = size_line,
     panel = panel,