Rename group/group_by arguments into by (#433)

* Rename `group`/`group_by` arguments into `by` * fix report_participants * fix news * use insight remotes * deprecation warning * lintr * ... * fix * update tests * fix * fix * fix * update snapshots * update readme * add remotes
easystats · May 24, 2024 · bf636ee · bf636ee
1 parent 201e979
commit bf636ee
Show file tree

Hide file tree

Showing 14 changed files with 205 additions and 167 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,7 +1,7 @@
 Package: report
 Type: Package
 Title: Automated Reporting of Results and Statistical Models
-Version: 0.5.8.2
+Version: 0.5.8.3
 Authors@R:
     c(person(given = "Dominique",
              family = "Makowski",
@@ -150,3 +150,4 @@ Collate:
     'utils_grouped_df.R'
     'zzz.R'
 Roxygen: list(markdown = TRUE)
+Remotes: easystats/insight, easystats/datawizard, easystats/parameters, easystats/performance, easystats/modelbased
diff --git a/NEWS.md b/NEWS.md
@@ -1,5 +1,14 @@
 # report 0.5.9
 
+Breaking
+
+* Arguments named `group`, `at` and `group_by` will be deprecated in future
+  releases. of _easystats_ packages. Please use `by` instead. This affects
+  following functions in *report*:
+
+  * `report_participants()`
+  * `report_sample()`
+
 Minor changes 
 
 * `report` now supports reporting of Bayesian model comparison with variables of class `brms::loo_compare`.

diff --git a/R/report.lm.R b/R/report.lm.R
@@ -483,7 +483,7 @@ report_info.lm <- function(x,
     effectsize <- report_effectsize(x, ...)
   }
 
-  text <- .info_effectsize(x, effectsize = effectsize, include_effectsize = include_effectsize)
+  info_text <- .info_effectsize(x, effectsize = effectsize, include_effectsize = include_effectsize)
 
   if (is.null(parameters)) {
     parameters <- report_parameters(x, ...)
@@ -495,7 +495,7 @@ report_info.lm <- function(x,
   }
 
   if ("ci_method" %in% names(att)) {
-    text <- paste0(text, " ", .info_df(
+    info_text <- paste0(info_text, " ", .info_df(
       ci = att$ci,
       ci_method = att$ci_method,
       test_statistic = att$test_statistic,
@@ -508,7 +508,7 @@ report_info.lm <- function(x,
   # }
 
 
-  as.report_info(text)
+  as.report_info(info_text)
 }
 
 
@@ -538,25 +538,25 @@ report_text.lm <- function(x, table = NULL, ...) {
     model,
     ". ",
     perf,
-    ifelse(nchar(perf) > 0, ". ", ""),
+    ifelse(nzchar(perf, keepNA = TRUE), ". ", ""),
     intercept,
     params_text_full,
     "\n\n",
     info
   )
 
-  text <- paste0(
+  summary_text <- paste0(
     "We fitted a ",
     summary(model),
     ". ",
     summary(perf),
-    ifelse(nchar(perf) > 0, ". ", ""),
+    ifelse(nzchar(perf, keepNA = TRUE), ". ", ""),
     summary(intercept),
     params_text
   )
 
 
-  as.report_text(text_full, summary = text)
+  as.report_text(text_full, summary = summary_text)
 }
 
 
@@ -569,7 +569,7 @@ report_text.lm <- function(x, table = NULL, ...) {
   if (!is.null(coefname) && coefname %in% names(table)) {
     estimate <- attributes(table)$coefficient_name
   } else {
-    estimate <- datawizard::data_find(table, candidates, regex = TRUE, verbose = FALSE)[1]
+    estimate <- datawizard::extract_column_names(table, candidates, regex = TRUE, verbose = FALSE)[1]
   }
   estimate
 }
diff --git a/R/report_htest_ttest.R b/R/report_htest_ttest.R
@@ -33,25 +33,25 @@
 
 .report_table_ttest <- function(table_full, effsize) {
   table_full <- cbind(table_full, attributes(effsize)$table)
-  table <- datawizard::data_remove(
+  table_small <- datawizard::data_remove(
     table_full,
     c("Parameter", "Group", "Mean_Group1", "Mean_Group2", "Method", "d_CI_low", "d_CI_high")
   )
-  list(table = table, table_full = table_full)
+  list(table = table_small, table_full = table_full)
 }
 
 
 # report_effectsize ---------------------
 
 .report_effectsize_ttest <- function(x, table, dot_args, type, rules = "cohen1988") {
-  args <- c(list(x), dot_args)
-  table <- do.call(effectsize::effectsize, args)
+  my_args <- c(list(x), dot_args)
+  table <- do.call(effectsize::effectsize, my_args)
   ci <- attributes(table)$ci
   estimate <- names(table)[1]
   rules <- ifelse(is.null(dot_args$rules), rules, dot_args$rules)
 
-  args <- list(table, rules = rules, dot_args)
-  interpretation <- do.call(effectsize::interpret, args)$Interpretation
+  my_args <- list(table, rules = rules, dot_args)
+  interpretation <- do.call(effectsize::interpret, my_args)$Interpretation
   rules <- .text_effectsize(attr(attr(interpretation, "rules"), "rule_name"))
 
   if (estimate %in% c("d", "Cohens_d")) {
@@ -88,7 +88,7 @@
 .report_model_ttest <- function(x, table) {
   # If against mu
   if (names(x$null.value) == "mean") {
-    # TODO: @DominiqueMakowski why do we need "table" here?
+    # TODO: @DominiqueMakowski why do we need "table" here??
 
     table$Difference <- x$estimate - x$null.value
     means <- paste0(" (mean = ", insight::format_value(x$estimate), ")")
@@ -106,12 +106,12 @@
     vars <- paste0(x$data.name)
   }
 
-  text <- paste0(
+  final_text <- paste0(
     trimws(x$method),
     " testing the difference ",
     ifelse(grepl(" by ", x$data.name, fixed = TRUE), "of ", "between "),
     vars_full
   )
 
-  text
+  final_text
 }
diff --git a/R/report_participants.R b/R/report_participants.R
@@ -21,11 +21,12 @@
 #' so countries that represent less than 10% will be combined in the "other" category).
 #' @param participants The name of the participants' identifier column (for
 #'   instance in the case of repeated measures).
-#' @param group A character vector indicating the name(s) of the column(s) used
+#' @param by A character vector indicating the name(s) of the column(s) used
 #'   for stratified description.
 #' @param spell_n Logical, fully spell the sample size (`"Three participants"`
 #'   instead of `"3 participants"`).
 #' @inheritParams report.numeric
+#' @param group Deprecated. Use `by` instead.
 #'
 #' @return A character vector with description of the "participants", based on
 #'   the information provided in `data`.
@@ -106,7 +107,7 @@
 #'   sex = "Sex",
 #'   gender = "Gender",
 #'   participants = "Participant",
-#'   group = "Condition"
+#'   by = "Condition"
 #' )
 #'
 #' # Spell sample size
@@ -123,14 +124,21 @@ report_participants <- function(data,
                                 country = NULL,
                                 race = NULL,
                                 participants = NULL,
-                                group = NULL,
+                                by = NULL,
                                 spell_n = FALSE,
                                 digits = 1,
                                 threshold = 10,
+                                group = NULL,
                                 ...) {
+  ## TODO: deprecate later
+  if (!is.null(group)) {
+    insight::format_warning("Argument `group` is deprecated and will be removed in a future release. Please use `by` instead.") # nolint
+    by <- group
+  }
+
   # Convert empty strings to NA
   data_list <- lapply(data, function(x) {
-    x[which(x == "")] <- NA
+    x[which(x == "")] <- NA # nolint
     x
   })
   data <- as.data.frame(data_list, stringsAsFactors = FALSE)
@@ -165,8 +173,8 @@ report_participants <- function(data,
     race <- .find_race_in_data(data)
   }
 
-  if (is.null(group)) {
-    text <- .report_participants(
+  if (is.null(by)) {
+    final_text <- .report_participants(
       data,
       age = age,
       sex = sex,
@@ -181,9 +189,9 @@ report_participants <- function(data,
       ...
     )
   } else {
-    text <- NULL
-    data[[group]] <- as.character(data[[group]])
-    for (i in split(data, data[group])) {
+    final_text <- NULL
+    data[[by]] <- as.character(data[[by]])
+    for (i in split(data, data[by])) {
       current_text <- .report_participants(
         i,
         age = age,
@@ -200,15 +208,15 @@ report_participants <- function(data,
 
       pre_text <- paste0(
         "the '",
-        paste0(names(i[group]), " - ", vapply(i[group], unique, "character"), collapse = " and "),
+        paste0(names(i[by]), " - ", vapply(i[by], unique, "character"), collapse = " and "),
         "' group: "
       )
 
-      text <- c(text, paste0(pre_text, current_text))
+      final_text <- c(final_text, paste0(pre_text, current_text))
     }
-    text <- paste("For", datawizard::text_concatenate(text, sep = ", for ", last = " and for "))
+    final_text <- paste("For", datawizard::text_concatenate(final_text, sep = ", for ", last = " and for "))
   }
-  text
+  final_text
 }
 
 #' @keywords internal
@@ -338,9 +346,7 @@ report_participants <- function(data,
       ) %in% c("male", "m", "female", "f", NA, "na")]) /
         nrow(data) * 100, digits = digits),
       "% other",
-      if (!insight::format_value(length(data[[sex]][tolower(
-        data[[sex]]
-      ) %in% c(NA, "na")]) / nrow(data) * 100) == "0.00") {
+      if (insight::format_value(length(data[[sex]][tolower(data[[sex]]) %in% c(NA, "na")]) / nrow(data) * 100) != "0.00") { # nolint
         paste0(", ", insight::format_value(length(data[[sex]][tolower(
           data[[sex]]
         ) %in% c(NA, "na")]) / nrow(data) * 100), "% missing")
@@ -375,9 +381,9 @@ report_participants <- function(data,
         data[[gender]]
       ) %in% both_genders]) /
         nrow(data) * 100), "% non-binary",
-      if (!insight::format_value(length(data[[gender]][tolower(
+      if (insight::format_value(length(data[[gender]][tolower(
         data[[gender]]
-      ) %in% c(NA, "na")]) / nrow(data) * 100) == "0.00") {
+      ) %in% c(NA, "na")]) / nrow(data) * 100) != "0.00") {
         paste0(", ", insight::format_value(length(data[[gender]][tolower(
           data[[gender]]
         ) %in% c(NA, "na")]) / nrow(data) * 100), "% missing")
@@ -387,31 +393,29 @@ report_participants <- function(data,
 
   if (all(is.na(data[[education]]))) {
     text_education <- ""
-  } else {
-    if (is.numeric(data[[education]])) {
-      text_education <- summary(
-        report_statistics(
-          data[[education]],
-          n = FALSE,
-          centrality = "mean",
-          missing_percentage = NULL,
-          digits = digits,
-          ...
-        )
-      )
-
-      text_education <- sub("Mean =", "Mean education =", text_education, fixed = TRUE)
-    } else {
-      data[which(data[[education]] %in% c(NA, "NA")), education] <- "missing"
-      txt <- summary(report_statistics(
-        as.factor(data[[education]]),
-        levels_percentage = TRUE,
+  } else if (is.numeric(data[[education]])) {
+    text_education <- summary(
+      report_statistics(
+        data[[education]],
+        n = FALSE,
+        centrality = "mean",
+        missing_percentage = NULL,
         digits = digits,
         ...
-      ))
+      )
+    )
 
-      text_education <- paste0("Education: ", txt)
-    }
+    text_education <- sub("Mean =", "Mean education =", text_education, fixed = TRUE)
+  } else {
+    data[which(data[[education]] %in% c(NA, "NA")), education] <- "missing"
+    txt <- summary(report_statistics(
+      as.factor(data[[education]]),
+      levels_percentage = TRUE,
+      digits = digits,
+      ...
+    ))
+
+    text_education <- paste0("Education: ", txt)
   }
 
   text_country <- if (all(is.na(data[[country]]))) {
@@ -468,6 +472,7 @@ report_participants <- function(data,
     text_race <- paste("Race:", value_string)
   }
 
+  # nolint start
   paste0(
     size,
     " participants (",
@@ -491,6 +496,7 @@ report_participants <- function(data,
     ), text_race)),
     ")"
   )
+  # nolint end
 }
 
 #' @keywords internal