Skip to contents

Group keys

key_group.Rd

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

  • key_group_auto() is a function factory whose functions make an attempt to infer groups from the scale's labels.

  • key_group_lut() is a function factory whose functions use a look up table to sort out group membership.

Usage

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

key_group_lut(members, group, ungrouped = "Other")

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 part of the split string as groups, and if TRUE treats the last part as groups.

members

A vector including the scale's breaks values.

group

A vector parallel to members giving the group of every member.

ungrouped

A <character[1]> giving a group label to assign to the scale's breaks that match no values in the members argument.

Value

For key_group_auto() and key_group_lut(), a function.

Details

The resulting key is always sorted by group. The key_group_auto() does not work with expression labels.

See also

Other keys: key_range, key_specialty, key_standard

Examples

# Example scale
values <- c("group A:value 1", "group A:value 2", "group B:value 1")
template <- scale_colour_discrete(limits = values)

# Treat the 'group X' part as groups
auto <- key_group_auto(sep = ":")
auto(template)
#>    colour          .value  .label  .group
#> 1 #F8766D group A:value 1 value 1 group A
#> 2 #00BA38 group A:value 2 value 2 group A
#> 3 #619CFF group B:value 1 value 1 group B

# Treat the 'value X' part as groups
auto <- key_group_auto(sep = ":", reverse = TRUE)
auto(template)
#>    colour          .value  .label  .group
#> 1 #F8766D group A:value 1 group A value 1
#> 2 #619CFF group B:value 1 group B value 1
#> 3 #00BA38 group A:value 2 group A value 2

# Example scale
template <- scale_colour_discrete(limits = msleep$name[c(1, 7, 9, 23, 24)])

# A lookup table can have more entries than needed
lut <- key_group_lut(msleep$name, msleep$order)
lut(template)
#>    colour            .value            .label         .group
#> 1 #F8766D           Cheetah           Cheetah      Carnivora
#> 2 #A3A500 Northern fur seal Northern fur seal      Carnivora
#> 3 #00BF7D               Dog               Dog      Carnivora
#> 4 #00B0F6             Horse             Horse Perissodactyla
#> 5 #E76BF3            Donkey            Donkey Perissodactyla

# Or less entries than needed
lut <- key_group_lut(
  msleep$name[23:24], msleep$order[23:24],
  ungrouped = "Other animals"
)
lut(template)
#>    colour            .value            .label         .group
#> 1 #00B0F6             Horse             Horse Perissodactyla
#> 2 #E76BF3            Donkey            Donkey Perissodactyla
#> 3 #F8766D           Cheetah           Cheetah  Other animals
#> 4 #A3A500 Northern fur seal Northern fur seal  Other animals
#> 5 #00BF7D               Dog               Dog  Other animals