ggalluvial 0.12.3

Shiny vignette

A new vignette by Quentin D. Read shows how to build interactive Shiny apps with tooltips sensitive to the locations of graphical elements. This is especially important for the spline boundaries of flows and alluvia.

Examples using vaccinations data

Corrections have been made to erroneous legacy code, found in one example and two vignettes, to reorder the factor levels of the "response" field in the data set vaccinations. The documentation is updated accordingly.

Also, an explanation of the (misleading) column names of this data set has been added to the main vignette.

ggalluvial 0.12.2

This patch addresses a bug introduced in v0.12.0 that had is_lodes_form() return an error when a data frame contains duplicate id-axis pairings, which may be appropriate for producing faceted plots. The new site parameter can be passed one or more grouping variables for this purpose, and internally it is passed "PANEL" to prevent this error from being thrown.

ggalluvial 0.12.1

This patch corrects a bug introduced in v0.12.0 that dropped missing values used internally by StatFlow$compute_panel() to keep track of flowless lodes. The problem was illustrated in issue #64.

ggalluvial 0.12.0

Data sets

Both installed data sets, vaccinations and majors, are better documented.

The a field of vaccinations (the within-survey fraction of respondents, which can be computed from the other fields) has been removed, and the start_date and end_date fields (Dates, obtained from the ALP website) have been added.

Warning and error messages

The following changes broke no examples or tests but could change behavior in rare cases:

Ordering of lodes/alluvia

Behavior of lode.ordering

For consistency with the behavior of aes.bind, stat_alluvium() now invokes lode.ordering together with lode.guidance: If the vectors of lode.ordering include duplicates, i.e. they do not completely determine an order, then the remaining deposits are used to refine the order. Previously, lode.ordering was assumed to consist of permutation vectors, so the two parameters were mutually exclusive.

Additionally, for consistency with other influences on the lode order, the vectors of lode.ordering are reversed if reverse = TRUE (the default). This will change some plots but will not produce new errors.

Controlling lode order before guidance and aesthetics

The lode.ordering parameter of stat_alluvium() has been deprecated. Instead, the new order aesthetic gives priority to its argument over the differentiation aesthetics in arranging the lodes within each stratum, without producing graphical artifacts. This aesthetic can also be used in stat_flow().

Order of alluvia in negative strata

Alluvia within “deposits” are now consistently ordered in positive and negative strata, rather than according to absolute. This avoids the “twisting” of flows between strata of different signs. Whereas the orderings of the deposits matter to the stacked-histogram reading of the plot, the orderings of the alluvia should simply maximize its elegance and readability. This will change some plots but will not produce new errors.

Computed variables

The alluvial stats now compute four variables for use with after_stat(): numeric variables n, count, and prop; and character variables lode (when the alluvium aesthetic is specified) and flow (when using the flow stat). The numerical variables can be weighted using the weight aesthetic, which is dropped during computation (so that it does not confuse the geoms), while lode is distilled according to a new distill parameter. This use of weight may cause confusion with its use by the is_*_form() functions until they are upgraded in the next version.

These new variables complement the already-computed but heretofore undocumented variables stratum and deposit. stratum obviates the need for the infer.label parameter, which is deprecated. Its alias, label.strata, is now defunct. (The variable alluvium is often computed, but it is manipulated to be used by the geom layers and should not be passed to an aesthetic.) deposit takes contiguous integer values forward along the axes and upward along the (signed) strata at each axis.

Flow upgrades and extensions

The knot.pos parameter of geom_alluvium() and geom_flow() is now interpreted as a proportion of the total length of each flow, i.e. of the gap between adjacent strata (not axes). This means that values will vary with axis positions and stratum widths. Setting the new knot.prop parameter to FALSE prevents this by interpreting knot.pos as a constant value in the x direction.

These flows are rendered using grid::xsplineGrob() with four control points each: the endpoints and the two knots. To complement them, several other curves are now available: linear (equivalent to knot.pos = 0), cubic, quintic, sinusoidal, arctangent, and sigmoid, summoned by the new curve_type parameter (which defaults to the x-spline). (The asymptotic functions, arctangent and sigmoid, are compressed according to the new curve_range parameter.) The new curves are rendered piecewise linearly, with resolution controlled by the new segments parameter (similar to ggplot2::stat_ellipse()).


The stratum and lode ordering parameters now default to NULL, in which case they are reassigned to global options internally. This simplifies their documentation. The new curve parameters curve_type, curve_range, and segments can also be set as options and are documented in the same way.

ggalluvial 0.11.3


