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 usingstrsplit(). Defaults to splitting on any non-alphanumeric character.- reverse
A
<logical[1]>which ifFALSE(default) treats the first labels as the inner labels and the last labels as the outer labels. IfTRUE, 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 toaes(), which will be evaluated in thedataargument. Forkey_range_map(), these must containstartandendmappings. Can contain additional parameters for text styling, namelycolour,family,face,size,hjust,vjust,angleandlineheight.- 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. Whenlevelis smaller than 1, no brackets are drawn.- data
A
<data.frame>or similar object coerced byfortify()to a<data.frame>, in which themappingargument is evaluated.- .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.
See also
Other keys:
key_group,
key_segments,
key_specialty,
key_standard
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