gizmo_histogram: Guide gizmo: histogram
In legendry: Extended Legends and Axes for 'ggplot2'

gizmo_histogram

R Documentation

Guide gizmo: histogram

Description

This guide displays a histogram of the aesthetic. If the aesthetic is colour or fill, the shape will reflect this.

Usage

gizmo_histogram(
  key = waiver(),
  hist = NULL,
  hist.args = list(),
  hist.fun = graphics::hist,
  just = 1,
  oob = oob_keep,
  metric = "counts",
  alpha = NA,
  theme = NULL,
  position = waiver(),
  direction = NULL
)

Arguments

`key`	A sequence key or binned key specification. Internally defaults to a sequence key when the scale is continuous and a binned key when the scale is binned.
`hist`	One of the following: `NULL` for computing histograms on the data values (default). an atomic `⁠<vector>⁠` to feed to the `hist.fun` function. A named `⁠<list>⁠` with `breaks` and `counts` numeric items, where the `breaks` item is exactly one element longer than the `counts` item. A typical way to construct such list is using the `hist()` function. Please note that `⁠<list>⁠` input is expected in scale-transformed space, not original data space.
`hist.args`	A `⁠<list>⁠` with additional arguments to the `hist.fun` argument. Only applies when `hist` is not provided as a `⁠<list>⁠` already. Please note that these arguments are only used for binning and counting: graphical arguments are ignored.
`hist.fun`	A `⁠<function>⁠` to use for computing histograms when the `hist` argument is not provided as a list already.
`just`	A `⁠<numeric[1]>⁠` between 0 and 1. Use 0 for bottom- or left-aligned histograms, use 1 for top- or right-aligned histograms and 0.5 for centred histograms.
`oob`	An out-of-bounds handling function that affects the cap colour. Can be one of the following: A `⁠<function>⁠` like `oob_squish`. A `⁠<character[1]>⁠` naming such a function without the '`oob`'-prefix, such as `"keep"`.
`metric`	A `⁠<character[1]>⁠` either `"counts"` or `"density"` stating which field of the `⁠<histogram>⁠` class to display. The `"density"` metric might be more appropriate to display when the histogram breaks have non-constant intervals.
`alpha`	A `⁠<numeric[1]>⁠` between 0 and 1 setting the colour transparency of the bar. Use `NA` to preserve the alpha encoded in the colour itself.
`theme`	A `<theme>` object to style the guide individually or differently from the plot's theme settings. The `theme` argument in the guide overrides and is combined with the plot's theme.
`position`	A `⁠<character[1]>⁠` giving the location of the guide. Can be one of `"top"`, `"bottom"`, `"left"` or `"right"`.
`direction`	A `⁠<character[1]>⁠` indicating the direction of the guide. Can be on of `"horizontal"` or `"vertical"`.

Details

Non-finite values such as NA and NaN are ignored while infinite values such as -Inf and Inf are squished to the limits.

Value

A ⁠<GizmoHistogram>⁠ object.

Examples

# A standard plot
p <- ggplot(mpg, aes(displ, hwy, colour = cty)) +
  geom_point() +
  scale_colour_viridis_c()

# Histogram from plot data
p + guides(colour = gizmo_histogram())

# Using bins instead of gradient
p + guides(colour = gizmo_histogram("bins"))

# Providing custom values to compute histogram
p + guides(colour = gizmo_histogram(hist = runif(1000, min = 5, max = 35)))

# Providing precomputed histogram
p + guides(colour = gizmo_histogram(hist = hist(mpg$cty, breaks = 10)))

# Alternatively, parameters may be passed through hist.args
p + guides(colour = gizmo_histogram(hist.arg = list(breaks = 10)))

legendry documentation built on April 4, 2025, 2:12 a.m.