R: Legend guide.

guide_legend {ggplot2}

R Documentation

Legend guide.

Description

Legend type guide shows key (i.e., geoms) mapped onto values. Legend guides for various scales are integrated if possible.

Usage

guide_legend(title = waiver(), title.position = NULL, title.theme = NULL,
  title.hjust = NULL, title.vjust = NULL, label = TRUE,
  label.position = NULL, label.theme = NULL, label.hjust = NULL,
  label.vjust = NULL, keywidth = NULL, keyheight = NULL,
  direction = NULL, default.unit = "line", override.aes = list(),
  nrow = NULL, ncol = NULL, byrow = FALSE, reverse = FALSE, 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 tha name specified in `labs` is used for the title.
`title.position`	A character string indicating the position of a title. One of "top" (default for a vertical guide), "bottom", "left" (default for a horizontal guide), or "right."
`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.
`label`	logical. If `TRUE` then the labels are drawn. If `FALSE` then the labels are invisible.
`label.position`	A character string indicating the position of a label. One of "top", "bottom" (default for horizontal guide), "left", or "right" (default for vertical gudie).
`label.theme`	A theme object for rendering the label text. Usually the object of `element_text` is expected. By default, the theme is specified by `legend.text` in `theme` or theme.
`label.hjust`	A numeric specifying horizontal justification of the label text.
`label.vjust`	A numeric specifying vertical justification of the label text.
`keywidth`	A numeric or a unit object specifying the width of the legend key. Default value is `legend.key.width` or `legend.key.size` in `theme` or theme.
`keyheight`	A numeric or a unit object specifying the height of the legend key. Default value is `legend.key.height` or `legend.key.size` in `theme` or theme.
`direction`	A character string indicating the direction of the guide. One of "horizontal" or "vertical."
`default.unit`	A character string indicating unit for `keywidth` and `keyheight`.
`override.aes`	A list specifying aesthetic parameters of legend key. See details and examples.
`nrow`	The desired number of rows of legends.
`ncol`	The desired number of column of legends.
`byrow`	logical. If `FALSE` (the default) the legend-matrix is filled by columns, otherwise the legend-matrix is filled by rows.
`reverse`	logical. If `TRUE` the order of legends is reversed.
`order`	positive integer less that 99 that specify the order of this guide in the multiple guides. If 0 (default), the order is determined by a secret algorithm.
`...`	ignored.

Details

Guides can be specified in each scale or in guides. guide="legend" in scale is syntactic sugar for guide=guide_legend(). As for how to specify the guide for each scales in more detail, see guides.

Value

A guide object

Examples


library(reshape2) # for melt
df <- melt(outer(1:4, 1:4), varnames = c("X1", "X2"))

p1 <- ggplot(df, aes(X1, X2)) + geom_tile(aes(fill = value))
p2 <- p1 + geom_point(aes(size = value))

# Basic form
p1 + scale_fill_continuous(guide = "legend")
p1 + scale_fill_continuous(guide = guide_legend())

# Guide title

p1 + scale_fill_continuous(guide = guide_legend(title = "V")) # title text
p1 + scale_fill_continuous(name = "V") # same
p1 + scale_fill_continuous(guide = guide_legend(title = NULL)) # no title

# Control styles

# key size
p1 + guides(fill = guide_legend(keywidth = 3, keyheight = 1))

# title position
p1 + guides(fill = guide_legend(title = "LEFT", title.position = "left"))

# title text styles via element_text
p1 + guides(fill = guide_legend(
  title.theme = element_text(size=15, face="italic", colour = "red", angle = 45)))

# label position
p1 + guides(fill = guide_legend(label.position = "bottom"))

# label styles
p1 + scale_fill_continuous(breaks = c(5, 10, 15),
  labels = paste("long", c(5, 10, 15)),
  guide = guide_legend(direction = "horizontal", title.position = "top",
    label.position="bottom", label.hjust = 0.5, label.vjust = 0.5,
    label.theme = element_text(angle = 90)))

# Set aesthetic of legend key

# very low alpha value make it difficult to see legend key
p3 <- qplot(carat, price, data = diamonds, colour = color,
  alpha = I(1/100))
p3

# override.aes overwrites the alpha
p3 + guides(colour = guide_legend(override.aes = list(alpha = 1)))

# multiple row/col legends
p <- qplot(1:20, 1:20, colour = letters[1:20])
p + guides(col = guide_legend(nrow = 8))
p + guides(col = guide_legend(ncol = 8))
p + guides(col = guide_legend(nrow = 8, byrow = TRUE))
p + guides(col = guide_legend(ncol = 8, byrow = TRUE))

# reversed order legend
p + guides(col = guide_legend(reverse = TRUE))

[Package ggplot2 version 1.0.1 Index]