Legend configuration

Parameters to customize legend in roboplots and robomaps.

Usage

set_legend(...)

set_plot_legend(
  position = NULL,
  orientation = NULL,
  maxwidth = NULL,
  title = FALSE,
  visible = NULL,
  reverse = getOption("roboplot.legend")$reverse,
  tidy = getOption("roboplot.legend")$tidy,
  xref = getOption("roboplot.legend")$xref,
  ...
)

set_map_legend(
  breaks = 5,
  position = "bottomleft",
  orientation = "vertical",
  title = NULL,
  opacity = 1,
  labformat = NULL,
  gradient = NULL,
  ...
)

Arguments

...

Arguments passed on to set_plot_legend, set_map_legend

position

Character. Either "bottom" or NA for no legend for roboplot, or one of "bottomleft", "bottomright", or "none" for robomap. On a roboplot, the legend is removed on default if column in data for param d of the roboplot that is defined by param color of that plot has only one observation.

orientation

Character. Currently unused.

maxwidth

Numeric. All roboplot legend items (and y-axis values for horizontal barplots) longer than this will be trunctated with an ellipsis.

title

Logical or character. TRUE if you want the parameter color from the roboplot to be the legend title. Character if you want to provide your own legend title.

visible

Character. A character vector of legend items initially selected to be visible in the legend, matching the arg color of roboplot. If NULL, all items are shown. Default is NULL. Items remains selectable to be visible in the legend regardless of this parameter.

reverse

Logical. Legend direction control. Default is FALSE.

tidy

Logical. Controls whether the roboplot legend items will have matching widths across columns. Default is FALSE.

xref

Character. Either "container" or "plot". Determines if the legend is positioned in relation to the plot or the container. Ignored for robomap().

breaks

Numeric vector. A length 1 vector attempts to make that many robomap legend entries. Length 2+ vector should be the breaks in values of param d of robomap where the legend should be split.

opacity

Numeric. The opacity of the robomap legend, ranging from 0 to 1.

labformat

Function. Specify custom label formatting function. The function must take a numeric vector of labels the map legend might have. Mostly useful for small number of specific labels.

gradient

Logical. If TRUE, the legend will be a gradient. Default TRUE for numeric data, FALSE for factor data.

Value

A list of class roboplotr.set_legend

Examples

# You can use `set_legend` to control how legends are displayed on a `roboplot()`.

d <- energiantuonti |>
  dplyr::filter(Alue == "Venäjä")

# Use `position` NA to remove the legend.
d |>
  roboplot(Suunta, legend = set_legend(position = NA))


# `roboplot()` omits the legend to give more space for the plot area, when there
# is only a single trace for `color`. Use `position` to force the legend to show.
# You can also use `title` to set a title.

d |>
  dplyr::filter(Suunta == "Tuonti") |>
  roboplot(Suunta, legend = set_legend(title = "Example", position = "bottom"))


# You can preset the initial items visible on the plot by using
# `set_legend(visible)` with items from the data passed to `roboplot(color)`.
 energiantuonti |>
  dplyr::filter(Suunta == "Vienti") |>
  roboplot(Alue,
           legend = set_legend(visible = c("Venäjä","Ruotsi"))
  )


# You can reverse the legend items with `set_legend(reverse = TRUE)` for whatever
# purpose you might have. The reverting is in relation to factor levels of the
# column.
energiantuonti |>
  dplyr::filter(Suunta == "Vienti") |>
  dplyr::mutate(Alue = forcats::fct_relevel(Alue, "Venäjä") |> forcats::fct_rev()) |>
  roboplot(Alue,
           plot_type = c("Venäjä" = "scatter", .other = "bar"),
           legend = set_legend(reverse = TRUE))


# Legend title is distinct from axis-specific legend titles which are controlled
# by `set_axes()` parameters `ylegend` and `y2legend`, when `y2` is used to move
# items from `color` to a secondary y-axis.

d |>
  roboplot(
    color = Suunta,
    plot_axes = set_axes(
      y2 = "Tuonti",
      ylegend = "Left yaxis",
      y2legend = "Right yaxis"
    ),
    legend = set_legend(title = "Example")
  )


# Use `tidy` to force legend items to have equal horizontal space across columns
# for slightly neater looking plots. Avoid if space is at premium.

energiantuonti |>
  dplyr::filter(Suunta == "Tuonti") |>
  roboplot(
    Alue,
    legend = set_legend(tidy = TRUE)
  )


# `set_legend()` works with `robomap()` too, but with a bit different parameters.
if (requireNamespace("sf", quietly = TRUE)) {

d <- vaesto_postinumeroittain |>
  dplyr::filter(stringr::str_detect(Postinumero, "^00(8|9)"))

# Control number of legend items with `breaks`. `robomap()` attempts to use that
# many items, but might settle for a near value.

d |> robomap(Postinumero, "Väkiluku", legend = set_legend(breaks = 5))

# If your legend won't be gradient, you can set specific breakpoints
d |>
  robomap(Postinumero,
          "V\u00e4kiluku",
          legend = set_legend(breaks = c(9000, 12000, 18000), gradient = FALSE))

# Adjust position and opacity.
d |>
  robomap(Postinumero,
          "V\u00e4kiluku",
          legend = set_legend(position = "bottomright", opacity = 0.3))

# Use factor column as value to have labeled legend.
d |>
  dplyr::mutate(
    value = dplyr::case_when(
      value >= stats::quantile(d$value)["75%"] ~ "Suuri",
      value <= stats::quantile(d$value)["25%"] ~ "Pieni",
      TRUE ~ "Normaali"
  ),
  value = forcats::fct_relevel(value, "Pieni","Normaali","Suuri")
  ) |>
  robomap(Postinumero, "V\u00e4kiluku")

}
#> Warning: Some values were outside the color scale and will be treated as NA