bi_class_breaks {biscale}

Return Breaks

Description

This function can be used to return a list containing vectors of either the ranges of values included in each category of x and y or, alternatively, the individual break values including the minimum and maximum values. This function supports simplified reporting as well as more descriptive legends.

Usage

bi_class_breaks(.data, x, y, style, dim = 3, clean_levels = TRUE,
    dig_lab = 3, split = FALSE)

Arguments

.data

A data frame, tibble, or sf object

x

The x variable, either a numeric (including double and integer classes) or factor

y

The y variable, either a numeric (including double and integer classes) or factor

style

A string identifying the style used to calculate breaks. Currently supported styles are "quantile" (default), "equal", "fisher", and "jenks". If both x and y are factors, this argument can be omitted.

dim

The dimensions of the palette. To use the built-in palettes, this value must be either 2, 3, or 4. A value of 3, for example, would be used to create a three-by-three bivariate map with a total of 9 classes.

If you are using a custom palette, this value may be larger (though these maps can be very hard to interpret).

If you are using pre-made factors, both factors must have the same number of levels as this value.

clean_levels

A logical scalar; if TRUE (default), the brackets and parentheses will be stripped from the output. If FALSE (default), the levels will be returned with brackets and parentheses. If split is TRUE and clean_levels is FALSE, the clean_levels argument will be overridden.

dig_lab

An integer that is passed to base::cut(); it determines the number of digits used in formatting break numbers. It can either be a scalar or a vector. If it is a scalar, the value will be applied to both the x and y variables. If it is a vector, the first element will be applied to the x variable and the second will be applied to the y variable.

split

A logical scalar; if FALSE (default), the range of values for each factor level (corresponds to dim) will be returned for both the x and y variables. If TRUE, the individual values for each break (including the minimum and maximum values) will be returned.

Value

A list where bi_x is a vector containing the breaks for the x variable and bi_y is a vector containing the breaks for the y variable.

Examples

# return ranges for each category of x and y
bi_class_breaks(stl_race_income, style = "quantile", x = pctWhite, y = medInc,
    dim = 4, dig_lab = c(4, 5), split = FALSE)

# ranges can be returned with brackets and parentheses
bi_class_breaks(stl_race_income, style = "quantile", x = pctWhite, y = medInc,
    clean_levels = FALSE, dim = 4, dig_lab = 3, split = FALSE)

# return breaks for each category of x and y
bi_class_breaks(stl_race_income, style = "quantile", x = pctWhite, y = medInc,
    dim = 4, dig_lab = c(4, 5), split = TRUE)

# optionally name vector for dig_lab for increased clarity of code
bi_class_breaks(stl_race_income, style = "quantile", x = pctWhite, y = medInc,
    dim = 4, dig_lab = c(x = 4, y = 5), split = TRUE)

# scalars can also be used for dig_lab, though results may be less optimal
bi_class_breaks(stl_race_income, style = "quantile", x = pctWhite, y = medInc,
    dim = 4, dig_lab = 3, split = TRUE)