colorplaner (version 0.1.3)

guide_colorplane: Add Guide for Colorplane

Description

Generates a guide to explain the colors plotted via scale_color_colorplane and scale_fill_colorplane.

Usage

guide_colorplane(title = waiver(), title.position = c("top", "bottom"), title.theme = NULL, title.hjust = 0.5, title.vjust = NULL, axis.title = waiver(), axis.title.position = c("bottom", "top"), axis.title.theme = NULL, axis.title.hjust = NULL, axis.title.vjust = NULL, axis.title.y = waiver(), axis.title.y.position = c("left", "right"), axis.title.y.theme = NULL, axis.title.y.hjust = NULL, axis.title.y.vjust = NULL, label = TRUE, label.position = c("bottom", "top"), label.theme = NULL, label.hjust = NULL, label.vjust = NULL, label.y.position = c("left", "right"), label.y.theme = NULL, label.y.hjust = NULL, label.y.vjust = NULL, planewidth = NULL, planeheight = NULL, nbin = 20, ticks = TRUE, default.unit = "line", order = 0, ...)

Arguments

title

A character string or expression indicating a title of guide. If NULL, the title is not shown. By default (waiver), the name of the scale object or the name specified in labs is used for the title.

title.position

Character string indicating position for the main title. One of "top" (default) or "bottom".

title.theme

A theme object for rendering the title text. Usually the object of element_text is expected. By default, the theme is specified by legend.title in theme or theme.

title.hjust

A number specifying horizontal justification of the title text.

title.vjust

A number specifying vertical justification of the title text.

axis.title, axis.title.y

Character strings or expressions indicating the horizontal and vertical axis titles in the guide, respectively. If NULL, the title is not shown. By default (waiver), the name of the scale or the name of the variable mapped to the aesthetic.

axis.title.position, axis.title.y.position

Character vectors indicating the position(s) of axis titles. axis.title.position: "top" and/or "bottom" (default). axis.title.y.position: "left" (default) and/or "right".

axis.title.theme, axis.title.y.theme

Theme objects for rendering the axis title text. Typically an element_text object. When NULL, defaults to settings for axis.title.x and axis.title.y in the plot theme.

axis.title.hjust, axis.title.vjust, axis.title.y.vjust, axis.title.y.hjust

Numerics specifying the horizontal (hjust) and vertical (vjust) justifications of the horizontal (axis.title) and vertical (axis.title.y) axis title text.

label

logical. If TRUE then the labels are drawn. If FALSE then the labels are invisible.

label.position, label.y.position

Character vectors indicating the position(s) of axis labels. For label.position, "top" and/or "bottom" (default). For label.y.position, "left" (default) and/or "right".

label.theme, label.y.theme

Theme objects for rendering axis label text. Usually the object of element_text is expected. By default, the theme is specified by axis.text.* in the plot theme.

label.hjust, label.vjust, label.y.hjust, label.y.vjust

Numerics specifying the horizontal (hjust) and vertical (vjust) justifications of the horizontal (label) and vertical (label.y) axis label text.

planewidth, planeheight

Numeric or unit objects specifying the width and height of the colorplane. Default values are 5 times the legend.key.width/height or legend.key.size in the plot theme.

nbin

Number specifying how many color pixels are generated for each dimension of the colorplane. Higher numbers increase guide color accuracy (especially for larger sized guides) at the expense of speed.

ticks

A logical specifying if tick marks on colorbar should be visible.

default.unit

A character string indicating unit for planewidth and planeheight.

order

positive integer less that 99 that specifies the order of this guide among multiple guides. This controls the order in which multiple guides are displayed, not the contents of the guide itself. If 0 (default), the order is determined by a secret algorithm.

...

ignored.

Details

The guide is based on guide_colorbar, but extended to be a plane of colors with ticks and labels for both variables in the scale. All *.theme arguments accept two types of arguments: a complete theme object (e.g. the object returned by theme_grey) or an element_text. If a theme is given, the related element will be extracted from the theme and used as-is. If an element is given, any missing parameters will be inherited from the plot's theme before use. If not specified, *.hjust and *.vjust parameters will draw from the corresponding *.theme argument, the plot's theme, or a default of 0.5 (centered). One exception is title.hjust which has been given a default value of 0.5 to override a undesirable default value in the default ggplot theme. Specify title.hjust = NULL to restore normal inheritance if needed.

References

Based on guide_colorbar, modified 2016.

Examples

if(requireNamespace("mapproj")) {
  library(ggplot2)
  crimes <- data.frame(state = tolower(rownames(USArrests)), USArrests)
  states_map <- map_data("state")
  ggplot(crimes,
         aes(map_id = state, fill = Murder, fill2 = UrbanPop)) +
    geom_map(map = states_map) +
    scale_fill_colorplane() +
    expand_limits(x = states_map$long, y = states_map$lat) +
    coord_map() +
    guides(fill = guide_colorplane("My Title", axis.title = "Murder Rate",
    axis.title.y = "Urban Population %", label.position = c("top", "bottom"),
    label.y.position = c("left", "right")))
 }