Create a hexbin plot. — hexbin

A hexbin plot is a two-dimensional histogram: the x/y plane is tiled with a grid of regular hexagons, every observation is assigned to the hexagon it falls into, and each hexagon is colored by the number of observations it contains. It is a readable alternative to a scatter plot when there are too many points to see individually (overplotting), because dense regions remain distinguishable instead of turning into a solid blob.

The look is inspired by the hexbin transform of the Observable Plot library: light gridlines, a sequential color scale with a continuous legend, and an optional mode where the hexagon size (area) also encodes the count. Binning is done in pixel space, so the hexagons are always regular regardless of the units of x and y.

The plot is interactive: hovering a hexagon outlines it, marks its count on the color legend and (when tooltip = TRUE) shows a tooltip with the bin count, its share of all observations, and the x/y range covered by the hexagon.

Usage

hexbin_plot(
  data,
  x,
  y,
  binWidth = 12,
  sizeByCount = FALSE,
  colorPalette = "YlGnBu",
  reverseColors = FALSE,
  colorScale = c("linear", "sqrt", "log"),
  legend = TRUE,
  legendTitle = "Count",
  tooltip = TRUE,
  hover = TRUE,
  animate = TRUE,
  opacity = 1,
  stroke = "white",
  strokeWidth = 0.5,
  grid = TRUE,
  gridCol = "#e5e5e5",
  xtitle = NULL,
  ytitle = NULL,
  xtitleFontSize = 13,
  ytitleFontSize = 13,
  title = NULL,
  titleFontSize = 16,
  xFontSize = 11,
  yFontSize = 11,
  font = "Verdana, Geneva, Tahoma, sans-serif",
  bgcol = "white",
  axisCol = "black",
  width = NULL,
  height = NULL
)

Arguments

data: The data frame containing the variables to consider.
x: The name of the numeric column mapped to the horizontal axis.
y: The name of the numeric column mapped to the vertical axis.
binWidth: The radius of each hexagon in pixels (distance from its center to a corner). Larger values give fewer, coarser bins. Defaults to 12.
sizeByCount: Logical. When TRUE, the area of each hexagon is also proportional to its count (the largest bin fills its cell), in addition to the fill color. Defaults to FALSE.
colorPalette: The name of a D3 sequential color interpolator, without the "interpolate" prefix (e.g. "Viridis", "Blues", "YlGnBu", "Magma", "Turbo"). Defaults to "YlGnBu".
reverseColors: Logical. Whether to reverse the direction of the color palette. Defaults to FALSE.
colorScale: How counts are mapped to colors: "linear" (default), "sqrt" or "log". Use "sqrt" or "log" when a few very dense bins wash out the rest.
legend: Logical. Whether to draw the continuous color legend. Defaults to TRUE.
legendTitle: Title of the color legend. Defaults to "Count".
tooltip: Logical. Whether to show a tooltip when a hexagon is hovered. Defaults to TRUE.
hover: Logical. When TRUE (default), hovering a hexagon outlines it and marks its count on the legend.
animate: Logical. When TRUE (default), hexagons grow into place with a short staggered entry animation on first render.
opacity: Fill opacity of the hexagons (0 to 1). Defaults to 1.
stroke: Stroke color of the hexagons. Defaults to "white".
strokeWidth: Stroke width of the hexagons in pixels. Defaults to 0.5.
grid: Logical. Whether to draw light gridlines behind the hexagons. Defaults to TRUE.
gridCol: Color of the gridlines. Defaults to "#e5e5e5".
xtitle: Optional. Title of the x-axis. Defaults to the value of x.
ytitle: Optional. Title of the y-axis. Defaults to the value of y.
xtitleFontSize: Font size of the x-axis title. Defaults to 13.
ytitleFontSize: Font size of the y-axis title. Defaults to 13.
title: Optional. Title of the chart.
titleFontSize: Font size of the chart title. Defaults to 16.
xFontSize: Font size of the x-axis tick labels. Defaults to 11.
yFontSize: Font size of the y-axis tick labels. Defaults to 11.
font: The font family used for all text. Defaults to "Verdana, Geneva, Tahoma, sans-serif".
bgcol: Background color of the SVG. Defaults to "white".
axisCol: Color of axis lines, ticks, labels and titles. Defaults to "black".
width: Optional. The width of the SVG output.
height: Optional. The height of the SVG output.

Value

An SVG hexbin plot.

Examples

# Old Faithful geyser: eruption duration vs waiting time
hexbin_plot(
  data     = faithful,
  x        = "waiting",
  y        = "eruptions",
  binWidth = 14,
  xtitle   = "Waiting time to next eruption (min)",
  ytitle   = "Eruption duration (min)",
  title    = "Old Faithful eruptions"
)


# 10,000 diamonds: carat vs price, with a log color scale
library(ggplot2) # for the diamonds dataset
set.seed(1)
dsample <- diamonds[sample(nrow(diamonds), 10000), ]

hexbin_plot(
  data         = dsample,
  x            = "carat",
  y            = "price",
  binWidth     = 8,
  colorPalette = "Viridis",
  colorScale   = "log",
  xtitle       = "Carat",
  ytitle       = "Price (USD)",
  title        = "Diamond price by carat"
)


# Hexagon size encodes the count as well as the color
set.seed(42)
pts <- data.frame(
  a = c(rnorm(1500, 0, 1), rnorm(800, 3, 0.6)),
  b = c(rnorm(1500, 0, 1), rnorm(800, 2, 0.6))
)

hexbin_plot(
  data         = pts,
  x            = "a",
  y            = "b",
  binWidth     = 13,
  sizeByCount  = TRUE,
  colorPalette = "Magma",
  reverseColors = TRUE,
  title        = "Two bivariate normal clusters"
)