geom_flow
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 reconfigures these into
alluvial segments connecting pairs of corresponding lodes in adjacent strata
and plots filled xsplines between each such pair, using a provided knot
position parameter knot.pos
, and filled rectangles at either end, using a
provided width
.
geom_flow( mapping = NULL, data = NULL, stat = "flow", position = "identity", width = 1/3, knot.pos = 1/4, knot.prop = TRUE, curve_type = NULL, curve_range = NULL, segments = NULL, aes.flow = "forward", na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ... ) positions_to_flow( x0, x1, ymin0, ymax0, ymin1, ymax1, kp0, kp1, knot.prop, curve_type, curve_range, segments )
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. 
aes.flow  Character; how interlode flows assume aesthetics from lodes. Options are "forward" and "backward". 
na.rm  Logical:
if 
show.legend  logical. Should this layer be included in the legends?

inherit.aes  If 
...  Additional arguments passed to 
x0, x1, ymin0, ymax0, ymin1, ymax1, kp0, kp1  Numeric corner and knot position data for the ribbon of a single flow. 
The helper function positions_toflow()
takes the corner and knot positions
and curve parameters for a single flow as input and returns a data frame of
x
, y
, and shape
used by grid::xsplineGrob()
to render the flow.
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_alluvium()
,
geom_lode()
,
geom_stratum()
# use of strata and labels ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age)) + geom_flow() + scale_x_discrete(limits = c("Class", "Sex", "Age")) + geom_stratum() + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + ggtitle("Alluvial plot of Titanic passenger demographic data") # use of facets, with sigmoid flows ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex)) + geom_flow(aes(fill = Age), width = .4, curve_type = "quintic") + geom_stratum(width = .4) + geom_text(stat = "stratum", aes(label = after_stat(stratum)), size = 3) + scale_x_discrete(limits = c("Class", "Sex")) + facet_wrap(~ Survived, scales = "fixed") # time series alluvia of WorldPhones data wph < as.data.frame(as.table(WorldPhones)) names(wph) < c("Year", "Region", "Telephones") ggplot(wph, aes(x = Year, alluvium = Region, y = Telephones)) + geom_flow(aes(fill = Region, colour = Region), width = 0) # treat 'Year' as a number rather than as a factor wph$Year < as.integer(as.character(wph$Year)) ggplot(wph, aes(x = Year, alluvium = Region, y = Telephones)) + geom_flow(aes(fill = Region, colour = Region), width = 0) # hold the knot positions fixed ggplot(wph, aes(x = Year, alluvium = Region, y = Telephones)) + geom_flow(aes(fill = Region, colour = Region), width = 0, knot.prop = FALSE) # rightward flow aesthetics for vaccine survey data, with cubic flows data(vaccinations) vaccinations$response < factor(vaccinations$response, rev(levels(vaccinations$response))) # annotate with proportional counts ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_lode() + geom_flow(curve_type = "cubic") + geom_stratum(alpha = 0) + geom_text(stat = "stratum", aes(label = round(after_stat(prop), 3))) # annotate fixedwidth ribbons with counts ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, weight = freq, fill = response)) + geom_lode() + geom_flow(curve_type = "cubic") + geom_stratum(alpha = 0) + geom_text(stat = "flow", aes(label = after_stat(n), hjust = (after_stat(flow) == "to")))