In response to ggplot2 v3.2.0, which removes the plyr dependency, the dependency has been removed from ggalluvial as well.

ggalluvial 0.11.2

The function self_adjoin() is debugged for use with a continuous-valued x variable. An example, taking x to be the date of each vaccination survey in vaccinations, is documented with stat_stratum().

ggalluvial 0.11.1

This patch fixes a bug with including negative observations in alluvia-form data due to outdated code that prohibited negative y values. This was discovered while drafting two examples of this usage, which are included in the documentation.

ggalluvial 0.11.0

Parameter renamings, deprecations, and additions

Negative observations

Negative values can now be meaningfully passed to y, producing behavior that mimics that of geom_bar(). The new logical parameter absolute controls whether negative strata, and lodes within them, are ordered vertically in the same way as positive strata and lodes (FALSE) or in the opposite way (TRUE). Additionally, the negate.strata parameter can be used to negate the observations associated with specific strata, in order to situate them below rather than above the x axis.

New lode guidance function

The new lode guidance function lode_zagzig() mimics the behavior of lode_zigzag() except in initially “zagging” toward the farther end rather than “zigging” toward the closer end.

Stat layer consistency

stat_*() internals have been simplified and standardized, in particular the manner in which lodes are ordered within strata.

Layer tests

Tests have been added for the statistical transformations. Visual regression tests using vdiffr have been added for the geoms.

ggalluvial 0.10.0

Lode guidance and ordering

The lode guidance functions have been renamed as follows and their original names retained as aliases:

original renamed
rightward forward
leftward backward
rightleft frontback
leftright backfront

Additionally, lode.ordering now accepts a single integer vector of length the number of cases (alluvia), and will use the vector to sort the lodes within strata at each axis.

Finally, a new vignette showcases this and related functionality using a small example.

Defunct parameters

The following parameters, deprecated in previous versions, are now defunct (with informative messages):

Default geom layer parameters

The width and knot.pos parameters sometimes required by Geom*$setup_data() are now set to the same defaults as in the geom_*()s when called from a stat. Previously-implemented warnings have been removed.

Custom lode guidance functions

The lode.guidance argument of stat_alluvial() now accepts functions as input, making the use of custom functions easier as demonstrated in an example.

ggalluvial 0.9.2

Height limits on strata

Parameters min.height and max.height are introduced to stat_stratum() to allow users to omit strata outside a given height range. This is probably most relevant for stratum labeling, as illustrated in the updated vignette.

ggalluvial 0.9.1

Suggest sessioninfo for session_info()

Because the only functional (e.g. out occurrence of devtools is to call session_info() at the ends of the vignettes, this suggestion and usage are switched to sessioninfo.

markdown formatting

Documentation is slightly reformatted due to switching roxygen syntax to markdown.

z-ordering patch

The internal z-ordering function z_order_aes failed to recognize contiguous segments of alluvia, thereby assigning later segments missing values of 'group' and preventing them from being rendered. This has been corrected.

ggalluvial 0.9.0

geom_alluvium() patch

An occurrence of weight in geom_alluvium() was not updated for v0.8.0 and caused geom_alluvium() to throw an error in some cases. This has been corrected.

geom_flow() patch

An earlier solution to the z-ordering problem sufficed for matched layers (*_alluvium() and *_flow()) but failed for the combination of stat_alluvium() with geom_flow(). This is been corrected in the code for GeomFlow$draw_panel(), though a more elegant and general solution is preferred.

Deprecated parameters removed

The deprecated parameters axis_width (all geom layers) and ribbon_bend (geom_alluvium() and geom_flow()) are removed and an explanatory note added to the layers’ documentation.

Vignette on labeling small strata

A vignette illustrating two methods for labeling small strata, using other ggplot2 extensions, is included.

self_adjoin() export

The internal function self_adjoin(), invoked by geom_flow(), is revised, exported, documented, and exemplified.

ggalluvial 0.8.0

Stat layer functionality

Alluvial data functionality

ggalluvial 0.7.0

Alluvial data functionality

These changes make the functions that test for and convert between alluvial formats behave more like popular functions in the tidyverse. Some of the changes introduce backward incompatibilities, but most result in deprecation warnings.

ggalluvial 0.6.0

CRAN checks for v0.5.0

Alluvial data functionality

Layer internals

ggalluvial 0.5.0

Backward incompatibilities

The ggalluvial() shortcut function, which included a formula interface, deprecated in version 0.4.0, is removed.

earlier versions

I only started maintaining with version 0.5.0.