Range keys

These functions are helper functions for working with ranged data as keys in guides. They all share the goal creating of a guide key, but have different methods:

key_range_auto() is a function factory whose functions make an attempt to infer ranges from the scale's labels.
key_range_manual() uses user-provided vectors to set ranges.
key_range_map() makes mappings from a <data.frame> to set ranges.

Usage

key_range_auto(sep = "[^[:alnum:]]+", reverse = FALSE)

key_range_manual(start, end, name = NULL, level = NULL)

key_range_map(data, ..., .call = caller_env())

Arguments

sep: A <character[1]> giving a regular expression to use for splitting labels provided by the scale using strsplit(). Defaults to splitting on any non-alphanumeric character.
reverse: A <logical[1]> which if FALSE (default) treats the first labels as the inner labels and the last labels as the outer labels. If TRUE, thee first labels are treated as the outer labels and the last labels are treated as the inner labels.
start, end: A vector that can be interpreted by the scale, giving the start and end positions of each range respectively.
name: A <character> or list of expressions
level: An <integer> giving the depth of each range to avoid overlaps between different ranges. When level is smaller than 1, no brackets are drawn.
data: A <data.frame> or similar object coerced by fortify() to a <data.frame>, in which the mapping argument is evaluated.
...: <data-masking> A set of mappings similar to those provided to aes(), which will be evaluated in the data argument. These must contain start and end mappings.
.call: A call to display in messages.

Value

For key_range_auto() a function. For key_range_manual() and key_range_map() a <data.frame> with the <key_range> class.

Details

The level variable is optional and when missing, the guides use an algorithm similar to IRanges::disjointBins() to avoid overlaps.

The key_range_auto() does not work with expression labels.

Examples

# Example scale
template <- scale_x_discrete(limits = c("A 1", "B 1", "C&1", "D&2", "E&2"))

# By default, splits on all non-alphanumeric characters
auto <- key_range_auto()
auto(template)
#>   start end .label .level
#> 1     1   1      A      0
#> 2     2   2      B      0
#> 3     3   3      C      0
#> 4     4   4      D      0
#> 5     5   5      E      0
#> 6     1   3      1      1
#> 7     4   5      2      1

# Only split on a specific character
auto <- key_range_auto(sep = "&")
auto(template)
#> Warning: Not all labels in `key_range_auto()` can be split into equal lengths.
#> ℹ Is "&" the correct `sep` argument?
#>   start end .label .level
#> 1     1   1    A 1      0
#> 2     2   2    B 1      0
#> 3     3   3      C      0
#> 4     4   4      D      0
#> 5     5   5      E      0
#> 6     3   3      1      1
#> 7     4   5      2      1

# Treating the letters as outer labels and numbers as inner labels
auto <- key_range_auto(reverse = TRUE)
auto(template)
#>    start end .label .level
#> 1      1   1      1      0
#> 2      2   2      1      0
#> 3      3   3      1      0
#> 4      4   4      2      0
#> 5      5   5      2      0
#> 6      1   1      A      1
#> 7      2   2      B      1
#> 8      3   3      C      1
#> 9      4   4      D      1
#> 10     5   5      E      1

# Providing custom values
key_range_manual(
  start = c(1, 5,  10),
  end   = c(4, 15, 11),
  level = c(0, 2, 1),
  name  = c("A", "B", "C")
)
#>   start end .label .level
#> 1     1   4      A      0
#> 2     5  15      B      2
#> 3    10  11      C      1

# Values from a <data.frame>
key_range_map(presidential, start = start, end = end, name = name)
#>         start        end     .label
#> 1  1953-01-20 1961-01-20 Eisenhower
#> 2  1961-01-20 1963-11-22    Kennedy
#> 3  1963-11-22 1969-01-20    Johnson
#> 4  1969-01-20 1974-08-09      Nixon
#> 5  1974-08-09 1977-01-20       Ford
#> 6  1977-01-20 1981-01-20     Carter
#> 7  1981-01-20 1989-01-20     Reagan
#> 8  1989-01-20 1993-01-20       Bush
#> 9  1993-01-20 2001-01-20    Clinton
#> 10 2001-01-20 2009-01-20       Bush
#> 11 2009-01-20 2017-01-20      Obama
#> 12 2017-01-20 2021-01-20      Trump

Usage

Arguments

Value

Details

See also

Examples