datawizard (version 0.4.0)

data_cut: Recode (or "cut") data into groups of values.

Description

This functions divides the range of variables into intervals and recodes the values inside these intervals according to their related interval. It is basically a wrapper around base R's cut(), providing a simplified and more accessible way to define the interval breaks (cut-off values).

Usage

data_cut(x, ...)
# S3 method for numeric
data_cut(
  x,
  split = "median",
  n_groups = NULL,
  range = NULL,
  lowest = 1,
  labels = NULL,
  verbose = TRUE,
  ...
)
# S3 method for data.frame
data_cut(
  x,
  split = "median",
  n_groups = NULL,
  range = NULL,
  lowest = 1,
  labels = NULL,
  force = FALSE,
  append = FALSE,
  select = NULL,
  exclude = NULL,
  ignore_case = FALSE,
  verbose = TRUE,
  ...
)

Arguments

x

A (grouped) data frame, numeric vector or factor.

...

not used.

split

Character vector, indicating at which breaks to split variables, or numeric values with values indicating breaks. If character, may be one of "median", "mean", "quantile", "equal_length", or "equal_range". "median" or "mean" will return dichotomous variables, split at their mean or median, respectively. "quantile" and "equal_length" will split the variable into n_groups groups, where each group refers to an interval of a specific range of values. Thus, the length of each interval will be based on the number of groups. "equal_range" also splits the variable into multiple groups, however, the length of the interval is given, and the number of resulting groups (and hence, the number of breaks) will be determined by how many intervals can be generated, based on the full range of the variable.

n_groups

If split is "quantile" or "equal_length", this defines the number of requested groups (i.e. resulting number of levels or values) for the recoded variable(s). "quantile" will define intervals based on the distribution of the variable, while "equal_length" tries to divide the range of the variable into pieces of equal length.

range

If split = "equal_range", this defines the range of values that are recoded into a new value.

lowest

Minimum value of the recoded variable(s). If NULL (the default), for numeric variables, the minimum of the original input is preserved. For factors, the default minimum is 1. For split = "equal_range", the default minimum is always 1, unless specified otherwise in lowest.

labels

Character vector of value labels. If not NULL, data_cut() will returns factors instead of numeric variables, with labels used for labelling the factor levels.

verbose

Toggle warnings.

force

Logical, if TRUE, forces recoding of factors as well.

append

Logical or string. If TRUE, recoded variables get new column names (with the suffix "_r") and are appended (column bind) to x, thus returning both the original and the recoded variables. If FALSE, original variables in x will be overwritten by their recoded versions. If a character value, recoded variables are appended with new column names (using the defined suffix) to the original data frame.

select

Variables that will be included when performing the required tasks. Can be either

• a variable specified as a literal variable name (e.g., column_name),

• a string with the variable name (e.g., "column_name"), or a character vector of variable names (e.g., c("col1", "col2", "col3")),

• a formula with variable names (e.g., ~column_1 + column_2),

• a vector of positive integers, giving the positions counting from the left (e.g. 1 or c(1, 3, 5)),

• a vector of negative integers, giving the positions counting from the right (e.g., -1 or -1:-3),

• or one of the following select-helpers: starts_with(""), ends_with(""), contains(""), a range using : or regex("").

If NULL, selects all columns.

exclude

See select, however, column names matched by the pattern from exclude will be excluded instead of selected. If NULL (the default), excludes no columns.

ignore_case

Logical, if TRUE and when one of the select-helpers or a regular expression is used in select, ignores lower/upper case in the search pattern when matching against variable names.

Value

x, recoded into groups. By default x is numeric, unless labels is specified. In this case, a factor is returned, where the factor levels (i.e. recoded groups are labelled accordingly.

Details

Splits and breaks (cut-off values)

Breaks are in general exclusive, this means that these values indicate the lower bound of the next group or interval to begin. Take a simple example, a numeric variable with values from 1 to 9. The median would be 5, thus the first interval ranges from 1-4 and is recoded into 1, while 5-9 would turn into 2 (compare cbind(1:9, data_cut(1:9))). The same variable, using split = "quantile" and n_groups = 3 would define breaks at 3.67 and 6.33 (see quantile(1:9, probs = c(1/3, 2/3)), which means that values from 1 to 3 belong to the first interval and are recoded into 1 (because the next interval starts at 3.67), 4 to 6 into 2 and 7 to 9 into 3.

Recoding into groups with equal size or range

split = "equal_length" and split = "equal_range" try to divide the range of x into intervals of similar (or same) length. The difference is that split = "equal_length" will divide the range of x into n_groups pieces and thereby defining the intervals used as breaks (hence, it is equivalent to cut(x, breaks = n_groups)), while split = "equal_range" will cut x into intervals that all have the length of range, where the first interval by defaults starts at 1. The lowest (or starting) value of that interval can be defined using the lowest argument.

Examples

# NOT RUN {
set.seed(123)
x <- sample(1:10, size = 50, replace = TRUE)

table(x)

# by default, at median
table(data_cut(x))

# into 3 groups, based on distribution (quantiles)
table(data_cut(x, split = "quantile", n_groups = 3))

# into 3 groups, user-defined break
table(data_cut(x, split = c(3, 5)))

set.seed(123)
x <- sample(1:100, size = 500, replace = TRUE)

# into 5 groups, try to recode into intervals of similar length,
# i.e. the range within groups is the same for all groups
table(data_cut(x, split = "equal_length", n_groups = 5))

# into 5 groups, try to return same range within groups
# i.e. 1-20, 21-40, 41-60, etc. Since the range of "x" is
# 1-100, and we have a range of 20, this results into 5
# groups, and thus is for this particular case identical
# to the previous result.
table(data_cut(x, split = "equal_range", range = 20))

# return factor with value labels instead of numeric value
set.seed(123)
x <- sample(1:10, size = 30, replace = TRUE)
data_cut(x, "equal_length", n_groups = 3)
data_cut(x, "equal_length", n_groups = 3, labels = c("low", "mid", "high"))
# }