geom_alluvium
receives a dataset of the horizontal (x
) and vertical (y
,
ymin
, ymax
) positions of the lodes of an alluvial plot, the
intersections of the alluvia with the strata. It plots both the lodes
themselves, using geom_lode()
, and the flows between them, using
geom_flow()
.
geom_alluvium( mapping = NULL, data = NULL, stat = "alluvium", position = "identity", width = 1/3, knot.pos = 1/4, knot.prop = TRUE, curve_type = NULL, curve_range = NULL, segments = NULL, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ... ) data_to_alluvium( data, knot.prop = TRUE, curve_type = "spline", curve_range = NULL, segments = NULL )
mapping  Set of aesthetic mappings created by 

data  The data to be displayed in this layer. There are three options: If A A 
stat  The statistical transformation to use on the data; override the default. 
position  Position adjustment, either as a string, or the result of a call to a position adjustment function. 
width  Numeric; the width of each stratum, as a proportion of the distance between axes. Defaults to 1/3. 
knot.pos  The horizontal distance of xspline knots from each stratum
( 
knot.prop  Logical; whether to interpret 
curve_type  Character; the type of curve used to produce flows.
Defaults to 
curve_range  For alternative 
segments  The number of segments to be used in drawing each alternative curve (each curved boundary of each flow). If less than 3, will be silently changed to 3. 
na.rm  Logical:
if 
show.legend  logical. Should this layer be included in the legends?

inherit.aes  If 
...  Additional arguments passed to 
The helper function data_to_alluvium()
takes internal ggplot2 data
(mapped aesthetics) and curve parameters for a single alluvium as input and
returns a data frame of x
, y
, and shape
used by grid::xsplineGrob()
to render the alluvium.
geom_alluvium
, geom_flow
, geom_lode
, and geom_stratum
understand the
following aesthetics (required aesthetics are in bold):
x
y
ymin
ymax
alpha
colour
fill
linetype
size
group
group
is used internally; arguments are ignored.
By default, geom_alluvium()
and geom_flow()
render flows between lodes as
filled regions between parallel xsplines. These graphical elements,
generated using grid::xsplineGrob()
, are
parameterized by the relative location of the knot (knot.pos
). They are
quick to render and clear to read, but users may prefer plots that use
differentlyshaped ribbons.
A variety of such options are documented at, e.g., this easing functions cheat sheet and this blog post by Jeffrey Shaffer. Easing functions are
not (yet) used in ggalluvial, but several alternative curves are available.
Each is encoded as a continuous, increasing, bijective function from the unit
interval \([0,1]\) to itself, and each is rescaled so that its endpoints
meet the corresponding lodes. They are rendered piecewiselinearly, by
default using segments = 48
. Summon each curve type by passing one of the
following strings to curve_type
:
"linear"
: \(f(x)=x\), the unique degree1 polynomial that takes
0 to 0 and 1 to 1
"cubic"
: \(f(x)=3x^{2}2x^{3}\), the unique
degree3 polynomial that also is flat at both endpoints
"quintic"
: \(f(x)=10x^{3}15x^{4}+6x^{5}\),
the unique degree5 polynomial that also has zero curvature
at both endpoints
"sine"
: the unique sinusoidal function that is flat at both
endpoints
"arctangent"
: the inverse tangent function, scaled and recentered to the
unit interval from the interval centered at zero with
radius curve_range
"sigmoid"
: the sigmoid function, scaled and recentered to the unit
interval from the interval centered at zero with radius
curve_range
Only the (default) "xspline"
option uses the knot.*
parameters, while
only the alternative curves use the segments
parameter, and only
"arctangent"
and "sigmoid"
use the curve_range
parameter. (Both are
ignored if not needed.) Larger values of curve_range
result in greater
compression and steeper slopes. The NULL
default will be changed to
2+sqrt(3)
for "arctangent"
and to 6
for "sigmoid"
.
These packagespecific options set global values for curve_type
,
curve_range
, and segments
that will be defaulted to when not manually
set:
ggalluvial.curve_type
: defaults to "xspline"
.
ggalluvial.curve_range
: defaults to NA
, which triggers the
curvespecific default values.
ggalluvial.segments
: defaults to 48L
.
See base::options()
for how to use options.
The previously defunct parameters axis_width
and ribbon_bend
have been
discontinued. Use width
and knot.pos
instead.
ggplot2::layer()
for additional arguments and
stat_alluvium()
and
stat_flow()
for the corresponding stats.
Other alluvial geom layers:
geom_flow()
,
geom_lode()
,
geom_stratum()
# basic ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, fill = Survived)) + geom_alluvium() + scale_x_discrete(limits = c("Class", "Sex", "Age")) gg < ggplot(alluvial::Refugees, aes(y = refugees, x = year, alluvium = country)) # time series bump chart (quintic flows) gg + geom_alluvium(aes(fill = country, colour = country), width = 1/4, alpha = 2/3, decreasing = FALSE, curve_type = "sigmoid") # time series line plot of refugees data, sorted by country gg + geom_alluvium(aes(fill = country, colour = country), decreasing = NA, width = 0, knot.pos = 0) # irregular spacing between axes of a continuous variable refugees_sub < subset(alluvial::Refugees, year %in% c(2003, 2005, 2010, 2013)) gg < ggplot(data = refugees_sub, aes(x = year, y = refugees, alluvium = country)) + theme_bw() + scale_fill_brewer(type = "qual", palette = "Set3") # proportional knot positioning (default) gg + geom_alluvium(aes(fill = country), alpha = .75, decreasing = FALSE, width = 1/2) + geom_stratum(aes(stratum = country), decreasing = FALSE, width = 1/2) # constant knot positioning gg + geom_alluvium(aes(fill = country), alpha = .75, decreasing = FALSE, width = 1/2, knot.pos = 1, knot.prop = FALSE) + geom_stratum(aes(stratum = country), decreasing = FALSE, width = 1/2) # coarselysegmented curves gg + geom_alluvium(aes(fill = country), alpha = .75, decreasing = FALSE, width = 1/2, curve_type = "arctan", segments = 6) + geom_stratum(aes(stratum = country), decreasing = FALSE, width = 1/2) # customranged curves gg + geom_alluvium(aes(fill = country), alpha = .75, decreasing = FALSE, width = 1/2, curve_type = "arctan", curve_range = 1) + geom_stratum(aes(stratum = country), decreasing = FALSE, width = 1/2)