geom_dice: A ggplot2 layer for creating dice representations

In ggdiceplot: DicePlot Visualization for 'ggplot2'

A ggplot2 layer for creating dice representations

Description

geom_dice() creates a layer that displays dice-like symbols where each dot represents a specific category. Dots are only shown when that categorical variable is present in the data, allowing compact visual encoding.

Usage

geom_dice(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ndots = NULL,
  x_length = NULL,
  y_length = NULL,
  pip_scale = 0.75,
  na.rm = FALSE,
  show.legend = TRUE,
  inherit.aes = TRUE,
  ...
)

Arguments

mapping	Set of aesthetic mappings created by aes(). Must include: x, y: Position of the dice. dots: The categories present (usually as a string or factor).
data	A data frame. If NULL, inherits from the plot.
stat	The statistical transformation to use.
position	Position adjustment.
ndots	Integer (1–6): number of positions shown per dice.
x_length	Numeric: number of x categories (used for aspect ratio).
y_length	Numeric: number of y categories (used for aspect ratio).
pip_scale	Numeric (0–1): controls pip diameter relative to the maximum available space. When size is constant (not mapped), all pips are drawn at pip_scale fraction of the die face. When size is mapped to a variable, pips scale between 0.25 (smallest value) and pip_scale (largest value) of the maximum pip diameter. Default is 0.75. Set to NULL to disable auto-scaling and use the raw size aesthetic.
na.rm	Remove missing values if TRUE.
show.legend	Whether to include in legend.
inherit.aes	If FALSE, overrides the default aesthetics.
...	Additional arguments passed to layer().

Value

A ggplot2 layer that draws dice with categorical dot encodings.

Examples

library(ggplot2)

df <- data.frame(
  x = 1:3,
  y = 1,
  dots = c("A,B", "A,C,E", "F")
)

ggplot(df, aes(x, y, dots = dots)) +
  geom_dice(ndots = 6, x_length = 3, y_length = 1)

ggdiceplot documentation built on March 27, 2026, 5:07 p.m.