Enhanced Numeric Data Categorization with cut

The cut function from the mStats package offers an enhanced and intuitive approach to categorizing numeric data into intervals, with improved labeling compared to the base cut function in R. It provides more flexibility in defining cut points and generates informative interval labels. The function handles both single numeric cut points and vector-based cut points, creating intervals accordingly. However, it does not accept NA, 1L, or missing values as the at argument. When using multiple elements in the at argument, it creates intervals with labels in the format of “lower value - upper value.”

This vignette demonstrates the usage of the cut function with various examples, showcasing its flexibility and convenience in data management tasks.

library(mStats)

Numeric Vector Example

Consider the following numeric vector x:

x <- 1:5
x
#> [1] 1 2 3 4 5

Single Numeric Cut Point

When using a single numeric cut point, cut creates equal bins similar to the base cut function:

cut(x, NA)
cut(x, 1)

The output divides x into equal intervals based on the cut point, with informative interval labels.

Multiple Numeric Cut Points

For multiple elements in the at argument, cut creates intervals based on the specified values:

cut(x, 2)
#> [1] 1-2 1-2 3-5 3-5 3-5
#> Levels: 1-2 3-5
cut(x, 5)
#> [1] 1-1.7   1.8-2.5 2.6-3.3 3.4-4.1 4.2-5  
#> Levels: 1-1.7 1.8-2.5 2.6-3.3 3.4-4.1 4.2-5
cut(x, c(3, 5))
#> [1] 1-2 1-2 3-5 3-5 3-5
#> Levels: 1-2 3-5

The output shows intervals that include the specified cut points, with labels in the format of “lower value-upper value” for each interval.

Handling Infinite Values

cut also handles infinite values in the at argument:

cut(x, c(-Inf, 2, Inf))
#> [1] 1-1 2-5 2-5 2-5 2-5
#> Levels: 1-1 2-5

In this example, -Inf represents negative infinity, and Inf represents positive infinity. The intervals are defined accordingly, incorporating the infinite values.

Vector-Based Cut Points

When using a vector as the at argument, cut categorizes x based on the provided values:

cut(x, 1:5)
#> [1] 1-1 2-2 3-3 4-5 4-5
#> Levels: 1-1 2-2 3-3 4-5

In this case, cut generates intervals based on each element in the at vector.

Invalid at Values

cut restricts the use of certain values for the at argument, such as NA, 1L, or missing values. It provides informative error messages when encountering such cases:

cut("x", 1)

Date Example

cut can also handle date objects. Let’s consider the following examples with date and time:

x <- Sys.Date() - 1:5
x
#> [1] "2026-10-05" "2026-10-04" "2026-10-03" "2026-10-02" "2026-10-01"
cut(x, 2)
#> [1] 2026-10-02 2026-10-02 2026-10-02 2026-10-05 2026-10-05
#> Levels: 2026-10-05 2026-10-02

In this example, cut categorizes the dates into intervals based on the specified cut points.

x <- Sys.time() - 1:5
x
#> [1] "2026-10-06 10:16:52 UTC" "2026-10-06 10:16:51 UTC"
#> [3] "2026-10-06 10:16:50 UTC" "2026-10-06 10:16:49 UTC"
#> [5] "2026-10-06 10:16:48 UTC"
cut(x, 2)
#> [1] 2026-10-06 10:16:49.513347 2026-10-06 10:16:49.513347
#> [3] 2026-10-06 10:16:49.513347 2026-10-06 10:16:52.513347
#> [5] 2026-10-06 10:16:52.513347
#> Levels: 2026-10-06 10:16:52.513347 2026-10-06 10:16:49.513347

For time objects, cut works similarly, categorizing the time values into intervals based on the provided cut points.

Conclusion

The cut function from the mStats package offers enhanced numeric data categorization with improved labeling. It provides flexibility in defining cut points, handles infinite values, and generates informative interval labels. By utilizing cut, users can easily categorize and analyze their numeric data, making data management tasks more intuitive and efficient.

For further information and additional features of the mStats package, please refer to the package documentation and explore its functionalities.