key_range: Range keys

Description

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())

Value

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

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.
...: <data-masking> A set of mappings similar to those provided to aes(), which will be evaluated in the data argument. For key_range_map(), these must contain start and end mappings. Can contain additional parameters for text styling, namely colour, family, face, size, hjust, vjust, angle and lineheight.
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.
.call: A call to display in messages.

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

Run this code

# 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)

# Only split on a specific character
auto <- key_range_auto(sep = "&")
auto(template)

# Treating the letters as outer labels and numbers as inner labels
auto <- key_range_auto(reverse = TRUE)
auto(template)

# 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")
)

# Values from a 
key_range_map(presidential, start = start, end = end, name = name)