From c33a8da6a408b8aff45eb39a86e62f8011243ad3 Mon Sep 17 00:00:00 2001
From: Daniel <mail@danielluedecke.de>
Date: Wed, 2 Oct 2024 17:17:56 +0200
Subject: [PATCH] add test, docs

---
 R/categorize.R                      |  7 ++++++
 man/categorize.Rd                   |  7 ++++++
 tests/testthat/_snaps/categorize.md | 33 +++++++++++++++++++++++++++++
 tests/testthat/test-categorize.R    |  9 ++++++++
 4 files changed, 56 insertions(+)
 create mode 100644 tests/testthat/_snaps/categorize.md

diff --git a/R/categorize.R b/R/categorize.R
index 61d4b4c96..b43a965b8 100644
--- a/R/categorize.R
+++ b/R/categorize.R
@@ -122,6 +122,13 @@
 #' x <- sample(1:10, size = 30, replace = TRUE)
 #' categorize(x, "equal_length", n_groups = 3, labels = "mean")
 #' categorize(x, "equal_length", n_groups = 3, labels = "median")
+#'
+#' # cut numeric into groups with the requested range as a label name
+#' # each category has the same range, and labels indicate this range
+#' categorize(mtcars$mpg, "equal_length", n_groups = 5, labels = "range")
+#' # in this example, each category has the same range, but labels only refer
+#' # to the ranges of the actual values (present in the data) inside each group
+#' categorize(mtcars$mpg, "equal_length", n_groups = 5, labels = "observed")
 #' @export
 categorize <- function(x, ...) {
   UseMethod("categorize")
diff --git a/man/categorize.Rd b/man/categorize.Rd
index eed5ecbab..8d3ffcd8e 100644
--- a/man/categorize.Rd
+++ b/man/categorize.Rd
@@ -220,6 +220,13 @@ categorize(x, "equal_length", n_groups = 3, labels = c("low", "mid", "high"))
 x <- sample(1:10, size = 30, replace = TRUE)
 categorize(x, "equal_length", n_groups = 3, labels = "mean")
 categorize(x, "equal_length", n_groups = 3, labels = "median")
+
+# cut numeric into groups with the requested range as a label name
+# each category has the same range, and labels indicate this range
+categorize(mtcars$mpg, "equal_length", n_groups = 5, labels = "range")
+# in this example, each category has the same range, but labels only refer
+# to the ranges of the actual values (present in the data) inside each group
+categorize(mtcars$mpg, "equal_length", n_groups = 5, labels = "observed")
 }
 \seealso{
 \itemize{
diff --git a/tests/testthat/_snaps/categorize.md b/tests/testthat/_snaps/categorize.md
new file mode 100644
index 000000000..1b8f9fd64
--- /dev/null
+++ b/tests/testthat/_snaps/categorize.md
@@ -0,0 +1,33 @@
+# categorize labelling ranged
+
+    Code
+      categorize(mtcars$mpg, "equal_length", n_groups = 5)
+    Output
+       [1] 3 3 3 3 2 2 1 3 3 2 2 2 2 2 1 1 1 5 5 5 3 2 2 1 2 4 4 5 2 2 1 3
+
+---
+
+    Code
+      categorize(mtcars$mpg, "equal_length", n_groups = 5, labels = "range")
+    Output
+       [1] [19.8,24.5) [19.8,24.5) [19.8,24.5) [19.8,24.5) [15.1,19.8) [15.1,19.8)
+       [7] [10.4,15.1) [19.8,24.5) [19.8,24.5) [15.1,19.8) [15.1,19.8) [15.1,19.8)
+      [13] [15.1,19.8) [15.1,19.8) [10.4,15.1) [10.4,15.1) [10.4,15.1) [29.2,33.9]
+      [19] [29.2,33.9] [29.2,33.9] [19.8,24.5) [15.1,19.8) [15.1,19.8) [10.4,15.1)
+      [25] [15.1,19.8) [24.5,29.2) [24.5,29.2) [29.2,33.9] [15.1,19.8) [15.1,19.8)
+      [31] [10.4,15.1) [19.8,24.5)
+      Levels: [10.4,15.1) [15.1,19.8) [19.8,24.5) [24.5,29.2) [29.2,33.9]
+
+---
+
+    Code
+      categorize(mtcars$mpg, "equal_length", n_groups = 5, labels = "observed")
+    Output
+       [1] (21-24.4)   (21-24.4)   (21-24.4)   (21-24.4)   (15.2-19.7) (15.2-19.7)
+       [7] (10.4-15)   (21-24.4)   (21-24.4)   (15.2-19.7) (15.2-19.7) (15.2-19.7)
+      [13] (15.2-19.7) (15.2-19.7) (10.4-15)   (10.4-15)   (10.4-15)   (30.4-33.9)
+      [19] (30.4-33.9) (30.4-33.9) (21-24.4)   (15.2-19.7) (15.2-19.7) (10.4-15)  
+      [25] (15.2-19.7) (26-27.3)   (26-27.3)   (30.4-33.9) (15.2-19.7) (15.2-19.7)
+      [31] (10.4-15)   (21-24.4)  
+      Levels: (10.4-15) (15.2-19.7) (21-24.4) (26-27.3) (30.4-33.9)
+
diff --git a/tests/testthat/test-categorize.R b/tests/testthat/test-categorize.R
index 0e0b5d317..2c81b0eec 100644
--- a/tests/testthat/test-categorize.R
+++ b/tests/testthat/test-categorize.R
@@ -232,3 +232,12 @@ test_that("categorize regex", {
     categorize(mtcars, select = "mpg")
   )
 })
+
+
+# select helpers ------------------------------
+test_that("categorize labelling ranged", {
+  data(mtcars)
+  expect_snapshot(categorize(mtcars$mpg, "equal_length", n_groups = 5))
+  expect_snapshot(categorize(mtcars$mpg, "equal_length", n_groups = 5, labels = "range"))
+  expect_snapshot(categorize(mtcars$mpg, "equal_length", n_groups = 5, labels = "observed"))
+})