knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.path = "man/figures/README-" )
This is a {ggplot2} extension for alluvial plots.
The alluvial plots implemented here can be used to visualize frequency distributions over time or frequency tables involving several categorical variables. The design is inspired by the {alluvial} package, but the {ggplot2} framework induced several conspicuous differences:
Additionally, {ggalluvial} arranges these layers vertically without gaps, so that the secondary plotting axis indicates the cumulative values of the strata at each dimension.
The latest stable release can be installed from CRAN:
install.packages("ggalluvial")
The cran
branch will contain the version most recently submitted to CRAN. It is duplicated in the master
branch, from which source the website is built.
The development version can be installed from the (default) main
branch on GitHub:
remotes::install_github("corybrunson/ggalluvial@main", build_vignettes = TRUE)
Note that, in order to build the vignettes, the imported packages {alluvial}, {ggfittext}, and {ggrepel} must be installed. To skip this step, leave build_vignettes
unspecified or set it to FALSE
.
The
optimization
branch contains a development version with experimental functions to reduce the number or area of alluvial overlaps (see issue #6). Install it as follows:
remotes::install_github("corybrunson/ggalluvial", ref = "optimization")
Note, however, that this branch has not kept pace with the main
branch or with recent upgrades on CRAN.
devtools::load_all()
Here is how to generate an alluvial plot representation of the multi-dimensional categorical dataset of passengers on the Titanic:
titanic_wide <- data.frame(Titanic) head(titanic_wide) ggplot(data = titanic_wide, aes(axis1 = Class, axis2 = Sex, axis3 = Age, y = Freq)) + scale_x_discrete(limits = c("Class", "Sex", "Age"), expand = c(.2, .05)) + xlab("Demographic") + geom_alluvium(aes(fill = Survived)) + geom_stratum() + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + theme_minimal() + ggtitle("passengers on the maiden voyage of the Titanic", "stratified by demographics and survival")
The data is in "wide" format, but {ggalluvial} also recognizes data in "long" format and can convert between the two:
titanic_long <- to_lodes_form(data.frame(Titanic), key = "Demographic", axes = 1:3) head(titanic_long) ggplot(data = titanic_long, aes(x = Demographic, stratum = stratum, alluvium = alluvium, y = Freq, label = stratum)) + geom_alluvium(aes(fill = Survived)) + geom_stratum() + geom_text(stat = "stratum") + theme_minimal() + ggtitle("passengers on the maiden voyage of the Titanic", "stratified by demographics and survival")
For detailed discussion of the data formats recognized by {ggalluvial} and several examples that illustrate its flexibility and limitations, read the technical vignette:
vignette(topic = "ggalluvial", package = "ggalluvial")
Several additional vignettes offer detailed solutions to specific needs:
"labels"
) for how to elegantly label strata of a wide range of heights in an alluvial plot;"order-rectangles"
) for how to control the positioning of strata and lodes in an alluvial plot; and"shiny"
) for how to incorporate alluvial plots into interactive apps.The object documentation includes several more examples. Use help()
to call forth more detail on
stat_*
or geom_*
),to_*_form
), andvaccinations
and majors
).For some more digestible guidance on using {ggalluvial}, check out three cheat sheets and demos by students in Joyce Robbins's Exploratory Data Analysis and Visualization Community Contribution Project:
Development of this package benefitted from the use of equipment and the support of colleagues at UConn Health and at UF Health.
Contributions in any form are more than welcome! Pretty much every fix and feature of this package derives from a problem or question posed by someone with datasets or design goals i hadn't anticipated. See the CONTRIBUTING file for guidance, and please respect the Code of Conduct.
If you use {ggalluvial}-generated figures in publication, i'd be grateful to hear about it! You can also cite the package according to citation("ggalluvial")
.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.