ggalluvial/0000755000176200001440000000000015146573312012410 5ustar liggesusersggalluvial/tests/0000755000176200001440000000000015146567322013556 5ustar liggesusersggalluvial/tests/testthat/0000755000176200001440000000000015146573312015412 5ustar liggesusersggalluvial/tests/testthat/test-stat-stratum.r0000644000176200001440000000436314452602415021224 0ustar liggesusers# weights are used but not returned test_that("`stat_stratum` weights computed variables but drops weight", { data <- data.frame(x = rep(1:2, c(2, 3)), stratum = LETTERS[c(1, 2, 1, 2, 2)]) data$y <- c(1, 1, 1, 1, 2) data$weight <- c(.5, 1, .5, 1, 1.5) comp <- StatStratum$compute_panel(data) comp <- comp[with(comp, order(x, stratum)), ] expect_equivalent(comp$n, c(0.5, 1, 0.5, 2.5)) expect_equivalent(comp$count, c(0.5, 1, 0.5, 4)) expect_equivalent(comp$prop, c(c(1, 2) / 3, c(1, 8) / 9)) expect_null(comp$lode) expect_null(comp$weight) }) # reverse and absolute parameters, negative values test_that("`stat_stratum` orders strata correctly with negative values", { data <- expand.grid(stratum = LETTERS[1:2], x = 1:2) data$y <- c(1, 1, -1, -1) # order by stratum, `reverse = TRUE` #ggplot(data, aes(x = x, stratum = stratum, y = y)) + # geom_stratum() + # geom_text(stat = "stratum", aes(label = stratum)) comp <- StatStratum$compute_panel(data) expect_identical(comp[with(comp, order(x, stratum)), ]$y, c(1.5, 0.5, -1.5, -0.5)) # order by stratum, `reverse = FALSE` #ggplot(data, aes(x = x, stratum = stratum, y = y)) + # geom_stratum(reverse = FALSE) + # geom_text(stat = "stratum", aes(label = stratum), reverse = FALSE) comp <- StatStratum$compute_panel(data, reverse = FALSE) expect_identical(comp[with(comp, order(x, stratum)), ]$y, c(0.5, 1.5, -0.5, -1.5)) # order by stratum, `absolute = FALSE` #ggplot(data, aes(x = x, stratum = stratum, y = y)) + # geom_stratum(absolute = FALSE) + # geom_text(stat = "stratum", aes(label = stratum), absolute = FALSE) comp <- StatStratum$compute_panel(data, absolute = FALSE) expect_identical(comp[with(comp, order(x, stratum)), ]$y, c(1.5, 0.5, -0.5, -1.5)) # order by stratum, `reverse = FALSE, absolute = FALSE` #ggplot(data, aes(x = x, stratum = stratum, y = y)) + # geom_stratum(reverse = FALSE, absolute = FALSE) + # geom_text(stat = "stratum", aes(label = stratum), # reverse = FALSE, absolute = FALSE) comp <- StatStratum$compute_panel(data, reverse = FALSE, absolute = FALSE) expect_identical(comp[with(comp, order(x, stratum)), ]$y, c(0.5, 1.5, -1.5, -0.5)) }) ggalluvial/tests/testthat/test-geom-stratum.r0000644000176200001440000000225514452602415021176 0ustar liggesusers# visual tests test_that("`geom_stratum` draws correctly", { d <- as.data.frame(Titanic) a1 <- aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, axis4 = Survived) a2 <- aes(y = Freq, axis1 = Class, axis2 = Sex) skip_on_cran() skip_if_not_installed("vdiffr") vdiffr::expect_doppelganger( "`geom_stratum`: basic", ggplot(d, a1) + geom_stratum() ) vdiffr::expect_doppelganger( "`geom_stratum`: extended width", ggplot(d, a1) + geom_stratum(width = 1) ) vdiffr::expect_doppelganger( "`geom_stratum`: inferred text labels", ggplot(d, a1) + geom_text(stat = "stratum", aes(label = after_stat(stratum))) ) vdiffr::expect_doppelganger( "`geom_stratum`: axis labels", ggplot(d, a1) + geom_stratum() + scale_x_discrete(limits = c("Class", "Sex", "Age", "Survived")) ) vdiffr::expect_doppelganger( "`geom_stratum`: facets", ggplot(d, a2) + geom_stratum() + facet_wrap(~ Age, scales = "free_y") ) vdiffr::expect_doppelganger( "`geom_stratum`: facets and axis labels", ggplot(d, a2) + geom_stratum() + scale_x_discrete(limits = c("Class", "Sex")) + facet_wrap(~ Age, scales = "free_y") ) }) ggalluvial/tests/testthat/test-geom-alluvium.r0000644000176200001440000000722014704334714021336 0ustar liggesusers# visual tests test_that("`geom_alluvium` draws correctly", { skip_on_cran() skip_if_not_installed("vdiffr") d1 <- as.data.frame(Titanic) a1 <- aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, fill = Survived) a2 <- aes(y = Freq, axis1 = Class, axis2 = Sex) vdiffr::expect_doppelganger( "`geom_alluvium`: basic", ggplot(d1, a1) + geom_alluvium() ) vdiffr::expect_doppelganger( "`geom_alluvium`: facets", ggplot(d1, a2) + geom_alluvium(aes(fill = Age), width = .4) + facet_wrap(~ Survived, scales = "fixed") ) skip_if_not_installed("alluvial") d2 <- alluvial::Refugees a3 <- aes(y = refugees, x = year, alluvium = country) vdiffr::expect_doppelganger( "`geom_alluvium`: bump plot", ggplot(d2, a3) + geom_alluvium(aes(fill = country), width = 1/4, decreasing = FALSE) ) vdiffr::expect_doppelganger( "`geom_alluvium`: line plot", ggplot(d2, a3) + geom_alluvium(aes(fill = country), width = 0, knot.pos = 0, outline.type = "upper") ) }) test_that("`geom_alluvium()` recognizes alternative curves", { data(vaccinations) skip_on_cran() skip_if_not_installed("vdiffr") suppressWarnings(vdiffr::expect_doppelganger( "`geom_alluvium`: unscaled knot positions", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_alluvium(knot.prop = FALSE) )) suppressWarnings(vdiffr::expect_doppelganger( "`geom_alluvium`: 'linear' curve", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_alluvium(curve_type = "linear") )) suppressWarnings(vdiffr::expect_doppelganger( "`geom_alluvium`: 'cubic' curve", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_alluvium(curve_type = "cubic") )) suppressWarnings(vdiffr::expect_doppelganger( "`geom_alluvium`: 'quintic' curve", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_alluvium(curve_type = "quintic") )) suppressWarnings(vdiffr::expect_doppelganger( "`geom_alluvium`: 'sine' curve", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_alluvium(curve_type = "sine") )) suppressWarnings(vdiffr::expect_doppelganger( "`geom_alluvium`: 'arctangent' curve", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_alluvium(curve_type = "arctan") )) suppressWarnings(vdiffr::expect_doppelganger( "`geom_alluvium`: 'arctangent' curve with custom range", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_alluvium(curve_type = "arctan", curve_range = 1) )) suppressWarnings(vdiffr::expect_doppelganger( "`geom_alluvium`: 'sigmoid' curve", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_alluvium(curve_type = "sigmoid") )) suppressWarnings(vdiffr::expect_doppelganger( "`geom_alluvium`: 'sigmoid' curve with custom range", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_alluvium(curve_type = "sigmoid", curve_range = 3) )) }) ggalluvial/tests/testthat/test-stat-flow.r0000644000176200001440000000750414452602415020474 0ustar liggesusers# weights are used but not returned test_that("`stat_flow` weights computed variables but drops weight", { data <- expand.grid(alluvium = letters[1:3], x = 1:2) data$stratum <- LETTERS[c(1, 1, 2, 1, 2, 2)] data$y <- c(1, 1, 1, 1, 1, 2) data$weight <- c(.5, 1, 1, .5, 1, 1) comp <- as.data.frame(StatFlow$compute_panel(data)) comp <- comp[with(comp, order(x, alluvium)), ] expect_equivalent(comp$n, c(1, 1, 0.5, 1, 1, 0.5)) expect_equivalent(comp$count, c(1, 1, 0.5, 2, 1, 0.5)) expect_equivalent(comp$prop, c(c(2, 2, 1) / 5, c(4, 2, 1) / 7)) expect_equal(comp$lode, rep(factor(letters[3:1]), times = 2)) expect_null(comp$weight) }) # reverse and absolute, negative values test_that("`stat_flow` orders flows correctly with negative values", { data <- expand.grid(alluvium = letters[1:3], x = 1:2) data$stratum <- LETTERS[c(1, 1, 2)] data$y <- c(1, 1, 1, -1, 1, -1) # order by stratum, `reverse = TRUE` #ggplot(data, aes(x = x, stratum = stratum, alluvium = alluvium, y = y)) + # geom_flow() comp <- StatFlow$compute_panel(data) expect_identical(comp[with(comp, order(x, alluvium)), ]$y, c(1.5, 0.5, 2.5, -1.5, -0.5, 0.5)) # order by stratum, `reverse = FALSE` #ggplot(data, aes(x = x, stratum = stratum, alluvium = alluvium, y = y)) + # geom_flow(reverse = FALSE) comp <- StatFlow$compute_panel(data, reverse = FALSE) expect_identical(comp[with(comp, order(x, alluvium)), ]$y, c(2.5, 0.5, 1.5, -1.5, -0.5, 0.5)) # order by stratum, `reverse = FALSE, absolute = FALSE` #ggplot(data, aes(x = x, stratum = stratum, alluvium = alluvium, y = y)) + # geom_flow(reverse = FALSE, absolute = FALSE) comp <- StatFlow$compute_panel(data, reverse = FALSE, absolute = FALSE) expect_identical(comp[with(comp, order(x, alluvium)), ]$y, c(0.5, 2.5, 1.5, -1.5, -0.5, 0.5)) }) # aesthetic binding test_that("`stat_flow` orders alluvia correctly according to `aes.bind`", { data <- expand.grid(alluvium = letters[1:4], x = 1:2) data$stratum <- LETTERS[c(1, 1, 1, 2, 2, 1, 3, 1)] data$y <- 1 data$fill <- c("red", "blue", "blue", "blue", "red", "blue", "blue", "blue") # order by index strata and linked strata (flows) #ggplot(data, aes(x = x, stratum = stratum, alluvium = alluvium, y = y)) + # geom_flow(aes(fill = fill)) comp <- StatFlow$compute_panel(data) expect_identical(comp[with(comp, order(x, alluvium)), ]$y, c(2.5, 1.5, 0.5, 3.5, 1.5, 0.5, 2.5, 3.5)) # order by index strata, linked strata (flows), and aesthetics #ggplot(data, aes(x = x, stratum = stratum, alluvium = alluvium, y = y)) + # geom_flow(aes(fill = fill), aes.bind = "flows") comp <- StatFlow$compute_panel(data, aes.bind = "flows") expect_identical(comp[with(comp, order(x, alluvium)), ]$y, c(1.5, 2.5, 0.5, 3.5, 1.5, 0.5, 2.5, 3.5)) # cannot order by aesthetics before by linked strata (flows) expect_warning(StatFlow$compute_panel(data, aes.bind = "alluvia"), "flows") }) # missing values test_that("`stat_flow` preserves missingness to position flows", { data <- data.frame(x = c(1, 2, 2, 3), stratum = factor(LETTERS[c(1L, 2L, 1L, 2L)]), alluvium = c(1L, 2L, 1L, 2L), PANEL = factor(1L), group = seq(4L), y = 1) comp <- StatFlow$compute_panel(data) expect_identical(sort(complete.cases(comp)), rep(c(FALSE, TRUE), c(2L, 4L))) }) # exceptional data test_that("`stat_flow` handles exceptional data with out errors", { wph <- as.data.frame(as.table(WorldPhones)) names(wph) <- c("Year", "Region", "Telephones") wph$Year <- as.integer(as.character(wph$Year)) gg <- ggplot(wph, aes(x = Year, alluvium = Region, y = Telephones)) + geom_flow(aes(fill = Region, colour = Region)) expect_silent(ggplot_build(gg)) }) ggalluvial/tests/testthat/test-alluvial-data.r0000644000176200001440000000732714452602415021277 0ustar liggesuserstitanic_alluvia <- as.data.frame(Titanic) null_wt <- NULL # `is_alluvia_form()` tests test_that("`is_alluvia_form` recognizes alluvia-format Titanic data", { expect_message(is_alluvia_form(titanic_alluvia), "[Mm]issing") expect_true(is_alluvia_form(titanic_alluvia, axes = c("Class", "Sex"))) expect_true(is_alluvia_form(titanic_alluvia, axes = 1:4)) expect_true(is_alluvia_form(titanic_alluvia, Class, Sex, Age)) expect_true(is_alluvia_form(titanic_alluvia, axes = c("Class", "Sex"), weight = "Freq")) expect_true(is_alluvia_form(titanic_alluvia, axes = 1:4, weight = 5)) expect_true(is_alluvia_form(titanic_alluvia, Class, Sex, Age, weight = Freq)) expect_true(is_alluvia_form(titanic_alluvia, Class, Sex, weight = !!null_wt)) }) # `to_lodes_form()` tests test_that("`to_lodes_form` consistently formats Titanic data", { expect_equivalent(to_lodes_form(titanic_alluvia, axes = c("Class", "Sex")), to_lodes_form(titanic_alluvia, axes = 1:2)) expect_equivalent(to_lodes_form(titanic_alluvia, axes = c("Class", "Sex")), to_lodes_form(titanic_alluvia, Class, Sex)) expect_equivalent(to_lodes_form(titanic_alluvia, axes = c("Class", "Sex"), diffuse = "Class"), to_lodes_form(titanic_alluvia, axes = 1:2, diffuse = 1)) expect_equivalent(to_lodes_form(titanic_alluvia, axes = c("Class", "Sex"), diffuse = "Class"), to_lodes_form(titanic_alluvia, Class, Sex, diffuse = Class)) }) # preparation for next tests titanic_lodes <- suppressWarnings(to_lodes_form( transform(titanic_alluvia, Index = 1:nrow(titanic_alluvia)), key = "Variable", value = "Value", id = "Index", axes = 1:4, factor_key = TRUE )) titanic_lodes$Value <- factor(titanic_lodes$Value, levels = do.call(c, lapply(titanic_alluvia[, 1:4], levels))) # `is_lodes_form()` tests test_that("`is_lodes_form` recognizes lodes-format Titanic data", { expect_error(is_lodes_form(titanic_lodes)) expect_true(is_lodes_form(titanic_lodes, key = "Variable", value = "Value", id = "Index")) expect_true(is_lodes_form(titanic_lodes, key = Variable, value = Value, id = Index)) expect_true(is_lodes_form(titanic_lodes, key = 3, value = 4, id = 2)) expect_true(is_lodes_form(titanic_lodes, key = "Variable", value = "Value", id = "Index", weight = "Freq")) expect_true(is_lodes_form(titanic_lodes, key = 3, value = 4, id = 2, weight = 1)) expect_true(is_lodes_form(titanic_lodes, key = Variable, value = Value, id = Index, weight = Freq)) expect_true(is_lodes_form(titanic_lodes, key = Variable, value = Value, id = Index, weight = !!null_wt)) }) # `to_alluvia_form()` tests test_that("`to_alluvia_form` consistently formats Titanic data", { expect_equivalent(to_alluvia_form(titanic_lodes, key = "Variable", value = "Value", id = "Index"), to_alluvia_form(titanic_lodes, key = 3, value = 4, id = 2)) expect_equivalent(to_alluvia_form(titanic_lodes, key = "Variable", value = "Value", id = "Index"), to_alluvia_form(titanic_lodes, key = Variable, value = Value, id = Index)) }) ggalluvial/tests/testthat/test-stat-alluvium.r0000644000176200001440000001070215042736161021357 0ustar liggesusers# weights are used but not returned test_that("`stat_alluvium` weights computed variables but drops weight", { # not cementing alluvia data <- expand.grid(alluvium = letters[1:3], x = 1:2) data$stratum <- LETTERS[c(1, 1, 2, 1, 2, 2)] data$y <- c(1, 1, 1, 1, 1, 2) data$weight <- c(.5, 1, 1, .5, 1, 1) comp <- StatAlluvium$compute_panel(data) comp <- comp[with(comp, order(x, alluvium)), ] expect_equivalent(comp$n, c(0.5, 1, 1, 0.5, 1, 1)) expect_equivalent(comp$count, c(0.5, 1, 1, 0.5, 1, 2)) expect_equivalent(comp$prop, c(c(1, 2, 2) / 5, c(1, 2, 4) / 7)) expect_equal(comp$lode, factor(rep(letters[1:3], times = 2))) expect_null(comp$weight) # cementing alluvia data$stratum <- LETTERS[c(1, 1, 2)] comp <- StatAlluvium$compute_panel(data, cement.alluvia = TRUE) comp <- comp[with(comp, order(x, alluvium)), ] expect_equivalent(comp$n, c(1.5, 1, 1.5, 1)) expect_equivalent(comp$count, c(1.5, 1, 1.5, 2)) expect_equivalent(comp$prop, c(c(3, 2) / 5, c(3, 4) / 7)) expect_equal(comp$lode, rep(factor(letters[1:3])[c(1, 3)], times = 2)) expect_null(comp$weight) }) # negative values test_that("`stat_alluvium` orders alluvia without regard to negative values", { data <- expand.grid(alluvium = letters[1:2], x = 1:2) data$stratum <- LETTERS[1] data$y <- c(-1, -1) # order by alluvium, `reverse = TRUE` #ggplot(data, aes(x = x, stratum = stratum, alluvium = alluvium, y = y)) + # geom_alluvium() + # geom_text(stat = "alluvium", aes(label = alluvium)) comp <- StatAlluvium$compute_panel(data) expect_identical(comp[with(comp, order(x, alluvium)), ]$y, c(-0.5, -1.5, -0.5, -1.5)) # order by alluvium, `reverse = FALSE` #ggplot(data, aes(x = x, stratum = stratum, alluvium = alluvium, y = y)) + # geom_alluvium(absolute = FALSE) + # geom_text(stat = "alluvium", aes(label = alluvium), absolute = FALSE) comp <- StatAlluvium$compute_panel(data, absolute = FALSE) expect_identical(comp[with(comp, order(x, alluvium)), ]$y, c(-0.5, -1.5, -0.5, -1.5)) }) # aesthetic binding test_that("`stat_alluvium` orders alluvia correctly according to `aes.bind`", { data <- expand.grid(alluvium = letters[1:4], x = 1:2) data$stratum <- LETTERS[1:2][c(1, 1, 2, 2, 2, 2, 2, 1)] data$y <- 1 data$fill <- c("red", "blue", "blue", "blue") # order by index strata, linked strata (flows), and alluvia #ggplot(data, aes(x = x, stratum = stratum, alluvium = alluvium, y = y)) + # geom_alluvium(aes(fill = fill)) + # geom_text(stat = "alluvium", aes(fill = fill, label = alluvium)) comp <- StatAlluvium$compute_panel(data) expect_identical(comp[with(comp, order(x, alluvium)), ]$y, c(3.5, 2.5, 0.5, 1.5, 2.5, 1.5, 0.5, 3.5)) # order by index strata, linked strata (flows), aesthetics, and alluvia #ggplot(data, aes(x = x, stratum = stratum, alluvium = alluvium, y = y)) + # geom_alluvium(aes(fill = fill), aes.bind = "flows") + # geom_text(stat = "alluvium", aes(fill = fill, label = alluvium), # aes.bind = "flows") comp <- StatAlluvium$compute_panel(data, aes.bind = "flows") expect_identical(comp[with(comp, order(x, alluvium)), ]$y, c(2.5, 3.5, 0.5, 1.5, 1.5, 2.5, 0.5, 3.5)) # order by index strata, aesthetics, linked strata (flows), and alluvia #ggplot(data, aes(x = x, stratum = stratum, alluvium = alluvium, y = y)) + # geom_alluvium(aes(fill = fill), aes.bind = "alluvia") + # geom_text(stat = "alluvium", aes(fill = fill, label = alluvium), # aes.bind = "alluvia") comp <- StatAlluvium$compute_panel(data, aes.bind = "alluvia") expect_identical(comp[with(comp, order(x, alluvium)), ]$y, c(2.5, 3.5, 0.5, 1.5, 0.5, 2.5, 1.5, 3.5)) }) # exceptional data test_that("`stat_flow` handles exceptional data with out errors", { skip_if_not_installed("alluvial") data(Refugees, package = "alluvial") refugees_sub <- subset(Refugees, year %in% c(2003, 2005, 2010, 2013)) gg <- ggplot(refugees_sub, aes(x = year, y = refugees, alluvium = country)) + geom_alluvium(aes(fill = country)) expect_silent(ggplot_build(gg)) }) d <- data.frame( subject = rep(c("A", "B"), each = 2), time = rep(1:2, times = 2), status = factor(c("a", "b", "b", "a")), value = c(0, 1, 0, 2) ) test_that("`stat_alluvium` handles axes with zero total height", { gg <- ggplot(d, aes(x = time, stratum = status, alluvium = subject, y = value)) + stat_alluvium(aes(fill = subject)) expect_silent(ggplot_build(gg)) }) ggalluvial/tests/testthat/_snaps/0000755000176200001440000000000014166562215016676 5ustar liggesusersggalluvial/tests/testthat/_snaps/geom-flow/0000755000176200001440000000000014452602415020565 5ustar liggesusersggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-arctangent-curve-with-custom-range.svg0000644000176200001440000026767514452602415032052 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'arctangent' curve with custom range ggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-cubic-curve.svg0000644000176200001440000026756614452602415025435 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'cubic' curve ggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-facets.svg0000644000176200001440000030447214452602415024457 0ustar liggesusers No Yes 0.8 1.2 1.6 2.0 0.8 1.2 1.6 2.0 0 500 1000 1500 Freq Age Child Adult `geom_flow`: facets ggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-unscaled-knot-positions.svg0000644000176200001440000027624614452602415030015 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: unscaled knot positions ggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-forward-orientation.svg0000644000176200001440000034374414452602415027214 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: forward orientation ggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-arctangent-curve.svg0000644000176200001440000026750114452602415026463 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'arctangent' curve ggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-sigmoid-curve-with-custom-range.svg0000644000176200001440000026761414452602415031350 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'sigmoid' curve with custom range ggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-linear-curve.svg0000644000176200001440000026771514452602415025616 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'linear' curve ggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-sine-curve.svg0000644000176200001440000026755514452602415025304 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'sine' curve ggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-sigmoid-curve.svg0000644000176200001440000026741614452602415025775 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'sigmoid' curve ggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-aesthetic.svg0000644000176200001440000024175514452602415025167 0ustar liggesusers 0 500 1000 1500 2000 1.0 1.5 2.0 2.5 3.0 Freq Survived No Yes `geom_flow`: aesthetic ggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-backward-orientation.svg0000644000176200001440000034374514452602415027327 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: backward orientation ggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-quintic-curve.svg0000644000176200001440000026752014452602415026012 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'quintic' curve ggalluvial/tests/testthat/_snaps/geom-flow/geom-flow-basic.svg0000644000176200001440000012624714452602415024275 0ustar liggesusers 0 500 1000 1500 2000 1.0 1.5 2.0 2.5 3.0 Freq `geom_flow`: basic ggalluvial/tests/testthat/_snaps/geom-lode/0000755000176200001440000000000014704334714020545 5ustar liggesusersggalluvial/tests/testthat/_snaps/geom-lode/geom-lode-lodes-as-strata.svg0000644000176200001440000066175414452602415026156 0ustar liggesusers 0 500 1000 1500 2000 1.0 1.5 2.0 2.5 3.0 Freq Survived No Yes `geom_lode`: lodes as strata ggalluvial/tests/testthat/_snaps/geom-lode/geom-lode-one-axis.svg0000644000176200001440000003013714704334714024663 0ustar liggesusers 0 500 1000 1500 2000 Class Freq Survived No Yes Class 1st 2nd 3rd Crew `geom_lode`: one axis ggalluvial/tests/testthat/_snaps/geom-lode/geom-lode-lodes-and-alluvia.svg0000644000176200001440000067036214452602415026447 0ustar liggesusers 0 500 1000 1500 2000 1.0 1.5 2.0 2.5 3.0 Freq Survived No Yes `geom_lode`: lodes and alluvia ggalluvial/tests/testthat/_snaps/geom-stratum/0000755000176200001440000000000014370022542021311 5ustar liggesusersggalluvial/tests/testthat/_snaps/geom-stratum/geom-stratum-facets-and-axis-labels.svg0000644000176200001440000002126714370022542030673 0ustar liggesusers Child Adult Class Sex Class Sex 0 500 1000 1500 2000 0 30 60 90 Freq `geom_stratum`: facets and axis labels ggalluvial/tests/testthat/_snaps/geom-stratum/geom-stratum-axis-labels.svg0000644000176200001440000001346614370022542026672 0ustar liggesusers 0 500 1000 1500 2000 Class Sex Age Survived Freq `geom_stratum`: axis labels ggalluvial/tests/testthat/_snaps/geom-stratum/geom-stratum-basic.svg0000644000176200001440000001342114370022542025536 0ustar liggesusers 0 500 1000 1500 2000 1 2 3 4 Freq `geom_stratum`: basic ggalluvial/tests/testthat/_snaps/geom-stratum/geom-stratum-inferred-text-labels.svg0000644000176200001440000001353214166562215030511 0ustar liggesusers Crew 3rd 2nd 1st Female Male Adult Child Yes No 0 500 1000 1500 2000 1 2 3 4 Freq `geom_stratum`: inferred text labels ggalluvial/tests/testthat/_snaps/geom-stratum/geom-stratum-facets.svg0000644000176200001440000002346014370022542025726 0ustar liggesusers Child Adult 0.8 1.2 1.6 2.0 0.8 1.2 1.6 2.0 0 500 1000 1500 2000 0 30 60 90 Freq `geom_stratum`: facets ggalluvial/tests/testthat/_snaps/geom-stratum/geom-stratum-extended-width.svg0000644000176200001440000001343214370022542027374 0ustar liggesusers 0 500 1000 1500 2000 1 2 3 4 Freq `geom_stratum`: extended width ggalluvial/tests/testthat/_snaps/geom-alluvium/0000755000176200001440000000000014452602415021454 5ustar liggesusersggalluvial/tests/testthat/_snaps/geom-alluvium/geom-alluvium-linear-curve.svg0000644000176200001440000070346414452602415027370 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'linear' curve ggalluvial/tests/testthat/_snaps/geom-alluvium/geom-alluvium-unscaled-knot-positions.svg0000644000176200001440000071207314452602415031564 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: unscaled knot positions ggalluvial/tests/testthat/_snaps/geom-alluvium/geom-alluvium-sine-curve.svg0000644000176200001440000070315414452602415027050 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'sine' curve ggalluvial/tests/testthat/_snaps/geom-alluvium/geom-alluvium-sigmoid-curve.svg0000644000176200001440000070263514452602415027550 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'sigmoid' curve ggalluvial/tests/testthat/_snaps/geom-alluvium/geom-alluvium-quintic-curve.svg0000644000176200001440000070304114452602415027561 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'quintic' curve ggalluvial/tests/testthat/_snaps/geom-alluvium/geom-alluvium-facets.svg0000644000176200001440000033771214452602415026240 0ustar liggesusers No Yes 1.00 1.25 1.50 1.75 2.00 1.00 1.25 1.50 1.75 2.00 0 500 1000 1500 Freq Age Child Adult `geom_alluvium`: facets ggalluvial/tests/testthat/_snaps/geom-alluvium/geom-alluvium-bump-plot.svg0000644000176200001440000050244214452602415026704 0ustar liggesusers 0e+00 2e+06 4e+06 6e+06 8e+06 2002.5 2005.0 2007.5 2010.0 2012.5 year refugees country Afghanistan Burundi Congo DRC Iraq Myanmar Palestine Somalia Sudan Syria Vietnam `geom_alluvium`: bump plot ggalluvial/tests/testthat/_snaps/geom-alluvium/geom-alluvium-cubic-curve.svg0000644000176200001440000070317714452602415027204 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'cubic' curve ggalluvial/tests/testthat/_snaps/geom-alluvium/geom-alluvium-arctangent-curve.svg0000644000176200001440000070301414452602415030233 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'arctangent' curve ggalluvial/tests/testthat/_snaps/geom-alluvium/geom-alluvium-sigmoid-curve-with-custom-range.svg0000644000176200001440000070323314452602415033116 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'sigmoid' curve with custom range ggalluvial/tests/testthat/_snaps/geom-alluvium/geom-alluvium-arctangent-curve-with-custom-range.svg0000644000176200001440000070340414452602415033611 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'arctangent' curve with custom range ggalluvial/tests/testthat/_snaps/geom-alluvium/geom-alluvium-line-plot.svg0000644000176200001440000040550214452602415026667 0ustar liggesusers 0e+00 2e+06 4e+06 6e+06 8e+06 2002.5 2005.0 2007.5 2010.0 2012.5 year refugees country Afghanistan Burundi Congo DRC Iraq Myanmar Palestine Somalia Sudan Syria Vietnam `geom_alluvium`: line plot ggalluvial/tests/testthat/_snaps/geom-alluvium/geom-alluvium-basic.svg0000644000176200001440000066027214452602415026054 0ustar liggesusers 0 500 1000 1500 2000 1.0 1.5 2.0 2.5 3.0 Freq Survived No Yes `geom_alluvium`: basic ggalluvial/tests/testthat/test-geom-lode.r0000644000176200001440000000132114452602415020413 0ustar liggesusers# visual tests test_that("`geom_lode` draws correctly", { d <- as.data.frame(Titanic) a1 <- aes(y = Freq, axis = Class) a2 <- aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, fill = Survived) skip_on_cran() skip_if_not_installed("vdiffr") suppressWarnings(vdiffr::expect_doppelganger( "`geom_lode`: one axis", ggplot(d, a1) + geom_lode(aes(fill = Class, alpha = Survived)) + scale_x_discrete(limits = c("Class")) )) vdiffr::expect_doppelganger( "`geom_lode`: lodes and alluvia", ggplot(d, a2) + geom_alluvium() + geom_lode() ) vdiffr::expect_doppelganger( "`geom_lode`: lodes as strata", ggplot(d, a2) + geom_alluvium() + geom_stratum(stat = "alluvium") ) }) ggalluvial/tests/testthat/test-geom-flow.r0000644000176200001440000001062314452602415020444 0ustar liggesusers# curve tests test_that("`positions_to_flow` computes as expected", { # spline curve spline_curve <- positions_to_flow(1, 2, 0, 1, 1, 2, 1.3, 1.7, FALSE, "spline", NULL, NULL) expect_equal(nrow(spline_curve), 8L) expect_equal(spline_curve$x, c(1, 2.3, 0.3, 2, 2, 0.3, 2.3, 1)) expect_equal(unique(spline_curve$y), c(0, 1, 2)) expect_equal(unique(spline_curve$shape), c(0, 1)) # cubic curve cubic_curve <- positions_to_flow(1, 2, 0, 1, 1, 2, 1.3, 1.7, FALSE, "cubic", NULL, 8L) expect_equal(nrow(cubic_curve), 2L * 8L + 2L) expect_equal(unique(cubic_curve$x), seq(1, 2, .125)) expect_equal(unique(cubic_curve$shape), 0) }) # visual tests test_that("`geom_flow` draws correctly", { d <- as.data.frame(Titanic) a1 <- aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age) a2 <- aes(y = Freq, axis1 = Class, axis2 = Sex) skip_on_cran() skip_if_not_installed("vdiffr") vdiffr::expect_doppelganger( "`geom_flow`: basic", ggplot(d, a1) + geom_flow() ) vdiffr::expect_doppelganger( "`geom_flow`: aesthetic", ggplot(d, a1) + geom_flow(aes(fill = Survived)) ) vdiffr::expect_doppelganger( "`geom_flow`: facets", ggplot(d, a2) + geom_flow(aes(fill = Age), width = .4) + facet_wrap(~ Survived, scales = "fixed") ) }) data(vaccinations) test_that("`geom_flow` orients flows correctly", { skip_on_cran() skip_if_not_installed("vdiffr") vdiffr::expect_doppelganger( "`geom_flow`: forward orientation", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_lode() + geom_flow() ) vdiffr::expect_doppelganger( "`geom_flow`: backward orientation", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_lode() + geom_flow(aes.flow = "backward") ) }) test_that("`geom_flow()` recognizes alternative curves", { skip_on_cran() skip_if_not_installed("vdiffr") vdiffr::expect_doppelganger( "`geom_flow`: unscaled knot positions", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_stratum() + geom_flow(knot.prop = FALSE) ) vdiffr::expect_doppelganger( "`geom_flow`: 'linear' curve", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_stratum() + geom_flow(curve_type = "linear") ) vdiffr::expect_doppelganger( "`geom_flow`: 'cubic' curve", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_stratum() + geom_flow(curve_type = "cubic") ) vdiffr::expect_doppelganger( "`geom_flow`: 'quintic' curve", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_stratum() + geom_flow(curve_type = "quintic") ) vdiffr::expect_doppelganger( "`geom_flow`: 'sine' curve", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_stratum() + geom_flow(curve_type = "sine") ) vdiffr::expect_doppelganger( "`geom_flow`: 'arctangent' curve", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_stratum() + geom_flow(curve_type = "arctan") ) vdiffr::expect_doppelganger( "`geom_flow`: 'arctangent' curve with custom range", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_stratum() + geom_flow(curve_type = "arctan", curve_range = 1) ) vdiffr::expect_doppelganger( "`geom_flow`: 'sigmoid' curve", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_stratum() + geom_flow(curve_type = "sigmoid") ) vdiffr::expect_doppelganger( "`geom_flow`: 'sigmoid' curve with custom range", ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_stratum() + geom_flow(curve_type = "sigmoid", curve_range = 3) ) }) ggalluvial/tests/testthat.R0000644000176200001440000000010014112432105015506 0ustar liggesuserslibrary(testthat) library(ggalluvial) test_check("ggalluvial") ggalluvial/tests/figs/0000755000176200001440000000000014112432105014464 5ustar liggesusersggalluvial/tests/figs/geom-flow/0000755000176200001440000000000014112432105016360 5ustar liggesusersggalluvial/tests/figs/geom-flow/geom-flow-cubic-curve.svg0000644000176200001440000015316414112432105023214 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'cubic' curve ggalluvial/tests/figs/geom-flow/geom-flow-facets.svg0000644000176200001440000016054014112432105022246 0ustar liggesusers No Yes 0.8 1.2 1.6 2.0 0.8 1.2 1.6 2.0 0 500 1000 1500 Freq Age Child Adult `geom_flow`: facets ggalluvial/tests/figs/geom-flow/geom-flow-unscaled-knot-positions.svg0000644000176200001440000015642014112432105025577 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: unscaled knot positions ggalluvial/tests/figs/geom-flow/geom-flow-forward-orientation.svg0000644000176200001440000023442014112432105024775 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: forward orientation ggalluvial/tests/figs/geom-flow/geom-flow-arctangent-curve.svg0000644000176200001440000015313414112432105024252 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'arctangent' curve ggalluvial/tests/figs/geom-flow/geom-flow-linear-curve.svg0000644000176200001440000015324014112432105023374 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'linear' curve ggalluvial/tests/figs/geom-flow/geom-flow-sine-curve.svg0000644000176200001440000015315714112432105023067 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'sine' curve ggalluvial/tests/figs/geom-flow/geom-flow-sigmoid-curve.svg0000644000176200001440000015310114112432105023551 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'sigmoid' curve ggalluvial/tests/figs/geom-flow/geom-flow-aesthetic.svg0000644000176200001440000013332214112432105022750 0ustar liggesusers 0 500 1000 1500 2000 1.0 1.5 2.0 2.5 3.0 Freq Survived No Yes `geom_flow`: aesthetic ggalluvial/tests/figs/geom-flow/geom-flow-backward-orientation.svg0000644000176200001440000023442114112432105025110 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: backward orientation ggalluvial/tests/figs/geom-flow/geom-flow-quintic-curve.svg0000644000176200001440000015314214112432105023577 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_flow`: 'quintic' curve ggalluvial/tests/figs/geom-flow/geom-flow-basic.svg0000644000176200001440000006244114112432105022063 0ustar liggesusers 0 500 1000 1500 2000 1.0 1.5 2.0 2.5 3.0 Freq `geom_flow`: basic ggalluvial/tests/figs/geom-lode/0000755000176200001440000000000014112432105016334 5ustar liggesusersggalluvial/tests/figs/geom-lode/geom-lode-lodes-as-strata.svg0000644000176200001440000037145214112432105023742 0ustar liggesusers 0 500 1000 1500 2000 1.0 1.5 2.0 2.5 3.0 Freq Survived No Yes `geom_lode`: lodes as strata ggalluvial/tests/figs/geom-lode/geom-lode-one-axis.svg0000644000176200001440000003601414112432105022452 0ustar liggesusers 0 500 1000 1500 2000 Class Freq Survived No Yes Class 1st 2nd 3rd Crew `geom_lode`: one axis ggalluvial/tests/figs/geom-lode/geom-lode-lodes-and-alluvia.svg0000644000176200001440000040006014112432105024224 0ustar liggesusers 0 500 1000 1500 2000 1.0 1.5 2.0 2.5 3.0 Freq Survived No Yes `geom_lode`: lodes and alluvia ggalluvial/tests/figs/geom-stratum/0000755000176200001440000000000014112432105017110 5ustar liggesusersggalluvial/tests/figs/geom-stratum/geom-stratum-facets-and-axis-labels.svg0000644000176200001440000002526414112432105026473 0ustar liggesusers Child Adult Class Sex Class Sex 0 500 1000 1500 2000 0 30 60 90 Freq `geom_stratum`: facets and axis labels ggalluvial/tests/figs/geom-stratum/geom-stratum-axis-labels.svg0000644000176200001440000001575414112432105024473 0ustar liggesusers 0 500 1000 1500 2000 Class Sex Age Survived Freq `geom_stratum`: axis labels ggalluvial/tests/figs/geom-stratum/geom-stratum-basic.svg0000644000176200001440000001570714112432105023346 0ustar liggesusers 0 500 1000 1500 2000 1 2 3 4 Freq `geom_stratum`: basic ggalluvial/tests/figs/geom-stratum/geom-stratum-inferred-text-labels.svg0000644000176200001440000001631614112432105026302 0ustar liggesusers Crew 3rd 2nd 1st Female Male Adult Child Yes No 0 500 1000 1500 2000 1 2 3 4 Freq `geom_stratum`: inferred text labels ggalluvial/tests/figs/geom-stratum/geom-stratum-facets.svg0000644000176200001440000003031114112432105023516 0ustar liggesusers Child Adult 0.8 1.2 1.6 2.0 0.8 1.2 1.6 2.0 0 500 1000 1500 2000 0 30 60 90 Freq `geom_stratum`: facets ggalluvial/tests/figs/geom-stratum/geom-stratum-extended-width.svg0000644000176200001440000001572014112432105025175 0ustar liggesusers 0 500 1000 1500 2000 1 2 3 4 Freq `geom_stratum`: extended width ggalluvial/tests/figs/deps.txt0000644000176200001440000000010314112432105016152 0ustar liggesusers- vdiffr-svg-engine: 1.0 - vdiffr: 0.3.1 - freetypeharfbuzz: 0.2.5 ggalluvial/tests/figs/geom-alluvium/0000755000176200001440000000000014112432105017247 5ustar liggesusersggalluvial/tests/figs/geom-alluvium/geom-alluvium-linear-curve.svg0000644000176200001440000035624614112432105025165 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'linear' curve ggalluvial/tests/figs/geom-alluvium/geom-alluvium-unscaled-knot-positions.svg0000644000176200001440000036145514112432105027363 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: unscaled knot positions ggalluvial/tests/figs/geom-alluvium/geom-alluvium-sine-curve.svg0000644000176200001440000035610114112432105024637 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'sine' curve ggalluvial/tests/figs/geom-alluvium/geom-alluvium-sigmoid-curve.svg0000644000176200001440000035573314112432105025346 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'sigmoid' curve ggalluvial/tests/figs/geom-alluvium/geom-alluvium-quintic-curve.svg0000644000176200001440000035603514112432105025363 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'quintic' curve ggalluvial/tests/figs/geom-alluvium/geom-alluvium-facets.svg0000644000176200001440000017724114112432105024032 0ustar liggesusers No Yes 1.00 1.25 1.50 1.75 2.00 1.00 1.25 1.50 1.75 2.00 0 500 1000 1500 Freq Age Child Adult `geom_alluvium`: facets ggalluvial/tests/figs/geom-alluvium/geom-alluvium-bump-plot.svg0000644000176200001440000026107614112432105024504 0ustar liggesusers 0e+00 2e+06 4e+06 6e+06 8e+06 2002.5 2005.0 2007.5 2010.0 2012.5 year refugees country Afghanistan Burundi Congo DRC Iraq Myanmar Palestine Somalia Sudan Syria Vietnam `geom_alluvium`: bump plot ggalluvial/tests/figs/geom-alluvium/geom-alluvium-cubic-curve.svg0000644000176200001440000035611314112432105024771 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'cubic' curve ggalluvial/tests/figs/geom-alluvium/geom-alluvium-arctangent-curve.svg0000644000176200001440000035602414112432105026033 0ustar liggesusers 0 250 500 750 1000 ms153_NSA ms432_NSA ms460_NSA survey freq response Missing Never Sometimes Always `geom_alluvium`: 'arctangent' curve ggalluvial/tests/figs/geom-alluvium/geom-alluvium-line-plot.svg0000644000176200001440000027306314112432105024467 0ustar liggesusers 0e+00 2e+06 4e+06 6e+06 8e+06 2002.5 2005.0 2007.5 2010.0 2012.5 year refugees country Afghanistan Burundi Congo DRC Iraq Myanmar Palestine Somalia Sudan Syria Vietnam `geom_alluvium`: line plot ggalluvial/tests/figs/geom-alluvium/geom-alluvium-basic.svg0000644000176200001440000034320114112432105023635 0ustar liggesusers 0 500 1000 1500 2000 1.0 1.5 2.0 2.5 3.0 Freq Survived No Yes `geom_alluvium`: basic ggalluvial/MD50000644000176200001440000002555415146573312012733 0ustar liggesusersf341cb5b9abbde7fb25b6d6dd5bd32aa *DESCRIPTION 501d29c3db005a95a1cb0e28f2859cff *NAMESPACE 0f081dbf50d6419e464f152d0847a05f *NEWS.md 060d092ab983e94d220b92fa3546f627 *R/alluvial-data.r 09aa353f212a485fffb576bf09e1ecb0 *R/data.r 24daa41e0bdd5707c1db36376153527a *R/devel.r 761681cad46d0d7551a1fc77450b0f59 *R/geom-alluvium.r 0a7261e9ae4feedf1e779c9581c6e7ea *R/geom-flow.r 7f3cbb097bad73aa42f72e49d808becc *R/geom-lode.r 2a31c7335523f9410cb7b0302d4f0bd4 *R/geom-stratum.r 381ec3f04c84b1356150879f98e27945 *R/geom-utils.r 403e922be3cc939f512c75ca55d8453d *R/ggalluvial-package.r 7d53688cdfb70ea93e4e951348f65837 *R/ggproto.r 94433385ca501998e4d3720d3a3b8e6c *R/lode-guidance-functions.r 3cd997dcccb780025a8274ee3f371346 *R/self-adjoin.r 6855e92a5d30dc11632698c0daf3eb7f *R/stat-alluvium.r 8e60bf1158a89eee4007ac21c2e0c3df *R/stat-flow.r 92e07812291b85e8f9982be6515ceea8 *R/stat-stratum.r 90ad7c7833ac54ba7156a46efaedc86c *R/stat-utils.r c41b7a5ef3d87b0334851e3a6aef2ace *R/utils.r e4f27efb805b1aca47fb3d0efb29bcdd *README.md 76e123f5dcc8dee07678412adc0a2a84 *build/partial.rdb d9fb81c01950f94f2cf59d2cb397b1b0 *build/vignette.rds 96bce82e0f24d1ff28ed6c6b5205ad52 *data/majors.rda 5223231efa77767c267893a6105952c8 *data/vaccinations.rda b397890005f835604a3d9bc10f0bab73 *inst/CITATION 9263652123a09399fc3fd5d536597cc2 *inst/doc/ggalluvial.R c31d1abf995cde55462b9a8dd9d5c2d4 *inst/doc/ggalluvial.html 0381295a12839e0f693885fe8ec9a4dc *inst/doc/ggalluvial.rmd ca77b0132eeacfb09a95e62de751c7fb *inst/doc/labels.R cad533211aac52723cc88a9e501f6e3a *inst/doc/labels.html 64137b3b858d1d240456dc435f40b6a8 *inst/doc/labels.rmd 86bc5c624c58cb785e4cd24f4f86fdcb *inst/doc/order-rectangles.R cd9ce6e1d9ba260c5eecd4a009432b5d *inst/doc/order-rectangles.html d9376fc182b778ae52fd8423a80ebd54 *inst/doc/order-rectangles.rmd a792410e41d50be7251168f4598b0861 *inst/doc/shiny.R c10b9409498bac0e674b1dcaa3d3549c *inst/doc/shiny.Rmd 6b8f576568badc7d6fa98d000e3e8bee *inst/doc/shiny.html f0396a001c5dbff3e569c43e69996dac *inst/examples/ex-alluvial-data.r 8365abbdca180174d96578bbc24fd733 *inst/examples/ex-geom-alluvium.r 5417e5f8ceb66497c39205d7009d9f15 *inst/examples/ex-geom-flow.r 06afb1bd496c895cd59d3a13de627bb1 *inst/examples/ex-geom-lode.r ca574ad27ff9e108d2e0b27a4228fbda *inst/examples/ex-geom-stratum.r ee0c1aeb45783b02702d73ba0eab71a8 *inst/examples/ex-self-adjoin.r b52699325b149e6d3e61df9c2845f8cf *inst/examples/ex-shiny-long-data/app.R b206e3baa0b99245bc0a420a3d92cf24 *inst/examples/ex-shiny-wide-data/app.R fc83ce98dee106452d2825d4e53ba871 *inst/examples/ex-stat-alluvium.r 6d37af8af13de17a748f804e04ec2798 *inst/examples/ex-stat-flow.r 4d355ce9ca7dfeede6d9c11ec1b58384 *inst/examples/ex-stat-stratum.r 6a68b662b2fa0df6fc56c4b421ba3d42 *man/alluvial-data.Rd 40051a31746f8fbbb5c37c4cf35bf233 *man/figures/README-unnamed-chunk-6-1.png 5c7d084f43664ec43704dd48ad51bb87 *man/figures/README-unnamed-chunk-7-1.png 7eade7cd75421fbf0f3e5fd64452a25f *man/geom_alluvium.Rd 203be0625616243518a30fc1fa515585 *man/geom_flow.Rd 5ffaa118e6fa48c452feded5187fe017 *man/geom_lode.Rd 9a6782b1fb19d677fe9acb2d8c1178d7 *man/geom_stratum.Rd 77310f20634ab54c42172859d5b23065 *man/ggalluvial-deprecated.Rd db003803ce31ab013cfa1b023c608e3a *man/ggalluvial-ggproto.Rd 7ead7dc12053d9afabed15b5d3ceffa1 *man/ggalluvial-package.Rd c5617b37eb2966c87406083b2412772b *man/lode-guidance-functions.Rd 642665787614a79aba58513bd73fa5be *man/majors.Rd 8fcddc4c1f89c6b2146254925448063e *man/self-adjoin.Rd 16dca107deeccda25644c54f50786329 *man/stat_alluvium.Rd 7576c6200ea232ccc4fa40e60b10d608 *man/stat_flow.Rd d9086abe6147c8439b2792d41273a166 *man/stat_stratum.Rd ae6df5b9750c3beeeb96617bdd42c136 *man/vaccinations.Rd 37455b724fc4126f1b8305cc5c05f444 *tests/figs/deps.txt 80a8836753d1d3974c51fa0bf8e4b643 *tests/figs/geom-alluvium/geom-alluvium-arctangent-curve.svg 7f178f59183893b0c74d4c12d6dda194 *tests/figs/geom-alluvium/geom-alluvium-basic.svg 791d677b21d6f9e87694e085c69a935f *tests/figs/geom-alluvium/geom-alluvium-bump-plot.svg c598e7783c69b2d0e1b52eb88396058a *tests/figs/geom-alluvium/geom-alluvium-cubic-curve.svg ba16e338ba8430415afd85c649f9a148 *tests/figs/geom-alluvium/geom-alluvium-facets.svg 269f15694a3c74a2975d5b536e9d4ea0 *tests/figs/geom-alluvium/geom-alluvium-line-plot.svg 8a5af214a9c3811c5224ebd4e9677ba2 *tests/figs/geom-alluvium/geom-alluvium-linear-curve.svg 59322eeecd3c0fa6acd1019d905db3dc *tests/figs/geom-alluvium/geom-alluvium-quintic-curve.svg 16d4545399ef44c1243c5ad0fd36fc7d *tests/figs/geom-alluvium/geom-alluvium-sigmoid-curve.svg c41a1587657d0be858436146ac806029 *tests/figs/geom-alluvium/geom-alluvium-sine-curve.svg d89637db1cc00533472c3bbf9251f831 *tests/figs/geom-alluvium/geom-alluvium-unscaled-knot-positions.svg 408eb295b4e40fd2523ca26c5050c9e7 *tests/figs/geom-flow/geom-flow-aesthetic.svg 9b05e92d0e89f7a8c8c22e9be21bbbaf *tests/figs/geom-flow/geom-flow-arctangent-curve.svg 9104176abeba96d128d03728c4e24c53 *tests/figs/geom-flow/geom-flow-backward-orientation.svg f339c9a794544a0150319b7f7546b0d1 *tests/figs/geom-flow/geom-flow-basic.svg d159996aacb6566b1c40ac37ca98e06d *tests/figs/geom-flow/geom-flow-cubic-curve.svg 8bb37a5d9ad931ae14b4d39520e2da41 *tests/figs/geom-flow/geom-flow-facets.svg 5e207c9545d6962800f7c29b05111d8b *tests/figs/geom-flow/geom-flow-forward-orientation.svg e58819cc82fb37ee3cafa42fc1aa33c6 *tests/figs/geom-flow/geom-flow-linear-curve.svg 78fbcdabefeea8943ed4076b8dc61514 *tests/figs/geom-flow/geom-flow-quintic-curve.svg c0a7cad8279c584c31415e6a1b949cc1 *tests/figs/geom-flow/geom-flow-sigmoid-curve.svg 4578b53eee1f8ab2303e44a99395b19d *tests/figs/geom-flow/geom-flow-sine-curve.svg 14aeb212895d30e1778b0928bb2d9ca6 *tests/figs/geom-flow/geom-flow-unscaled-knot-positions.svg 2c336196ba2f5b28c34cbed7ebb500e3 *tests/figs/geom-lode/geom-lode-lodes-and-alluvia.svg 00f5f305c794f03d08f13f94e16635dd *tests/figs/geom-lode/geom-lode-lodes-as-strata.svg 48f75b82c0958493aaa8eb50b9f4a215 *tests/figs/geom-lode/geom-lode-one-axis.svg 822a21cb71e7d2cc1e2c93700ee07b86 *tests/figs/geom-stratum/geom-stratum-axis-labels.svg 6424087e3ca003aefd4f536b4217e0f6 *tests/figs/geom-stratum/geom-stratum-basic.svg 5c051c27d36886ad07f5a2da9b65874f *tests/figs/geom-stratum/geom-stratum-extended-width.svg e793a9ec3c67e177c59b0c9d43a27a6e *tests/figs/geom-stratum/geom-stratum-facets-and-axis-labels.svg a15f703b58f52550aabedf54a81a807d *tests/figs/geom-stratum/geom-stratum-facets.svg c1662f77e2600e5343bda99a39bcfcf8 *tests/figs/geom-stratum/geom-stratum-inferred-text-labels.svg b742a5fd073aa7f6e60ec5c35b2aa9c7 *tests/testthat.R 1684580ab355b3e41fe0612467bf5947 *tests/testthat/_snaps/geom-alluvium/geom-alluvium-arctangent-curve-with-custom-range.svg 3c84fe0e39c8b843bcc710c3b386a5d1 *tests/testthat/_snaps/geom-alluvium/geom-alluvium-arctangent-curve.svg 49135c031b85c71ed33f7791a3396e2a *tests/testthat/_snaps/geom-alluvium/geom-alluvium-basic.svg 84f395bc55ee53a175ae597b062b41c4 *tests/testthat/_snaps/geom-alluvium/geom-alluvium-bump-plot.svg 232dd56271854f5883f312afe9273fa9 *tests/testthat/_snaps/geom-alluvium/geom-alluvium-cubic-curve.svg 088126d5af65119a52a2fabef11b1c97 *tests/testthat/_snaps/geom-alluvium/geom-alluvium-facets.svg bf3aa351c3cc2f64f5cd8a63bfb7c357 *tests/testthat/_snaps/geom-alluvium/geom-alluvium-line-plot.svg a2ac665becc7b4506c099ac53a4413f4 *tests/testthat/_snaps/geom-alluvium/geom-alluvium-linear-curve.svg bf28f16e007d9b20285b798aa156b6cf *tests/testthat/_snaps/geom-alluvium/geom-alluvium-quintic-curve.svg 14f404daf17388dd25e8b8177e9a919a *tests/testthat/_snaps/geom-alluvium/geom-alluvium-sigmoid-curve-with-custom-range.svg e3b53809746b4d38885cc49aa8a536e0 *tests/testthat/_snaps/geom-alluvium/geom-alluvium-sigmoid-curve.svg 02745fe97f6a8648608a87d9ed81232d *tests/testthat/_snaps/geom-alluvium/geom-alluvium-sine-curve.svg 8102bc8507ef3298bd7237f70fd1b9c5 *tests/testthat/_snaps/geom-alluvium/geom-alluvium-unscaled-knot-positions.svg 1d2f84fbd5c8c7f2ee662ae1723f3a56 *tests/testthat/_snaps/geom-flow/geom-flow-aesthetic.svg 8c239b152ebdc5792a407e7c55213799 *tests/testthat/_snaps/geom-flow/geom-flow-arctangent-curve-with-custom-range.svg d501bc04b8c5322355032b839623434d *tests/testthat/_snaps/geom-flow/geom-flow-arctangent-curve.svg b7044a24a9afac4b2f2fead338391b1a *tests/testthat/_snaps/geom-flow/geom-flow-backward-orientation.svg c3f0812a91ff906e29e80723184b908a *tests/testthat/_snaps/geom-flow/geom-flow-basic.svg c8c0b96c2931381355e296c60ef4ffda *tests/testthat/_snaps/geom-flow/geom-flow-cubic-curve.svg 6e9c8772fc2316f7c6600b6e3353dbed *tests/testthat/_snaps/geom-flow/geom-flow-facets.svg d62620dffc562aeb74e92684549fbbfa *tests/testthat/_snaps/geom-flow/geom-flow-forward-orientation.svg 3a8f7e4cb67c4a8d577a58586408db8c *tests/testthat/_snaps/geom-flow/geom-flow-linear-curve.svg 5d0f7e7e3c0cc08a773f9c7b6a1bdffe *tests/testthat/_snaps/geom-flow/geom-flow-quintic-curve.svg 02a74a4afc377e18eaea0bff4cd92195 *tests/testthat/_snaps/geom-flow/geom-flow-sigmoid-curve-with-custom-range.svg 4f42cbd2576cea7842f9afe32c5322ce *tests/testthat/_snaps/geom-flow/geom-flow-sigmoid-curve.svg 00aa72f9466b060617c15df252d92a83 *tests/testthat/_snaps/geom-flow/geom-flow-sine-curve.svg 450d038615e23b529ac89aa1d848595a *tests/testthat/_snaps/geom-flow/geom-flow-unscaled-knot-positions.svg 5b81663e8c64c7c7e2a7791c427c9cf9 *tests/testthat/_snaps/geom-lode/geom-lode-lodes-and-alluvia.svg d343acbf57e32981cad13d03abf36e93 *tests/testthat/_snaps/geom-lode/geom-lode-lodes-as-strata.svg c5b268fc1debacecf87b5a45a543a87d *tests/testthat/_snaps/geom-lode/geom-lode-one-axis.svg 53da1b555634c02c5daac4efff6b6d77 *tests/testthat/_snaps/geom-stratum/geom-stratum-axis-labels.svg a836a0fc098705cfa104cd37c0a45b59 *tests/testthat/_snaps/geom-stratum/geom-stratum-basic.svg d68f0c876236427d8ca15d186152f984 *tests/testthat/_snaps/geom-stratum/geom-stratum-extended-width.svg 4f8e09f5cf713d58c712ffea49b18a10 *tests/testthat/_snaps/geom-stratum/geom-stratum-facets-and-axis-labels.svg 8f21c88a01e8032a6e8d0d03948e3f50 *tests/testthat/_snaps/geom-stratum/geom-stratum-facets.svg eb07a40e45b2fd8a2d8444cf87740370 *tests/testthat/_snaps/geom-stratum/geom-stratum-inferred-text-labels.svg e279a278cdf9068a7b73592595dfd90a *tests/testthat/test-alluvial-data.r b650193866623f7f1c1faed8e7093c2e *tests/testthat/test-geom-alluvium.r 4a2b692a16c3a3e8122b84328d18140a *tests/testthat/test-geom-flow.r 59646104939bb4429d7d4f7726bcd097 *tests/testthat/test-geom-lode.r 08b95b27214bdba9c0a7c20efd05981a *tests/testthat/test-geom-stratum.r e87f384e26399c784c15a3b11a2c0b2d *tests/testthat/test-stat-alluvium.r 270cb218cb2a42361e3d880d3d1305f7 *tests/testthat/test-stat-flow.r babfc663c0558da02e9a6f33d0423a68 *tests/testthat/test-stat-stratum.r 0381295a12839e0f693885fe8ec9a4dc *vignettes/ggalluvial.rmd 86dc3a5abc2ccdc272bced12595f3c2d *vignettes/img/hover_alluvium.png cfb69383eaae0fbf596f1734e77c80c9 *vignettes/img/hover_empty_area.png b73588e1a048d76ab751ab89ad9060f7 *vignettes/img/hover_stratum.png 64137b3b858d1d240456dc435f40b6a8 *vignettes/labels.rmd d9376fc182b778ae52fd8423a80ebd54 *vignettes/order-rectangles.rmd c10b9409498bac0e674b1dcaa3d3549c *vignettes/shiny.Rmd ggalluvial/R/0000755000176200001440000000000015146420370012604 5ustar liggesusersggalluvial/R/stat-stratum.r0000644000176200001440000002507315146420370015446 0ustar liggesusers#' Stratum positions #' #' Given a dataset with alluvial structure, `stat_stratum` calculates the #' centroids (`x` and `y`) and heights (`ymin` and `ymax`) of the strata at each #' axis. #' @template stat-aesthetics #' @template computed-variables #' @template order-options #' @template defunct-stat-params #' #' @import ggplot2 #' @family alluvial stat layers #' @seealso [ggplot2::layer()] for additional arguments and [geom_stratum()] for #' the corresponding geom. #' @inheritParams ggplot2::layer #' @template layer-params #' @param geom The geometric object to use display the data; override the #' default. #' @param decreasing Logical; whether to arrange the strata at each axis in the #' order of the variable values (`NA`, the default), in ascending order of #' totals (largest on top, `FALSE`), or in descending order of totals (largest #' on bottom, `TRUE`). #' @param reverse Logical; if `decreasing` is `NA`, whether to arrange the #' strata at each axis in the reverse order of the variable values, so that #' they match the order of the values in the legend. Ignored if `decreasing` #' is not `NA`. Defaults to `TRUE`. #' @param absolute Logical; if some cases or strata are negative, whether to #' arrange them (respecting `decreasing` and `reverse`) using negative or #' absolute values of `y`. #' @param discern Passed to [to_lodes_form()] if `data` is in alluvia format. #' @param distill A function (or its name) to be used to distill alluvium values #' to a single lode label, accessible via #' [`ggplot2::after_stat()`][ggplot2::aes_eval] (similar to its behavior in #' [to_alluvia_form()]). It recognizes three character values: `"first"` (the #' default) and `"last"` [as defined][dplyr::nth()] in **dplyr**; and `"most"` #' (which returns the first modal value). #' @param negate.strata A vector of values of the `stratum` aesthetic to be #' treated as negative (will ignore missing values with a warning). #' @param infer.label Logical; whether to assign the `stratum` or `alluvium` #' variable to the `label` aesthetic. Defaults to `FALSE`, and requires that #' no `label` aesthetic is assigned. This parameter is intended for use only #' with data in alluva form, which are converted to lode form before the #' statistical transformation. Deprecated; use #' [`ggplot2::after_stat()`][ggplot2::aes_eval] instead. #' @param label.strata Defunct; alias for `infer.label`. #' @param min.y,max.y Numeric; bounds on the heights of the strata to be #' rendered. Use these bounds to exclude strata outside a certain range, for #' example when labeling strata using [ggplot2::geom_text()]. #' @param min.height,max.height Deprecated aliases for `min.y` and `max.y`. #' @example inst/examples/ex-stat-stratum.r #' @export stat_stratum <- function(mapping = NULL, data = NULL, geom = "stratum", position = "identity", decreasing = NULL, reverse = NULL, absolute = NULL, discern = FALSE, distill = "first", negate.strata = NULL, infer.label = FALSE, label.strata = NULL, min.y = NULL, max.y = NULL, min.height = NULL, max.height = NULL, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ...) { layer( stat = StatStratum, mapping = mapping, data = data, geom = geom, position = position, show.legend = show.legend, inherit.aes = inherit.aes, params = list( decreasing = decreasing, reverse = reverse, absolute = absolute, discern = discern, distill = distill, negate.strata = negate.strata, infer.label = infer.label, label.strata = label.strata, min.y = min.y, max.y = max.y, min.height = min.height, max.height = max.height, na.rm = na.rm, ... ) ) } #' @rdname ggalluvial-ggproto #' @usage NULL #' @export StatStratum <- ggproto( "StatStratum", Stat, required_aes = c("x"), # ` = NULL` prevents "unknown aesthetics" warnings default_aes = aes(weight = 1, stratum = NULL, alluvium = NULL), setup_data = function(data, params) { # if `alluvium` not provided, assign each row its own, grouped by `x` if (is.null(data$alluvium) && ! is.null(data$x)) { data$alluvium <- NA for (xx in unique(data$x)) { ww <- which(data$x == xx) data$alluvium[ww] <- 1:length(ww) } } # assign unit amounts if not provided if (is.null(data$y)) { data$y <- rep(1, nrow(data)) } else { data <- remove_missing( data, na.rm = params$na.rm, vars = "y", name = "stat_stratum", finite = TRUE ) } type <- get_alluvial_type(data) if (type == "none") { stop("Data is not in a recognized alluvial form ", "(see `help('alluvial-data')` for details).") } if (params$na.rm) { data <- na.omit(object = data) } else { data <- na_keep(data = data, type = type) } # ensure that data is in lode form if (type == "alluvia") { axis_ind <- get_axes(names(data)) data <- to_lodes_form(data = data, axes = axis_ind, discern = params$discern) # positioning requires numeric `x` data <- data[with(data, order(x, stratum, alluvium)), , drop = FALSE] data$x <- contiguate(data$x) } else { if (! is.null(params$discern) && ! (params$discern == FALSE)) { warning("Data is already in lodes format, ", "so `discern` will be ignored.") } } # negate strata if (! is.null(params$negate.strata)) { if (! all(params$negate.strata %in% unique(data$stratum))) { warning("Some values of `negate.strata` are not among strata.") } wneg <- which(data$stratum %in% params$negate.strata) if (length(wneg) > 0) data$y[wneg] <- -data$y[wneg] } # nullify `group` and `alluvium` fields (to avoid confusion with geoms) data$group <- NULL #data$alluvium <- NULL data }, compute_panel = function(self, data, scales, decreasing = NULL, reverse = NULL, absolute = NULL, discern = FALSE, distill = "first", negate.strata = NULL, infer.label = FALSE, label.strata = NULL, min.y = NULL, max.y = NULL, min.height = NULL, max.height = NULL) { # parameter defaults if (is.null(decreasing)) decreasing <- ggalluvial_opt("decreasing") if (is.null(reverse)) reverse <- ggalluvial_opt("reverse") if (is.null(absolute)) absolute <- ggalluvial_opt("absolute") # introduce label if (! is.null(label.strata)) { defunct_parameter("label.strata", msg = "use `aes(label = after_stat(stratum))`.") infer.label <- label.strata } if (infer.label) { deprecate_parameter("infer.label", msg = "Use `aes(label = after_stat(stratum))`.") if (is.null(data$label)) { data$label <- data$stratum } else { warning("Aesthetic `label` is specified, ", "so parameter `infer.label` will be ignored.") } } # differentiation aesthetics (in prescribed order) diff_aes <- intersect(c(.color_diff_aesthetics, .text_aesthetics), names(data)) # sign variable (sorts positives before negatives) data$yneg <- data$y < 0 # lode variable (before co-opting 'alluvium') data$lode <- data$alluvium # specify distillation function from `distill` distill <- distill_fun(distill) # initiate variables for `after_stat()` weight <- data$weight data$weight <- NULL if (is.null(weight)) weight <- 1 data$n <- weight data$count <- data$y * weight # aggregate variables over 'x', 'yneg', and 'stratum': # sum of computed variables and unique-or-bust values of aesthetics by_vars <- c("x", "yneg", "stratum") only_vars <- c(diff_aes) sum_vars <- c("y", "n", "count") if (! is.null(data$lode)) { agg_lode <- stats::aggregate(data[, "lode", drop = FALSE], data[, by_vars], distill) } if (length(only_vars) > 0) { agg_only <- stats::aggregate(data[, only_vars, drop = FALSE], data[, by_vars], only) } data <- stats::aggregate(data[, sum_vars], data[, by_vars], sum) if (! is.null(data$lode)) { data <- merge(data, agg_lode) } if (length(only_vars) > 0) { data <- merge(data, agg_only) } # remove empty lodes (including labels) data <- subset(data, y != 0) # define 'deposit' variable to rank strata vertically data <- deposit_data(data, decreasing, reverse, absolute) # calculate variables for `after_stat()` x_sums <- tapply(abs(data$count), data$x, sum, na.rm = TRUE) data$prop <- data$count / x_sums[match(as.character(data$x), names(x_sums))] # sort data in preparation for `y` sums data <- data[with(data, order(deposit)), , drop = FALSE] # calculate `y` sums data$ycum <- NA for (xx in unique(data$x)) { for (yn in c(FALSE, TRUE)) { ww <- which(data$x == xx & data$yneg == yn) data$ycum[ww] <- cumulate(data$y[ww]) } } # calculate y bounds data$ymin <- data$ycum - abs(data$y) / 2 data$ymax <- data$ycum + abs(data$y) / 2 data$y <- data$ycum data$yneg <- NULL data$ycum <- NULL # impose height restrictions if (! is.null(min.height)) { deprecate_parameter("min.height", "min.y") min.y <- min.height } if (! is.null(max.height)) { deprecate_parameter("max.height", "max.y") max.y <- max.height } if (! is.null(min.y)) data <- subset(data, ymax - ymin >= min.y) if (! is.null(max.y)) data <- subset(data, ymax - ymin <= max.y) data } ) # single unique value, or else NA only <- function(x) { uniq <- unique(x) if (length(uniq) == 1L) { uniq } else { switch( class(x), integer = NA_integer_, numeric = NA_real_, character = NA_character_, factor = factor(NA_character_, levels = levels(x)) ) } } ggalluvial/R/devel.r0000644000176200001440000000456214166562215014103 0ustar liggesusers deprecate_parameter <- function(old, new = NA, type = "parameter", msg = NULL) { .Deprecated(msg = paste0( "The ", type, " `", old, "` is deprecated.", if (is.null(new)) { "\nPass unparameterized arguments instead." } else if (! is.na(new)) { paste0("\nPass arguments to `", new, "` instead.") } else if (! is.null(msg)) { paste0("\n", msg) } else { "" } )) } defunct_parameter <- function(old, new = NA, type = "parameter", msg = NULL) { .Defunct(msg = paste0( "The ", type, " `", old, "` is defunct.", if (is.null(new)) { "\nPass unparameterized arguments instead." } else if (! is.na(new)) { paste0("\nPass arguments to `", new, "` instead.") } else if (! is.null(msg)) { paste0("\n", msg) } else { "" } )) } release_questions <- function() { c( "Have previous CRAN NOTEs been addressed?" ) } #' Deprecated functions #' #' These functions are deprecated in the current version and may be removed in a #' future version. #' #' Use `is_*_form` instead of `is_alluvial` and `is_alluvial_*`. #' Use `to_*_form` instead of `to_*`. #' #' @name ggalluvial-deprecated #' @keywords internal NULL #' @rdname ggalluvial-deprecated #' @export is_alluvial <- function(data, ..., silent = FALSE) { .Deprecated(msg = paste0( "The function `is_alluvial()` is deprecated; ", "use `is_lodes_form()` or `is_alluvia_form()`." )) # determine method based on arguments given dots <- lazyeval::lazy_dots(...) if (! is.null(dots$key) | ! is.null(dots$value) | ! is.null(dots$id)) { if (! is.null(dots$axes)) { stop("Arguments to `key`, `value`, and `id` are mutually exclusive ", "with an argument to `axes`.") } is_lodes_form(data = data, ..., silent = silent) } else { is_alluvia_form(data = data, ..., silent = silent) } } #' @rdname ggalluvial-deprecated #' @export is_alluvial_lodes <- function(...) { .Deprecated("is_lodes_form") is_lodes_form(...) } #' @rdname ggalluvial-deprecated #' @export is_alluvial_alluvia <- function(...) { .Deprecated("is_alluvia_form") is_alluvia_form(...) } #' @rdname ggalluvial-deprecated #' @export to_lodes <- function(...) { .Deprecated("to_lodes_form") to_lodes_form(...) } #' @rdname ggalluvial-deprecated #' @export to_alluvia <- function(...) { .Deprecated("to_alluvia_form") to_alluvia_form(...) } ggalluvial/R/data.r0000644000176200001440000000313214112432105013666 0ustar liggesusers#' Influenza vaccination survey responses #' #' This data set is aggregated from three RAND American Life Panel (ALP) surveys #' that asked respondents their probability of vaccinating for influenza. Their #' responses were discretized to "Never" (0%), "Always" (100%), or "Sometimes" #' (any other value). After merging, missing responses were coded as "Missing" #' and respondents were grouped and counted by all three coded responses. The #' pre-processed data were kindly contributed by Raffaele Vardavas, and the #' complete surveys are freely available at the ALP website. #' #' @keywords datasets #' @format A data frame with 117 rows and 5 variables: #' \describe{ #' \item{`freq`}{number of respondents represented in each row} #' \item{`subject`}{identifier linking respondents across surveys} #' \item{`survey`}{survey designation from the ALP website} #' \item{`start_date`}{start date of survey} #' \item{`end_date`}{end date of survey} #' \item{`response`}{discretized probability of vaccinating for influenza} #' } #' @source \url{https://alpdata.rand.org/} "vaccinations" #' Students' declared majors across several semesters #' #' This data set follows the major curricula of 10 students across 8 academic #' semesters. Missing values indicate undeclared majors. The data were kindly #' contributed by Dario Bonaretti. #' #' @name majors #' @keywords datasets #' @format A data frame with 80 rows and 3 variables: #' \describe{ #' \item{`student`}{student identifier} #' \item{`semester`}{character tag for odd-numbered semesters} #' \item{`curriculum`}{declared major program} #' } NULL ggalluvial/R/stat-alluvium.r0000755000176200001440000004216115146420370015605 0ustar liggesusers#' Alluvial positions #' #' Given a dataset with alluvial structure, `stat_alluvium` calculates the #' centroids (`x` and `y`) and heights (`ymin` and `ymax`) of the lodes, the #' intersections of the alluvia with the strata. It leverages the `group` #' aesthetic for plotting purposes (for now). #' @template stat-aesthetics #' @template computed-variables #' @template order-options #' @template defunct-stat-params #' #' @import ggplot2 #' @importFrom rlang .data #' @family alluvial stat layers #' @seealso [ggplot2::layer()] for additional arguments and [geom_alluvium()], #' [geom_lode()], and [geom_flow()] for the corresponding geoms. #' @inheritParams stat_flow #' @param cement.alluvia Logical value indicating whether to aggregate `y` #' values over equivalent alluvia before computing lode and flow positions. #' @param aggregate.y Deprecated alias for `cement.alluvia`. #' @param lode.guidance The function to prioritize the axis variables for #' ordering the lodes within each stratum, or else a character string #' identifying the function. Character options are "zigzag", "frontback", #' "backfront", "forward", and "backward" (see [`lode-guidance-functions`]). #' @param lode.ordering **Deprecated in favor of the `order` aesthetic.** A list #' (of length the number of axes) of integer vectors (each of length the #' number of rows of `data`) or NULL entries (indicating no imposed ordering), #' or else a numeric matrix of corresponding dimensions, giving the preferred #' ordering of alluvia at each axis. This will be used to order the lodes #' within each stratum by sorting the lodes first by stratum, then by the #' provided vectors, and lastly by remaining factors (if the vectors contain #' duplicate entries and therefore do not completely determine the lode #' orderings). #' @example inst/examples/ex-stat-alluvium.r #' @export stat_alluvium <- function(mapping = NULL, data = NULL, geom = "alluvium", position = "identity", decreasing = NULL, reverse = NULL, absolute = NULL, discern = FALSE, negate.strata = NULL, aggregate.y = NULL, cement.alluvia = NULL, lode.guidance = NULL, lode.ordering = NULL, aes.bind = NULL, infer.label = FALSE, min.y = NULL, max.y = NULL, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ...) { layer( stat = StatAlluvium, data = data, mapping = mapping, geom = geom, position = position, show.legend = show.legend, inherit.aes = inherit.aes, params = list( decreasing = decreasing, reverse = reverse, absolute = absolute, discern = discern, negate.strata = negate.strata, aggregate.y = aggregate.y, cement.alluvia = cement.alluvia, lode.guidance = lode.guidance, lode.ordering = lode.ordering, aes.bind = aes.bind, infer.label = infer.label, min.y = min.y, max.y = max.y, na.rm = na.rm, ... ) ) } #' @rdname ggalluvial-ggproto #' @usage NULL #' @export StatAlluvium <- ggproto( "StatAlluvium", Stat, required_aes = c("x"), # ` = NULL` prevents "unknown aesthetics" warnings default_aes = aes(weight = 1, stratum = NULL, alluvium = NULL), setup_params = function(data, params) { if (! is.null(params$lode.ordering)) { if (is.list(params$lode.ordering)) { # replace any null entries with uniform `NA` vectors wh_null <- which(sapply(params$lode.ordering, is.null)) len <- unique(sapply(params$lode.ordering[wh_null], length)) if (length(len) > 1) stop("Lode orderings have different lengths.") for (w in wh_null) params$lode.ordering[[w]] <- rep(NA, len) # convert list to array (requires equal-length numeric entries) params$lode.ordering <- do.call(cbind, params$lode.ordering) } } # remove null parameter values (see #103) params[vapply(params, is.null, NA)] <- NULL params }, setup_data = function(data, params) { # assign `alluvium` to `stratum` if `stratum` not provided if (is.null(data$stratum) && ! is.null(data$alluvium)) { data$stratum <- data$alluvium } # assign unit amounts if not provided if (is.null(data$y)) { data$y <- rep(1, nrow(data)) } else { data <- remove_missing( data, na.rm = params$na.rm, vars = "y", name = "stat_alluvium", finite = TRUE ) } type <- get_alluvial_type(data) if (type == "none") { stop("Data is not in a recognized alluvial form ", "(see `help('alluvial-data')` for details).") } if (params$na.rm) { data <- na.omit(object = data) } else { data <- na_keep(data = data, type = type) } # ensure that data is in lode form if (type == "alluvia") { axis_ind <- get_axes(names(data)) data <- to_lodes_form(data = data, axes = axis_ind, discern = params$discern) # positioning requires numeric `x` data <- data[with(data, order(x, stratum, alluvium)), , drop = FALSE] data$x <- contiguate(data$x) } else { if (! is.null(params$discern) && ! (params$discern == FALSE)) { warning("Data is already in lodes format, ", "so `discern` will be ignored.") } } # negate strata if (! is.null(params$negate.strata)) { if (! all(params$negate.strata %in% unique(data$stratum))) { warning("Some values of `negate.strata` are not among strata.") } wneg <- which(data$stratum %in% params$negate.strata) if (length(wneg) > 0) data$y[wneg] <- -data$y[wneg] } data }, compute_panel = function(data, scales, decreasing = NULL, reverse = NULL, absolute = NULL, discern = FALSE, distill = "first", negate.strata = NULL, aggregate.y = NULL, cement.alluvia = NULL, lode.guidance = NULL, lode.ordering = NULL, aes.bind = NULL, infer.label = FALSE, min.y = NULL, max.y = NULL) { # parameter defaults if (is.null(decreasing)) decreasing <- ggalluvial_opt("decreasing") if (is.null(reverse)) reverse <- ggalluvial_opt("reverse") if (is.null(absolute)) absolute <- ggalluvial_opt("absolute") if (is.null(cement.alluvia)) cement.alluvia <- ggalluvial_opt("cement.alluvia") if (is.null(lode.guidance)) lode.guidance <- ggalluvial_opt("lode.guidance") if (is.null(aes.bind)) aes.bind <- ggalluvial_opt("aes.bind") # introduce label if (infer.label) { deprecate_parameter("infer.label", msg = "Use `aes(label = after_stat(lode))`.") if (is.null(data$label)) { data$label <- data$alluvium } else { warning("Aesthetic `label` is specified, ", "so parameter `infer.label` will be ignored.") } } # ensure that `lode.ordering` is a matrix with column names if (! is.null(lode.ordering)) { deprecate_parameter("lode.ordering", msg = "Use the `order` aesthetic instead.") if (is.null(data$order)) { # bind a vector to itself to create a matrix if (is.vector(lode.ordering)) { lode.ordering <- matrix(lode.ordering, nrow = length(lode.ordering), ncol = length(unique(data$x))) } # flatten `lode.ordering` into an 'order' column data$order <- as.vector(lode.ordering) } else { warning("Aesthetic `order` is specified, ", "so parameter `lode.ordering` will be ignored.") } } # differentiation aesthetics (in prescribed order) diff_aes <- intersect(c(.color_diff_aesthetics, .text_aesthetics), names(data)) # match arguments for `aes.bind` if (! is.null(aes.bind)) { if (is.logical(aes.bind)) { aes.bind.rep <- if (aes.bind) "flows" else "none" warning("Logical values of `aes.bind` are deprecated; ", "replacing ", aes.bind, " with '", aes.bind.rep, "'.") aes.bind <- aes.bind.rep } aes.bind <- match.arg(aes.bind, c("none", "flows", "alluvia")) } # sign variable (sorts positives before negatives) data$yneg <- data$y < 0 # lode variable (before co-opting 'alluvium') data$lode <- data$alluvium # specify distillation function from `distill` distill <- distill_fun(distill) # initiate variables for `after_stat()` weight <- data$weight data$weight <- NULL if (is.null(weight)) weight <- 1 data$n <- weight data$count <- data$y * weight # transform 'order' according to `absolute` and `reverse` params if (! is.null(data$order)) data$order <- xtfrm(data$order) * (-1) ^ (data$yneg * absolute + reverse) # cement (aggregate) `y` over otherwise equivalent alluvia if (! is.null(aggregate.y)) { deprecate_parameter("aggregate.y", "cement.alluvia") cement.alluvia <- aggregate.y } if (cement.alluvia) { # -+- need to stop depending on 'group' and 'PANEL' -+- only_vars <- intersect(c(diff_aes, "group", "PANEL"), names(data)) bind_vars <- intersect(c("yneg", "stratum", only_vars), names(data)) sum_vars <- c("y", "n", "count") # interaction of all variables to aggregate over (without dropping NAs) # -+- need to stop depending on 'group' -+- data$binding <- as.numeric(interaction(lapply( data[, bind_vars, drop = FALSE], addNA, ifany = FALSE ), drop = TRUE)) # convert to alluvia format with 'binding' entries luv_dat <- alluviate(data, "x", "binding", "alluvium") # sort by all axes (everything except 'alluvium') luv_dat <- luv_dat[do.call( order, luv_dat[, setdiff(names(luv_dat), "alluvium"), drop = FALSE] ), , drop = FALSE] # define map from original to aggregated 'alluvium' column luv_orig <- luv_dat$alluvium luv_agg <- cumsum(! duplicated(interaction( luv_dat[, setdiff(names(luv_dat), "alluvium"), drop = FALSE], drop = TRUE ))) # transform 'alluvium' in `data` accordingly data$alluvium <- luv_agg[match(data$alluvium, luv_orig)] # aggregate variables over 'x', 'yneg', and 'stratum': # sum of computed variables and unique-or-bust values of aesthetics by_vars <- c("x", "yneg", "stratum", "alluvium", "binding") agg_lode <- stats::aggregate(data[, "lode", drop = FALSE], data[, by_vars], distill) if (length(only_vars) > 0) { agg_only <- stats::aggregate(data[, only_vars, drop = FALSE], data[, by_vars], only) } agg_dat <- stats::aggregate(data[, sum_vars], data[, by_vars], sum) agg_dat <- merge(agg_dat, agg_lode) if (length(only_vars) > 0) { agg_dat <- merge(agg_dat, agg_only) } # merge into `data`, ensuring that no `key`-`id` pairs are duplicated data <- unique(merge( agg_dat, data[, setdiff(names(data), sum_vars)], all.x = TRUE, all.y = FALSE )) data$binding <- NULL } # define 'deposit' variable to rank strata vertically data <- deposit_data(data, decreasing, reverse, absolute) # ensure that `lode.guidance` is a function if (is.character(lode.guidance)) { lode.guidance <- get(paste0("lode_", lode.guidance)) } stopifnot(is.function(lode.guidance)) # invoke surrounding axes in the order prescribed by `lode.guidance` lode_ord <- guide_lodes(data, lode.guidance) # convert `lode_ord` into a single sorting variable 'rem_deposit' # that orders index lodes by remaining / remote deposits names(lode_ord) <- sort(unique(data$x)) lode_ord$alluvium <- if (is.null(rownames(lode_ord))) { if (is.factor(data$alluvium)) { levels(data$alluvium) } else if (is.numeric(data$alluvium)) { sort(unique(data$alluvium)) } else { unique(data$alluvium) } } else { rownames(lode_ord) } # match `lode_ord$x` back to `data$x` uniq_x <- sort(unique(data$x)) lode_ord <- tidyr::gather(lode_ord, key = "x", value = "rem_deposit", as.character(uniq_x)) match_x <- match(lode_ord$x, as.character(uniq_x)) lode_ord$x <- uniq_x[match_x] # merge `lode_ord` back into `data` data <- merge(data, lode_ord, by = c("x", "alluvium"), all.x = TRUE, all.y = FALSE) # identify fissures at aesthetics that vary within strata n_lodes <- nrow(unique(data[, c("x", "stratum")])) fissure_aes <- diff_aes[which(sapply(diff_aes, function(x) { nrow(unique(data[, c("x", "stratum", x)])) }) > n_lodes)] data$fissure <- if (length(fissure_aes) == 0) { 1 } else { # order by aesthetics in order as.integer(interaction(data[, rev(fissure_aes)], drop = TRUE)) * (-1) ^ (data$yneg * absolute + reverse) } # calculate variables for `after_stat()` x_sums <- tapply(abs(data$count), data$x, sum, na.rm = TRUE) data$prop <- data$count / x_sums[match(as.character(data$x), names(x_sums))] # reverse alluvium order data$fan <- xtfrm(data$alluvium) * (-1) ^ reverse # sort data in preparation for `y` sums sort_fields <- c( "x", "deposit", if (! is.null(data$order)) "order", if (aes.bind == "alluvia") "fissure", "rem_deposit", if (aes.bind == "flows") "fissure", "fan" ) data <- data[do.call(order, data[, sort_fields]), , drop = FALSE] # calculate `y` sums data$ycum <- NA for (xx in unique(data$x)) { for (yn in c(FALSE, TRUE)) { ww <- which(data$x == xx & data$yneg == yn) data$ycum[ww] <- cumulate(data$y[ww]) } } # calculate y bounds data$rem_deposit <- NULL data$order <- NULL data$fissure <- NULL data$fan <- NULL data$ymin <- data$ycum - abs(data$y) / 2 data$ymax <- data$ycum + abs(data$y) / 2 data$y <- data$ycum data$yneg <- NULL data$ycum <- NULL # within each alluvium, indices at which subsets are contiguous data <- data[with(data, order(x, alluvium)), , drop = FALSE] data$cont <- duplicated(data$alluvium) & ! duplicated(data[, c("x", "alluvium")]) data$axis <- contiguate(data$x) # within each alluvium, group contiguous subsets # (data is sorted by `x` and `alluvium`; group_by() does not reorder it) data <- dplyr::ungroup(dplyr::mutate(dplyr::group_by(data, alluvium), flow = axis - cumsum(cont))) # add 'group' to group contiguous alluvial subsets data <- transform(data, group = as.numeric(interaction(alluvium, flow))) # remove unused fields data$cont <- NULL data$axis <- NULL data$flow <- NULL # impose height restrictions if (! is.null(min.y)) data <- subset(data, ymax - ymin >= min.y) if (! is.null(max.y)) data <- subset(data, ymax - ymin <= max.y) # arrange data by aesthetics for consistent (reverse) z-ordering data <- z_order_aes(data, diff_aes) data } ) # apply lode guidance function to produce ordering matrix guide_lodes <- function(data, guidance_fun) { # summary data of alluvial deposits alluv_dep <- alluviate(data, "x", "deposit", "alluvium") # axis indices alluv_x <- setdiff(names(alluv_dep), "alluvium") # initialize ordering matrix ord_mat <- matrix(NA_integer_, nrow = nrow(alluv_dep), ncol = length(alluv_x)) dimnames(ord_mat) <- list(alluv_dep$alluvium, alluv_x) # calculate orderings from `guidance_fun` for (xx in alluv_x) { ii <- match(xx, alluv_x) ord_x <- guidance_fun(length(alluv_x), match(xx, alluv_x)) # order by prescribed ordering and by aesthetics in order ord_mat[, xx] <- interaction(alluv_dep[, alluv_x[rev(ord_x)]], drop = TRUE) } # check that array has correct dimensions stopifnot(dim(ord_mat) == c(length(unique(data$alluvium)), length(unique(data$x)))) # return ordering matrix as a data aframe as.data.frame(ord_mat) } # build alluvial dataset for reference during lode-ordering alluviate <- function(data, key, value, id) { to_alluvia_form( data[, c(key, value, id), drop = FALSE], key = key, value = value, id = id ) } ggalluvial/R/geom-stratum.r0000644000176200001440000000462315146420370015420 0ustar liggesusers#' Strata at axes #' #' `geom_stratum` receives a dataset of the horizontal (`x`) and vertical (`y`, #' `ymin`, `ymax`) positions of the strata of an alluvial plot. It plots #' rectangles for these strata of a provided `width`. #' @template geom-aesthetics #' @template defunct-geom-params #' #' @import ggplot2 #' @family alluvial geom layers #' @seealso [ggplot2::layer()] for additional arguments and #' [stat_stratum()] for the corresponding stat. #' @inheritParams geom_lode #' @example inst/examples/ex-geom-stratum.r #' @export geom_stratum <- function(mapping = NULL, data = NULL, stat = "stratum", position = "identity", show.legend = NA, inherit.aes = TRUE, width = 1/3, na.rm = FALSE, ...) { layer( geom = GeomStratum, mapping = mapping, data = data, stat = stat, position = position, show.legend = show.legend, inherit.aes = inherit.aes, params = list( width = width, na.rm = na.rm, ... ) ) } #' @rdname ggalluvial-ggproto #' @usage NULL #' @export GeomStratum <- ggproto( "GeomStratum", GeomRect, required_aes = c("x", "y", "ymin", "ymax"), default_aes = aes(size = .5, linewidth = .5, linetype = 1, colour = "black", fill = "white", alpha = 1), setup_data = function(data, params) { width <- params$width if (is.null(width)) width <- 1/3 transform(data, xmin = x - width / 2, xmax = x + width / 2) }, draw_panel = function(self, data, panel_params, coord, width = 1/3) { # taken from GeomRect strat_aes <- setdiff( names(data), c("x", "y", "xmin", "xmax", "ymin", "ymax") ) # construct polygon grobs polys <- lapply(split(data, seq_len(nrow(data))), function(row) { poly <- rect_to_poly(row$xmin, row$xmax, row$ymin, row$ymax) aes <- as.data.frame(row[strat_aes], stringsAsFactors = FALSE)[rep(1, 5), ] GeomPolygon$draw_panel(cbind(poly, aes, group = 1), panel_params, coord) }) # combine polygon grobs grob <- do.call(grid::grobTree, polys) grob$name <- grid::grobName(grob, "geom_stratum") grob }, draw_key = draw_key_polygon ) ggalluvial/R/geom-utils.r0000644000176200001440000000326314112432105015047 0ustar liggesusers# convert rectangle to polygon # (lifted from [ggplot2::geom_rect()]) rect_to_poly <- function(xmin, xmax, ymin, ymax) { data.frame( y = c(ymax, ymax, ymin, ymin, ymax), x = c(xmin, xmax, xmax, xmin, xmin) ) } # alternative curve options # each is a function that takes [0,1] to [0,1] # degree-3 polynomial with degree-1 critical endpoints unit_cubic <- function(x) 3*x^2 - 2*x^3 # degree-5 polynomial with degree-2 critical endpoints unit_quintic <- function(x) 10*x^3 - 15*x^4 + 6*x^5 # sinusoidal function with crests at endpoints unit_sine <- function(x) { t <- (x - .5) * pi sin(t) / 2 + .5 } # inverse tangent function compressed from a specified symmetric domain unit_arctangent <- function(x, curve_range) { if (is.na(curve_range)) curve_range <- 2 + sqrt(3) t <- (x - .5) * 2 * curve_range atan(t) / 2 / atan(curve_range) + .5 } # sigmoid function compressed from a specified symmetric domain unit_sigmoid <- function(x, curve_range) { if (is.na(curve_range)) curve_range <- 6 t <- (x - .5) * 2 * curve_range (stats::plogis(t) - stats::plogis(-curve_range)) / diff(stats::plogis(c(-1, 1) * curve_range)) } # return the desired flow curve function make_curve_fun <- function(curve_type, curve_range) { curve_type <- match.arg( curve_type, c("linear", "cubic", "quintic", "sine", "arctangent", "sigmoid") ) switch( curve_type, # polynomial curves linear = identity, cubic = unit_cubic, quintic = unit_quintic, # sinusoidal curve sine = unit_sine, # asymptotic curves (compressed from a specifiable range) arctangent = function(x) unit_arctangent(x, curve_range), sigmoid = function(x) unit_sigmoid(x, curve_range) ) } ggalluvial/R/utils.r0000644000176200001440000000066614371220124014131 0ustar liggesusers# color and differentiation aesthetics .color_diff_aesthetics <- c( "fill", "bg", "alpha", "fg", "col", "colour", "color", "lty", "linetype", "cex", "lwd", "linewidth", "size", "pch", "shape" ) # text aesthetics .text_aesthetics <- c( "label", "vjust", "hjust", "angle", "family", "fontface", "lineheight" ) # distilling functions most <- function(x) { x[which(factor(x) == names(which.max(table(factor(x)))))[1]] } ggalluvial/R/stat-utils.r0000644000176200001440000001050115042736161015100 0ustar liggesusers# Identify elements in a character vector that fit the pattern of axis aesthetic # names, and return their indices in the numerical order of the axis numbers # (with `axis` first, if present). Only non-negative integers are allowed. get_axes <- function(x) { if (anyDuplicated(x)) { dupes <- unique(x[duplicated(x)]) stop("Duplicated variables: ", paste(dupes, collapse = ", ")) } axis_ind <- grep("^axis[0-9]*$", x) axis_ind[order(as.numeric(gsub("^axis", "", x[axis_ind])), na.last = FALSE)] } get_alluvial_type <- function(data) { # ensure that data is alluvial if (!is.null(data$x) | !is.null(data$stratum) | !is.null(data$alluvium)) { if (is.null(data$x) | is.null(data$stratum) | is.null(data$alluvium)) { stop("Parameters `x`, `stratum`, and `alluvium` are required ", "for data in lodes form.") } if (is_lodes_form(data, key = "x", value = "stratum", id = "alluvium", weight = "y", site = if ("PANEL" %in% names(data)) "PANEL", silent = TRUE)) return("lodes") } else { axis_ind <- get_axes(names(data)) if (is_alluvia_form(data, axes = axis_ind, weight = "y", silent = TRUE)) return("alluvia") } return("none") } # incorporate any missing values into factor levels na_keep <- function(data, type) { if (type == "lodes") { if (is.factor(data$stratum)) { data$stratum <- addNA(data$stratum, ifany = TRUE) } else { data$stratum[is.na(data$stratum)] <- "" } } else if (type == "alluvia") { axis_ind <- get_axes(names(data)) for (i in axis_ind) { if (any(is.na(data[[i]]))) { if (is.factor(data[[i]])) { data[[i]] <- addNA(data[[i]], ifany = TRUE) } else { data[[i]][is.na(data[[i]])] <- "" } } } } data } # replace a vector `x` of any type with # a numeric vector of *contiguous* integers that sort in the same order as `x` contiguate <- function(x) { x <- xtfrm(x) match(x, sort(unique(x))) } # define 'deposit' variable to rank strata vertically deposit_data <- function(data, decreasing, reverse, absolute) { if (is.na(decreasing)) { deposits <- unique(data[, c("x", "yneg", "stratum"), drop = FALSE]) deposits$deposit <- order(order( deposits$x, -deposits$yneg, xtfrm(deposits$stratum) * (-1) ^ (deposits$yneg * absolute + reverse) )) } else { deposits <- stats::aggregate( x = data$y, by = data[, c("x", "yneg", "stratum"), drop = FALSE], FUN = sum ) names(deposits)[ncol(deposits)] <- "y" deposits$deposit <- order(order( deposits$x, -deposits$yneg, xtfrm(deposits$y) * (-1) ^ (deposits$yneg * absolute + decreasing), xtfrm(deposits$stratum) * (-1) ^ (deposits$yneg * absolute + reverse) )) deposits$y <- NULL } merge(data, deposits, all.x = TRUE, all.y = FALSE) } # calculate cumulative 'y' values, accounting for sign cumulate <- function(x) { if (length(x) == 0) return(x) if (all(x == 0)) return(rep(0, length(x))) s <- setdiff(unique(sign(x)), 0) stopifnot(length(s) == 1 && s %in% c(-1, 1)) if (s == 1) { cumsum(x) - x / 2 } else { rev(cumsum(rev(x)) - rev(x) / 2) } } # choose a function via the `cement` parameter distill_vals <- c("first", "last", "most") distill_fun <- function(distill) { if (is.function(distill)) { return(distill) } else if (distill %in% distill_vals) { return(switch( distill, first = dplyr::first, last = dplyr::last, most = most )) } else if (is.character(distill)) { return(get(distill)) } else { stop("Please pass either a function or its name to `distill`.") } } # arrange data by aesthetics for consistent (reverse) z-ordering z_order_aes <- function(data, aesthetics) { # `aesthetics` and 'group' are fixed within contiguous alluvial segments aes_data <- data[! duplicated(data[, c("alluvium", "group"), drop = FALSE]), c("alluvium", aesthetics, "group")] if (length(aes_data) == 2) return(data) aes_data <- aes_data[do.call(order, aes_data[, c(aesthetics, "alluvium")]), ] # ensure order of "group" respects aesthetics data$group <- match(data$group, unique(aes_data$group)) data[with(data, order(x, group)), , drop = FALSE] } ggalluvial/R/geom-lode.r0000644000176200001440000000531315146420370014641 0ustar liggesusers#' Lodes at intersections of alluvia and strata #' #' `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 rectangles for these #' lodes of a provided `width`. #' @template geom-aesthetics #' @template defunct-geom-params #' #' @import ggplot2 #' @family alluvial geom layers #' @seealso [ggplot2::layer()] for additional arguments and #' [stat_alluvium()] and #' [stat_stratum()] for the corresponding stats. #' @inheritParams ggplot2::layer #' @template layer-params #' @param stat The statistical transformation to use on the data; #' override the default. #' @param width Numeric; the width of each stratum, as a proportion of the #' distance between axes. Defaults to 1/3. #' @example inst/examples/ex-geom-lode.r #' @export geom_lode <- function(mapping = NULL, data = NULL, stat = "alluvium", position = "identity", width = 1/3, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ...) { layer( geom = GeomLode, mapping = mapping, data = data, stat = stat, position = position, show.legend = show.legend, inherit.aes = inherit.aes, params = list( width = width, na.rm = na.rm, ... ) ) } #' @rdname ggalluvial-ggproto #' @usage NULL #' @export GeomLode <- ggproto( "GeomLode", Geom, required_aes = c("x", "y", "ymin", "ymax"), default_aes = aes(size = .5, linewidth = .5, linetype = 1, colour = "transparent", fill = "gray", alpha = .5), setup_data = function(data, params) { width <- params$width if (is.null(width)) width <- 1/3 transform(data, xmin = x - width / 2, xmax = x + width / 2) }, draw_panel = function(data, panel_params, coord, width = 1/3) { # taken from GeomRect lode_aes <- setdiff( names(data), c("x", "y", "xmin", "xmax", "ymin", "ymax") ) # construct polygon grobs polys <- lapply(split(data, seq_len(nrow(data))), function(row) { poly <- rect_to_poly(row$xmin, row$xmax, row$ymin, row$ymax) aes <- as.data.frame(row[lode_aes], stringsAsFactors = FALSE)[rep(1, 5), ] GeomPolygon$draw_panel(cbind(poly, aes, group = 1), panel_params, coord) }) # combine polygon grobs grob <- do.call(grid::grobTree, polys) grob$name <- grid::grobName(grob, "geom_lode") grob }, draw_key = draw_key_polygon ) ggalluvial/R/ggalluvial-package.r0000644000176200001440000000206214341153260016504 0ustar liggesusers#' @keywords internal #' #' @section Acknowledgments: #' #' Many users identified problems and suggested improvements via email and the #' GitHub issue tracker. #' #' Development benefitted from the use of equipment and the support of #' colleagues at [UConn Health](https://health.uconn.edu/) and at [UF #' Health](https://ufhealth.org/). #' "_PACKAGE" #' @importFrom rlang "%||%" # stratum and lode ordering options are documented in the `stat_*()` topics # curve options are documented in the `geom_*()` topics op.ggalluvial <- list( # stratum and lode ordering ggalluvial.decreasing = NA, ggalluvial.reverse = TRUE, ggalluvial.absolute = TRUE, ggalluvial.cement.alluvia = FALSE, ggalluvial.lode.guidance = "zigzag", ggalluvial.aes.bind = "none", # curves ggalluvial.curve_type = "xspline", ggalluvial.curve_range = NA_real_, ggalluvial.segments = 48L ) ggalluvial_opt <- function(x) { x_ggalluvial <- paste0("ggalluvial.", x) res <- getOption(x_ggalluvial) if (! is.null(res)) { return(res) } op.ggalluvial[[x_ggalluvial]] } ggalluvial/R/stat-flow.r0000644000176200001440000003037015146420370014712 0ustar liggesusers#' Flow positions #' #' Given a dataset with alluvial structure, `stat_flow` calculates the centroids #' (`x` and `y`) and heights (`ymin` and `ymax`) of the flows between each pair #' of adjacent axes. #' @template stat-aesthetics #' @template computed-variables #' @template order-options #' @template defunct-stat-params #' #' @import ggplot2 #' @family alluvial stat layers #' @seealso [ggplot2::layer()] for additional arguments and #' [geom_alluvium()] and #' [geom_flow()] for the corresponding geoms. #' @inheritParams stat_stratum #' @param aes.bind At what grouping level, if any, to prioritize differentiation #' aesthetics when ordering the lodes within each stratum. Defaults to #' `"none"` (no aesthetic binding) with intermediate option `"flows"` to bind #' aesthetics after stratifying by axes linked to the index axis (the one #' adjacent axis in `stat_flow()`; all remaining axes in `stat_alluvium()`) #' and strongest option `"alluvia"` to bind aesthetics after stratifying by #' the index axis but before stratifying by linked axes (only available for #' `stat_alluvium()`). Stratification by any axis is done with respect to the #' strata at that axis, after separating positive and negative strata, #' consistent with the values of `decreasing`, `reverse`, and `absolute`. #' Thus, if `"none"`, then lode orderings will not depend on aesthetic #' variables. All aesthetic variables are used, in the order in which they are #' specified in `aes()`. #' @example inst/examples/ex-stat-flow.r #' @export stat_flow <- function(mapping = NULL, data = NULL, geom = "flow", position = "identity", decreasing = NULL, reverse = NULL, absolute = NULL, discern = FALSE, negate.strata = NULL, aes.bind = NULL, infer.label = FALSE, min.y = NULL, max.y = NULL, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ...) { layer( stat = StatFlow, data = data, mapping = mapping, geom = geom, position = position, show.legend = show.legend, inherit.aes = inherit.aes, params = list( decreasing = decreasing, reverse = reverse, absolute = absolute, discern = discern, negate.strata = negate.strata, aes.bind = aes.bind, infer.label = infer.label, min.y = min.y, max.y = max.y, na.rm = na.rm, ... ) ) } #' @rdname ggalluvial-ggproto #' @usage NULL #' @export StatFlow <- ggproto( "StatFlow", Stat, required_aes = c("x"), optional_aes = c("order"), # ` = NULL` prevents "unknown aesthetics" warnings default_aes = aes(weight = 1, stratum = NULL, alluvium = NULL, order = NULL), setup_params = function(data, params) { # remove null parameter values (see #103) params[vapply(params, is.null, NA)] <- NULL params }, setup_data = function(data, params) { # assign `alluvium` to `stratum` if `stratum` not provided if (is.null(data$stratum) && ! is.null(data$alluvium)) { data$stratum <- data$alluvium } # assign unit amounts if not provided if (is.null(data$y)) { data$y <- rep(1, nrow(data)) } else { data <- remove_missing( data, na.rm = params$na.rm, vars = "y", name = "stat_flow", finite = TRUE ) } type <- get_alluvial_type(data) if (type == "none") { stop("Data is not in a recognized alluvial form ", "(see `help('alluvial-data')` for details).") } if (params$na.rm) { data <- na.omit(object = data) } else { data <- na_keep(data = data, type = type) } # ensure that data is in lode form if (type == "alluvia") { axis_ind <- get_axes(names(data)) data <- to_lodes_form(data = data, axes = axis_ind, discern = params$discern) # positioning requires numeric `x` data <- data[with(data, order(x, stratum, alluvium)), , drop = FALSE] data$x <- contiguate(data$x) } else { if (! is.null(params$discern) && ! (params$discern == FALSE)) { warning("Data is already in lodes format, ", "so `discern` will be ignored.") } } # negate strata if (! is.null(params$negate.strata)) { if (! all(params$negate.strata %in% unique(data$stratum))) { warning("Some values of `negate.strata` are not among strata.") } wneg <- which(data$stratum %in% params$negate.strata) if (length(wneg) > 0) data$y[wneg] <- -data$y[wneg] } data }, compute_panel = function(self, data, scales, decreasing = NULL, reverse = NULL, absolute = NULL, discern = FALSE, distill = "first", negate.strata = NULL, aes.bind = NULL, infer.label = FALSE, min.y = NULL, max.y = NULL) { # parameter defaults if (is.null(decreasing)) decreasing <- ggalluvial_opt("decreasing") if (is.null(reverse)) reverse <- ggalluvial_opt("reverse") if (is.null(absolute)) absolute <- ggalluvial_opt("absolute") if (is.null(aes.bind)) aes.bind <- ggalluvial_opt("aes.bind") # introduce label if (infer.label) { deprecate_parameter("infer.label", msg = "Use `aes(label = after_stat(lode))`.") if (is.null(data$label)) { data$label <- data$alluvium } else { warning("Aesthetic `label` is specified, ", "so parameter `infer.label` will be ignored.") } } # differentiation and text aesthetics (in prescribed order) diff_aes <- intersect(c(.color_diff_aesthetics, .text_aesthetics), names(data)) # match arguments for `aes.bind` if (! is.null(aes.bind)) { if (is.logical(aes.bind)) { aes.bind.rep <- if (aes.bind) "flow" else "none" warning("Logical values of `aes.bind` are deprecated; ", "replacing ", aes.bind, " with '", aes.bind.rep, "'.") aes.bind <- aes.bind.rep } aes.bind <- match.arg(aes.bind, c("none", "flows", "alluvia")) if (aes.bind == "alluvia") { warning("`aes.bind = 'alluvia'` only available for `geom_alluvium()`; ", "changing to 'flows'.") aes.bind <- "flows" } } # sign variable (sorts positives before negatives) data$yneg <- data$y < 0 # lode variable (before co-opting 'alluvium') data$lode <- data$alluvium # specify distillation function from `distill` distill <- distill_fun(distill) # transform 'order' according to `absolute` and `reverse` params if (! is.null(data$order)) data$order <- xtfrm(data$order) * (-1) ^ (data$yneg * absolute + reverse) # define 'deposit' variable to rank strata vertically data <- deposit_data(data, decreasing, reverse, absolute) # identify fissures at aesthetics that vary within strata n_lodes <- nrow(unique(data[, c("x", "stratum")])) fissure_aes <- diff_aes[which(sapply(diff_aes, function(x) { nrow(unique(data[, c("x", "stratum", x)])) }) > n_lodes)] data$fissure <- if (length(fissure_aes) == 0) { 1 } else { # order by aesthetics in order as.integer(interaction(data[, rev(fissure_aes)], drop = TRUE)) * (-1) ^ (data$yneg * absolute + reverse) } # stack positions of flows to strata, using 'alluvium' to link them # (does not assume that 'x' is continuous or regularly-spaced) ran_x <- range(data$x) uniq_x <- sort(unique(data$x)) # ensure that 'alluvium' ranges simply from 1 to max data$alluvium <- contiguate(data$alluvium) alluvium_max <- max(data$alluvium) data <- rbind( transform(data[data$x != ran_x[2], , drop = FALSE], alluvium = alluvium + alluvium_max * (match(as.character(x), as.character(uniq_x)) - 1), link = match(as.character(x), as.character(uniq_x)), flow = factor("from", levels = c("from", "to"))), transform(data[data$x != ran_x[1], , drop = FALSE], alluvium = alluvium + alluvium_max * (match(as.character(x), as.character(uniq_x)) - 2), link = match(as.character(x), as.character(uniq_x)) - 1, flow = factor("to", levels = c("from", "to"))) ) # flag flows between common pairs of strata and of aesthetics # (induces NAs for one-sided flows) lnk_vars <- intersect(c("deposit", "order", "fissure"), names(data)) adj_vars <- paste0("adj_", lnk_vars) # interactions of link:from:to for (i in seq(lnk_vars)) { data <- match_flows(data, lnk_vars[[i]], adj_vars[[i]]) #data[[adj_vars[i]]] <- xtfrm(data[[adj_vars[i]]]) } # designate these flow pairings the alluvia data$alluvium <- as.integer(interaction(data[, adj_vars], drop = TRUE)) # initiate variables for `after_stat()` weight <- data$weight data$weight <- NULL if (is.null(weight)) weight <- 1 data$n <- weight data$count <- data$y * weight # aggregate variables over 'alluvium', 'x', 'yneg', and 'stratum': # sum of computed variables and unique-or-bust values of aesthetics by_vars <- intersect(c("alluvium", "x", "yneg", "stratum", "deposit", "order", "fissure", "link", "flow", "adj_deposit", "adj_order", "adj_fissure"), names(data)) only_vars <- c(diff_aes) sum_vars <- c("y", "n", "count") data <- dplyr::group_by(data, dplyr::across(dplyr::all_of(by_vars))) # keep `NA`s in order to correctly position flows: # `distill()`, `only()`, and `sum(na.rm = TRUE)` agg_lode <- dplyr::summarize_at(data, "lode", distill) if (length(only_vars) > 0) { agg_only <- dplyr::summarize_at(data, only_vars, only) } data <- dplyr::summarize_at(data, sum_vars, sum, na.rm = TRUE) data <- dplyr::ungroup(data) # merges forget tibble classes data <- merge(data, agg_lode) if (length(only_vars) > 0) { data <- merge(data, agg_only) } # redefine 'group' to be used to control grobs in the geom step data$group <- data$alluvium # calculate variables for `after_stat()` x_sums <- tapply(abs(data$count), data$x, sum, na.rm = TRUE) data$prop <- data$count / x_sums[match(as.character(data$x), names(x_sums))] # sort data in preparation for `y` sums sort_fields <- c( "link", "x", "deposit", if (! is.null(data$order)) "order", #if (aes.bind != "none") "fissure", if (aes.bind == "flows") "adj_fissure", "adj_deposit", "alluvium", "flow" ) data <- data[do.call(order, data[, sort_fields]), , drop = FALSE] # calculate `y` sums data$ycum <- NA for (ll in unique(data$link)) { for (ss in unique(data$flow)) { for (yn in c(FALSE, TRUE)) { ww <- which(data$link == ll & data$flow == ss & data$yneg == yn) data$ycum[ww] <- cumulate(data$y[ww]) } } } # calculate y bounds data$fissure <- NULL data$adj_deposit <- NULL data$adj_fissure <- NULL data$link <- NULL data$ymin <- data$ycum - abs(data$y) / 2 data$ymax <- data$ycum + abs(data$y) / 2 data$y <- data$ycum data$yneg <- NULL data$ycum <- NULL # impose height restrictions if (! is.null(min.y)) data <- subset(data, ymax - ymin >= min.y) if (! is.null(max.y)) data <- subset(data, ymax - ymin <= max.y) # arrange data by aesthetics for consistent (reverse) z-ordering data <- z_order_aes(data, diff_aes) data } ) match_flows <- function(data, var, var_col) { adj <- tidyr::spread(data[, c("alluvium", "link", "flow", var)], key = "flow", value = var) adj[[var_col]] <- interaction(adj$link, adj$from, adj$to, drop = TRUE) merge(data, adj[, c("alluvium", var_col)], by = "alluvium", all.x = TRUE, all.y = FALSE) } ggalluvial/R/geom-alluvium.r0000644000176200001440000002426115146420370015557 0ustar liggesusers#' Alluvia across strata #' #' `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()]. #' #' 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. #' @template geom-aesthetics #' @template geom-curves #' @template defunct-geom-params #' #' @import ggplot2 #' @family alluvial geom layers #' @seealso [ggplot2::layer()] for additional arguments and #' [stat_alluvium()] and #' [stat_flow()] for the corresponding stats. #' @inheritParams geom_lode #' @param knot.pos The horizontal distance of x-spline knots from each stratum #' (`width/2` from its axis), either (if `knot.prop = TRUE`, the default) as a #' proportion of the length of the x-spline, i.e. of the gap between adjacent #' strata, or (if `knot.prop = FALSE`) on the scale of the `x` direction. #' @param knot.prop Logical; whether to interpret `knot.pos` as a proportion of #' the length of each flow (the default), rather than on the `x` scale. #' @param curve_type Character; the type of curve used to produce flows. #' Defaults to `"xspline"` and can be alternatively set to one of `"linear"`, #' `"cubic"`, `"quintic"`, `"sine"`, `"arctangent"`, and `"sigmoid"`. #' `"xspline"` produces approximation splines using 4 points per curve; the #' alternatives produce interpolation splines between points along the graphs #' of functions of the associated type. See the **Curves** section. #' @param curve_range For alternative `curve_type`s based on asymptotic #' functions, the value along the asymptote at which to truncate the function #' to obtain the shape that will be scaled to fit between strata. See the #' **Curves** section. #' @param 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. #' @param outline.type Type of outline of each alluvium; one of `"both"`, #' `"lower"`, `"upper"`, and `"full"`. #' @example inst/examples/ex-geom-alluvium.r #' @export geom_alluvium <- function(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, outline.type = "both", na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ...) { outline.type <- match.arg(outline.type, c("both", "upper", "lower", "full")) layer( geom = GeomAlluvium, mapping = mapping, data = data, stat = stat, position = position, show.legend = show.legend, inherit.aes = inherit.aes, params = list( width = width, knot.pos = knot.pos, knot.prop = knot.prop, curve_type = curve_type, curve_range = curve_range, segments = segments, outline.type = outline.type, na.rm = na.rm, ... ) ) } #' @rdname ggalluvial-ggproto #' @usage NULL #' @export GeomAlluvium <- ggproto( "GeomAlluvium", Geom, required_aes = c("x", "y", "ymin", "ymax"), default_aes = aes(linewidth = .5, linetype = 1, colour = "transparent", fill = "gray", alpha = .5), setup_data = function(data, params) { if (! is.null(params$aes.flow)) { warning("Parameter `aes.flow` cannot be used in `geom_alluvium`, ", "and will be ignored; ", "use `geom_lode` and `geom_flow` instead.") params$aes.flow <- NULL } # check whether color or differentiation aesthetics vary within alluvia aesthetics <- intersect(.color_diff_aesthetics, names(data)) if (nrow(unique(data[, c("alluvium", aesthetics), drop = FALSE])) != length(unique(data$alluvium))) { warning("Some differentiation aesthetics vary within alluvia, ", "and will be diffused by their first value.\n", "Consider using `geom_flow()` instead.") } knot.pos <- params$knot.pos if (is.null(knot.pos)) knot.pos <- 1/4 # positioning parameters transform(data, knot.pos = knot.pos) }, draw_group = function(self, data, panel_scales, coord, width = 1/3, knot.pos = 1/4, knot.prop = TRUE, curve_type = NULL, curve_range = NULL, segments = NULL, outline.type = "both") { # parameter defaults if (is.null(curve_type)) curve_type <- ggalluvial_opt("curve_type") if (is.null(curve_range)) curve_range <- ggalluvial_opt("curve_range") if (is.null(segments)) segments <- ggalluvial_opt("segments") # add width to data data <- transform(data, width = width) first_row <- data[1, setdiff(names(data), c("x", "xmin", "xmax", "width", "knot.pos", "y", "ymin", "ymax")), drop = FALSE] rownames(first_row) <- NULL # default to 48 segments per curve, ensure the minimum number of segments if (is.null(segments)) segments <- 48 else if (segments < 3) { #warning("Must use at least 3 segments; substituting `segments = 3`.") segments <- 3 } curve_data <- data_to_alluvium( data, knot.prop = knot.prop, curve_type = curve_type, curve_range = curve_range, segments = segments ) data <- data.frame(first_row, curve_data) # transform (after calculating spline paths) coords <- coord$transform(data, panel_scales) # graphics object is_full_outline <- identical(outline.type, "full") # polygon interior grob_polygon <- grid::xsplineGrob( x = coords$x, y = coords$y, shape = coords$shape, open = FALSE, gp = grid::gpar( fill = coords$fill, alpha = coords$alpha, col = if (is_full_outline) coords$colour else NA, lty = if (is_full_outline) coords$linetype else 1, lwd = if (is_full_outline) (coords$linewidth %||% coords$size) * .pt else 0 ) ) if (is_full_outline) { grob_polygon$name <- grid::grobName(grob_polygon, "geom_alluvium") return(grob_polygon) } # lower and upper bounds if (identical(outline.type, "lower")) coords <- coords[coords$bound == 0L, ] if (identical(outline.type, "upper")) coords <- coords[coords$bound == 1L, ] grob_lines <- grid::xsplineGrob( x = coords$x, y = coords$y, shape = coords$shape, open = TRUE, id = coords$bound, gp = grid::gpar( col = coords$colour, lty = coords$linetype, lwd = (coords$linewidth %||% coords$size) * .pt ) ) grob <- grid::grobTree(grob_polygon, grob_lines) grob$name <- grid::grobName(grob, "geom_alluvium") grob }, draw_key = draw_key_polygon, non_missing_aes = "size", rename_size = TRUE ) #' @rdname geom_alluvium #' @export data_to_alluvium <- function( data, knot.prop = TRUE, curve_type = "spline", curve_range = NULL, segments = NULL ) { if (nrow(data) == 1L) { # spline coordinates (one axis) with(data, data.frame( x = x + width / 2 * c(-1, 1, 1, -1), y = ymin + (ymax - ymin) * c(0, 0, 1, 1), shape = rep(0, 4L), bound = rep(c(0L, 1L), each = 2L) )) } else if (curve_type %in% c("spline", "xspline")) { # spline coordinates (more than one axis) # calculate control point coordinates for x-splines: # left side, right side, foreward knot, rearward knot, left side, right side w_fore <- rep(data$width, c(3, rep(4, nrow(data) - 2L), 3)) k_fore <- rep(data$knot.pos, c(3, rep(4, nrow(data) - 2L), 3)) if (knot.prop) { # distances between strata b_fore <- rep(data$x, c(1, rep(2, nrow(data) - 2L), 1)) + c(1, -1) * rep(data$width / 2, c(1, rep(2, nrow(data) - 2L), 1)) d_fore <- diff(b_fore)[seq(length(b_fore) - 1L) %% 2L] # scale `k_fore` to these distances k_fore <- k_fore * c(0, rep(d_fore, rep(4, nrow(data) - 1L)), 0) } # axis position +/- corresponding width +/- relative knot position x_fore <- rep(data$x, c(3, rep(4, nrow(data) - 2L), 3)) + w_fore / 2 * c(-1, rep(c(1, 1, -1, -1), nrow(data) - 1L), 1) + k_fore * c(0, rep(c(0, 1, -1, 0), nrow(data) - 1L), 0) # vertical positions are those of lodes ymin_fore <- rep(data$ymin, c(3, rep(4, nrow(data) - 2L), 3)) ymax_fore <- rep(data$ymax, c(3, rep(4, nrow(data) - 2L), 3)) shape_fore <- c(0, rep(c(0, 1, 1, 0), nrow(data) - 1L), 0) data.frame( x = c(x_fore, rev(x_fore)), y = c(ymin_fore, rev(ymax_fore)), shape = rep(shape_fore, 2L), bound = rep(c(0L, 1L), each = length(x_fore)) ) } else { # unit curve coordinates (more than one axis) # specs for a single flow curve curve_fun <- make_curve_fun(curve_type, curve_range) i_once <- seq(0L, 1L, length.out = segments + 1L) f_once <- curve_fun(i_once) # coordinates for a full curve b_fore <- as.vector(rbind(data$x - data$w / 2, data$x + data$w / 2)) x_fore <- c( b_fore[1], t(b_fore[seq(nrow(data) - 1L) * 2L] + outer(diff(b_fore)[seq(nrow(data) - 1L) * 2L], i_once, "*")), b_fore[nrow(data) * 2L] ) ymin_fore <- c( data$ymin[1L], t(data$ymin[-nrow(data)] + outer(diff(data$ymin), f_once, "*")), data$ymin[nrow(data)] ) ymax_fore <- c( data$ymax[1L], t(data$ymax[-nrow(data)] + outer(diff(data$ymax), f_once, "*")), data$ymax[nrow(data)] ) data.frame( x = c(x_fore, rev(x_fore)), y = c(ymin_fore, rev(ymax_fore)), shape = 0, bound = rep(c(0L, 1L), each = length(x_fore)) ) } } ggalluvial/R/self-adjoin.r0000644000176200001440000000435514166562215015177 0ustar liggesusers#' Adjoin a dataset to itself #' #' This function binds a dataset to itself along adjacent pairs of a `key` #' variable. It is invoked by [geom_flow()] to convert data in lodes #' form to something similar to alluvia form. #' #' `self_adjoin` invokes [`dplyr::mutate-joins`] functions in order to convert #' a dataset with measures along a discrete `key` variable into a dataset #' consisting of column bindings of these measures (by any `by` variables) along #' adjacent values of `key`. #' @name self-adjoin #' @importFrom rlang enquo #' @importFrom tidyselect vars_pull #' @family alluvial data manipulation #' @param data A data frame in lodes form (repeated measures data; see #' [`alluvial-data`]). #' @param key Column of `data` indicating sequential collection; handled as in #' [tidyr::spread()]. #' @param by Character vector of variables to self-adjoin by; passed to #' [`dplyr::mutate-joins`] functions. #' @param link Character vector of variables to adjoin. Will be replaced by #' pairs of variables suffixed by `suffix`. #' @param keep.x,keep.y Character vector of variables to associate with the #' first (respectively, second) copy of `data` after adjoining. These #' variables can overlap with each other but cannot overlap with `by` or #' `link`. #' @param suffix Suffixes to add to the adjoined `link` variables; passed to #' [`dplyr::mutate-joins`] functions. #' @example inst/examples/ex-self-adjoin.r #' @export self_adjoin <- function( data, key, by = NULL, link = NULL, keep.x = NULL, keep.y = NULL, suffix = c(".x", ".y") ) { key_var <- vars_pull(names(data), !! enquo(key)) # ensure that `key` is coercible to numeric #key_num <- data[[key_var]] #if (is.character(key_num)) key_num <- as.factor(key_num) #key_num <- as.numeric(key_num) # identify unique values of `key` in order uniq_key <- sort(unique(data[[key_var]])) key_num <- match(data[[key_var]], uniq_key) # select datasets `x` and `y` x <- transform(data, step = key_num)[, c("step", by, link, keep.x)] y <- transform(data, step = key_num - 1)[, c("step", by, link, keep.y)] # return inner join of `x` and `y` adj <- dplyr::inner_join( x, y, by = c("step", by), suffix = suffix ) adj$step <- uniq_key[adj$step] adj } ggalluvial/R/geom-flow.r0000644000176200001440000002011615146420370014663 0ustar liggesusers#' Flows between lodes or strata #' #' `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 x-splines between each such pair, using a provided knot #' position parameter `knot.pos`, and filled rectangles at either end, using a #' provided `width`. #' #' The helper function `positions_to_flow()` 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. #' @template geom-aesthetics #' @template geom-curves #' @template defunct-geom-params #' #' @import ggplot2 #' @family alluvial geom layers #' @seealso [ggplot2::layer()] for additional arguments and #' [stat_alluvium()] and #' [stat_flow()] for the corresponding stats. #' @inheritParams geom_alluvium #' @param aes.flow Character; how inter-lode flows assume aesthetics from lodes. #' Options are "forward" and "backward". #' @param x0,x1,ymin0,ymax0,ymin1,ymax1,kp0,kp1 Numeric corner and knot position #' data for the ribbon of a single flow. #' @example inst/examples/ex-geom-flow.r #' @export geom_flow <- function(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, outline.type = "both", aes.flow = "forward", na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ...) { outline.type <- match.arg(outline.type, c("both", "upper", "lower", "full")) aes.flow <- match.arg(aes.flow, c("forward", "backward")) layer( geom = GeomFlow, mapping = mapping, data = data, stat = stat, position = position, show.legend = show.legend, inherit.aes = inherit.aes, params = list( width = width, knot.pos = knot.pos, knot.prop = knot.prop, curve_type = curve_type, curve_range = curve_range, segments = segments, outline.type = outline.type, aes.flow = aes.flow, na.rm = na.rm, ... ) ) } #' @rdname ggalluvial-ggproto #' @usage NULL #' @export GeomFlow <- ggproto( "GeomFlow", Geom, required_aes = c("x", "y", "ymin", "ymax"), default_aes = aes(linewidth = .5, linetype = 1, colour = "transparent", fill = "gray", alpha = .5), setup_data = function(data, params) { width <- params$width if (is.null(width)) { width <- 1/3 } knot.pos <- params$knot.pos if (is.null(knot.pos)) knot.pos <- 1/4 # positioning parameters transform(data, xmin = x - width / 2, xmax = x + width / 2, knot.pos = knot.pos) }, draw_panel = function(self, data, panel_params, coord, width = 1/3, aes.flow = "forward", knot.pos = 1/4, knot.prop = TRUE, curve_type = NULL, curve_range = NULL, segments = NULL, outline.type = "both") { # parameter defaults if (is.null(curve_type)) curve_type <- ggalluvial_opt("curve_type") if (is.null(curve_range)) curve_range <- ggalluvial_opt("curve_range") if (is.null(segments)) segments <- ggalluvial_opt("segments") # exclude one-sided flows data <- data[complete.cases(data), ] # adjoin data with itself by alluvia along adjacent axes flow_pos <- intersect(names(data), c("x", "xmin", "xmax", "width", "knot.pos", "y", "ymin", "ymax")) flow_aes <- intersect(names(data), c("linewidth", "size", "linetype", "colour", "fill", "alpha")) flow_fore <- if (aes.flow != "backward") flow_aes else NULL flow_back <- if (aes.flow != "forward") flow_aes else NULL data <- self_adjoin( data = data, key = "x", by = "alluvium", link = flow_pos, keep.x = flow_fore, keep.y = flow_back, suffix = c(".0", ".1") ) # aesthetics (in prescribed order) aesthetics <- intersect(.color_diff_aesthetics, names(data)) # arrange data by aesthetics for consistent (reverse) z-ordering data <- data[do.call(order, lapply( data[, c("step", aesthetics)], function(x) factor(x, levels = unique(x)) )), ] # construct x-spline grobs grobs <- lapply(split(data, seq_len(nrow(data))), function(row) { # path of spline or unit curve f_path <- positions_to_flow( row$xmax.0, row$xmin.1, row$ymin.0, row$ymax.0, row$ymin.1, row$ymax.1, row$knot.pos.0, row$knot.pos.1, knot.prop = knot.prop, curve_type = curve_type, curve_range = curve_range, segments = segments ) # aesthetics aes <- as.data.frame(row[flow_aes], stringsAsFactors = FALSE) # join aesthetics to path f_data <- cbind(f_path, aes[rep(1, nrow(f_path)), ]) # transform (after calculating spline paths) f_coords <- coord$transform(f_data, panel_params) # graphics object for single row is_full_outline <- identical(outline.type, "full") # polygon interior grob_polygon <- grid::xsplineGrob( x = f_coords$x, y = f_coords$y, shape = f_coords$shape, open = FALSE, gp = grid::gpar( fill = f_coords$fill, alpha = f_coords$alpha, col = if (is_full_outline) f_coords$colour else NA, lty = if (is_full_outline) f_coords$linetype else 1, lwd = if (is_full_outline) (f_coords$linewidth %||% f_coords$size) * .pt else 0 ) ) if (is_full_outline) { return(grob_polygon) } # lower and upper bounds if (identical(outline.type, "lower")) f_coords <- f_coords[f_coords$bound == 0L, ] if (identical(outline.type, "upper")) f_coords <- f_coords[f_coords$bound == 1L, ] grob_lines <- grid::xsplineGrob( x = f_coords$x, y = f_coords$y, shape = f_coords$shape, open = TRUE, id = f_coords$bound, gp = grid::gpar( col = f_coords$colour, lty = f_coords$linetype, lwd = (f_coords$linewidth %||% f_coords$size) * .pt ) ) grob <- grid::grobTree(grob_polygon, grob_lines) grob }) # combine spline grobs grob <- do.call(grid::grobTree, grobs) grob$name <- grid::grobName(grob, "geom_flow") grob }, draw_key = draw_key_polygon, non_missing_aes = "size", rename_size = TRUE ) #' @rdname geom_flow #' @export positions_to_flow <- function( x0, x1, ymin0, ymax0, ymin1, ymax1, kp0, kp1, knot.prop, curve_type, curve_range, segments ) { if (curve_type %in% c("spline", "xspline")) { # x-spline path k_fore <- c(0, kp0, -kp1, 0) if (knot.prop) k_fore <- k_fore * (x1 - x0) x_fore <- rep(c(x0, x1), each = 2) + k_fore data.frame( x = c(x_fore, rev(x_fore)), y = c(ymin0, ymin0, ymin1, ymin1, ymax1, ymax1, ymax0, ymax0), shape = rep(c(0, 1, 1, 0), times = 2), bound = rep(c(0L, 1L), each = length(x_fore)) ) } else { # default to 48 segments per curve, ensure the minimum number of segments if (is.null(segments)) segments <- 48 else if (segments < 3) { #warning("Must use at least 3 segments; substituting `segments = 3`.") segments <- 3 } # unit curve path curve_fun <- make_curve_fun(curve_type, curve_range) i_fore <- seq(0, 1, length.out = segments + 1) f_fore <- curve_fun(i_fore) x_fore <- x0 + (x1 - x0) * i_fore data.frame( x = c(x_fore, rev(x_fore)), y = c(ymin0 + (ymin1 - ymin0) * f_fore, ymax1 + (ymax0 - ymax1) * f_fore), shape = 0, bound = rep(c(0L, 1L), each = length(x_fore)) ) } } ggalluvial/R/lode-guidance-functions.r0000644000176200001440000000570214166562215017507 0ustar liggesusers#' Lode guidance functions #' #' These functions control the order of lodes within strata in an alluvial #' diagram. They are invoked by [stat_alluvium()] and can be passed to #' the `lode.guidance` parameter. #' #' Each function orders the numbers 1 through `n`, starting at index #' `i`. The choice of function made in [stat_alluvium()] #' determines the order in which the other axes contribute to the sorting of #' lodes within each index axis. After starting at `i`, the functions order #' the remaining axes as follows: #' #' - `zigzag`: Zigzag outward from `i`, starting in the outward direction #' - `zigzag`: Zigzag outward from `i`, starting in the inward direction #' - `forward`: Increasing order (alias `rightward`) #' - `backward`: Decreasing order (alias `leftward`) #' - `frontback`: Proceed forward from `i` to `n`, then backward to 1 #' (alias `rightleft`) #' - `backfront`: Proceed backward from `i` to 1, then forward to `n` #' (alias `leftright`) #' #' An extended discussion of how strata and lodes are arranged in alluvial #' plots, including the effects of different lode guidance functions, can be #' found in the vignette "The Order of the Rectangles" via #' `vignette("order-rectangles", package = "ggalluvial")`. #' #' @name lode-guidance-functions #' @param n Numeric, a positive integer #' @param i Numeric, a positive integer at most `n` NULL lode_zz <- function(n, i, outward) { # radii r1 <- i - 1 r2 <- n - i r <- min(r1, r2) # attempt cohesion in the direction of the closer end backward <- (i <= n / 2) == outward # setup sgn <- if(r1 == r2) 0 else (r2 - r1) / abs(r2 - r1) rem <- (i + sgn * (r + 1)):((n+1)/2 + sgn * (n-1)/2) zz <- (1 - 2 * backward) * c(1, -1) # order c(i, if(r == 0) c() else sapply(1:r, function(j) i + j * zz), if(sgn == 0) c() else rem) } #' @rdname lode-guidance-functions #' @export lode_zigzag <- function(n, i) { lode_zz(n, i, outward = TRUE) } #' @rdname lode-guidance-functions #' @export lode_zagzig <- function(n, i) { lode_zz(n, i, outward = FALSE) } #' @rdname lode-guidance-functions #' @export lode_forward <- function(n, i) { if (i == 1) 1:n else if (i == n) c(n, 1:(n-1)) else c(i, 1:(i-1), (i+1):n) } #' @rdname lode-guidance-functions #' @export lode_rightward <- lode_forward #' @rdname lode-guidance-functions #' @export lode_backward <- function(n, i) { if (i == 1) c(i, n:2) else if (i == n) n:1 else c(i, n:(i+1), (i-1):1) } #' @rdname lode-guidance-functions #' @export lode_leftward <- lode_backward #' @rdname lode-guidance-functions #' @export lode_frontback <- function(n, i) { if (i == 1) 1:n else if (i == n) n:1 else c(i, (i+1):n, (i-1):1) } #' @rdname lode-guidance-functions #' @export lode_rightleft <- lode_frontback #' @rdname lode-guidance-functions #' @export lode_backfront <- function(n, i) { if (i == 1) 1:n else if (i == n) n:1 else c(i, (i-1):1, (i+1):n) } #' @rdname lode-guidance-functions #' @export lode_leftright <- lode_backfront ggalluvial/R/ggproto.r0000644000176200001440000000021214112432105014432 0ustar liggesusers#' Base ggproto classes for ggalluvial #' #' @name ggalluvial-ggproto #' @seealso [`ggplot2::ggplot2-ggproto`] #' @keywords internal NULL ggalluvial/R/alluvial-data.r0000644000176200001440000003054515127216606015522 0ustar liggesusers#' Check for alluvial structure and convert between alluvial formats #' #' Alluvial plots consist of multiple horizontally-distributed columns (axes) #' representing factor variables, vertical divisions (strata) of these axes #' representing these variables' values; and splines (alluvial flows) connecting #' vertical subdivisions (lodes) within strata of adjacent axes representing #' subsets or amounts of observations that take the corresponding values of the #' corresponding variables. This function checks a data frame for either of two #' types of alluvial structure: #' #' - One row per **lode**, wherein each row encodes a subset or amount of #' observations having a specific profile of axis values, a `key` field #' encodes the axis, a `value` field encodes the value within each axis, and a #' `id` column identifies multiple lodes corresponding to the same subset or #' amount of observations. `is_lodes_form` tests for this structure. #' - One row per **alluvium**, wherein each row encodes a subset or amount of #' observations having a specific profile of axis values and a set `axes` of #' fields encodes its values at each axis variable. `is_alluvia_form` tests #' for this structure. #' #' `to_lodes_form` takes a data frame with several designated variables to #' be used as axes in an alluvial plot, and reshapes the data frame so that #' the axis variable names constitute a new factor variable and their values #' comprise another. Other variables' values will be repeated, and a #' row-grouping variable can be introduced. This function invokes #' [tidyr::gather()]. #' #' `to_alluvia_form` takes a data frame with axis and axis value variables #' to be used in an alluvial plot, and reshape the data frame so that the #' axes constitute separate variables whose values are given by the value #' variable. This function invokes [tidyr::spread()]. #' #' @name alluvial-data #' @importFrom rlang enquo enquos enexpr enexprs quos is_empty quo_name #' is_character is_integerish is_quosures have_name #' @importFrom tidyselect vars_pull vars_select eval_select #' @family alluvial data manipulation #' @param data A data frame. #' @param logical Defunct. Whether to return a logical value or a character #' string indicating the type of alluvial structure ("none", "lodes", or #' "alluvia"). #' @param silent Whether to print messages. #' @param key,value,id In `to_lodes_form`, handled as in #' [tidyr::gather()] and used to name the new axis (key), stratum #' (value), and alluvium (identifying) variables. In `to_alluvia_form`, #' handled as in [tidyr::spread()] and used to identify the fields #' of `data` to be used as the axis (key), stratum (value), and alluvium #' (identifying) variables. #' @param axes In `*_alluvia_form`, handled as in #' [dplyr::select()] and used to identify the field(s) of #' `data` to be used as axes. #' @param ... Used in `is_alluvia_form` and `to_lodes_form` as in #' [dplyr::select()] to determine axis variables, as an alternative #' to `axes`. Ignored when `axes` is provided. #' @param weight Optional field of `data`, handled using #' [`rlang::enquo()`][rlang::nse-defuse], to be used as heights or depths of #' the alluvia or lodes. #' @param site Optional vector of fields of `data`, handled using #' [`rlang::enquos()`][rlang::nse-defuse], to be used to group rows before #' testing for duplicate and missing id-axis pairings. Variables intended for #' faceting should be passed to `site`. #' @param diffuse Fields of `data`, handled using #' [tidyselect::vars_select()], to merge into the reshapen data by #' `id`. They must be a subset of the axis variables. Alternatively, a #' logical value indicating whether to merge all (`TRUE`) or none #' (`FALSE`) of the axis variables. #' @param distill A logical value indicating whether to include variables, other #' than those passed to `key` and `value`, that vary within values #' of `id`. Alternatively, a function (or its name) to be used to distill #' each such variable to a single value. In addition to existing functions, #' `distill` accepts the character values `"first"` (used if #' `distill` is `TRUE`), `"last"`, and `"most"` (which #' returns the first modal value). #' @param discern Logical value indicating whether to suffix values of the #' variables used as axes that appear at more than one variable in order to #' distinguish their factor levels. This forces the levels of the combined #' factor variable `value` to be in the order of the axes. #' @example inst/examples/ex-alluvial-data.r #' @rdname alluvial-data #' @export is_lodes_form <- function(data, key, value, id, weight = NULL, site = NULL, logical = TRUE, silent = FALSE) { if (! isTRUE(logical)) defunct_parameter("logical") key_var <- vars_pull(names(data), !! enquo(key)) value_var <- vars_pull(names(data), !! enquo(value)) id_var <- vars_pull(names(data), !! enquo(id)) # test id-axis pairings within each site (see issue #65) if (! is.null(enexprs(site))) { site_vars <- vars_select(names(data), !!! enquos(site)) data[[id_var]] <- interaction(data[c(id_var, site_vars)], drop = FALSE) } if (any(duplicated(cbind(data[c(key_var, id_var)])))) { if (! silent) message("Duplicated id-axis pairings", if (! is.null(enexprs(site))) "." else "; should `site` have been specified?") return(if (logical) FALSE else "none") } n_pairs <- dplyr::n_distinct(data[key_var]) * dplyr::n_distinct(data[id_var]) if (nrow(data) < n_pairs) { if (! silent) warning("Missing id-axis pairings (at some sites).") } # if `weight` is not `NULL`, use NSE to identify `weight_var` if (! is.null(enexpr(weight))) { weight_var <- vars_select(names(data), !! enquo(weight)) if (! is.numeric(data[[weight_var]])) { if (! silent) message("Lode weights are non-numeric.") return(if (logical) FALSE else "none") } } if (logical) TRUE else "lodes" } #' @rdname alluvial-data #' @export is_alluvia_form <- function(data, ..., axes = NULL, weight = NULL, logical = TRUE, silent = FALSE) { if (! isTRUE(logical)) defunct_parameter("logical") if (is.null(enexpr(weight))) { weight_var <- NULL } else { weight_var <- vars_select(names(data), !! enquo(weight)) if (! is.numeric(data[[weight_var]])) { if (! silent) message("Alluvium weights are non-numeric.") return(if (logical) FALSE else "none") } } if (! is.null(enexpr(axes))) { axes <- data_at_vars(data, axes) } else { quos <- quos(...) if (is_empty(quos)) { axes <- setdiff(names(data), c(weight_var)) } else { axes <- unname(vars_select(names(data), !!! quos)) } } n_alluvia <- nrow(dplyr::distinct(data[axes])) n_combns <- do.call(prod, lapply(data[axes], dplyr::n_distinct)) if (n_alluvia < n_combns) { if (! silent) message("Missing alluvia for some stratum combinations.") } if (logical) TRUE else "alluvia" } #' @rdname alluvial-data #' @export to_lodes_form <- function(data, ..., axes = NULL, key = "x", value = "stratum", id = "alluvium", diffuse = FALSE, discern = FALSE) { key_var <- quo_name(enexpr(key)) value_var <- quo_name(enexpr(value)) id_var <- quo_name(enexpr(id)) if (! is.null(enexpr(axes))) { axes <- data_at_vars(data, axes) } else { quos <- quos(...) if (is_empty(quos)) { axes <- names(data) } else { axes <- unname(vars_select(names(data), !!! quos)) } } stopifnot(is_alluvia_form(data, axes, silent = TRUE)) if (! is.data.frame(data)) data <- as.data.frame(data) if (is.logical(enexpr(diffuse))) { diffuse <- if (diffuse) axes else NULL } else { diffuse <- unname(vars_select(names(data), !! enquo(diffuse))) if (! all(diffuse %in% axes)) { stop("All `diffuse` variables must be `axes` variables.") } } # combine factor levels cat_levels <- unname(unlist(lapply(lapply(data[axes], as.factor), levels))) if (any(duplicated(cat_levels)) & is.null(discern)) { warning("Some strata appear at multiple axes.") } if (isTRUE(discern)) { data <- discern_data(data, axes) # uniquify strata separately from `discern_data` as a validation step strata <- make.unique(unname(cat_levels)) } else { strata <- unique(unname(cat_levels)) } # format data in preparation for `gather()` data[[id_var]] <- 1:nrow(data) if (! is.null(diffuse)) { diffuse_data <- data[, c(id_var, diffuse), drop = FALSE] } for (i in axes) data[[i]] <- as.character(data[[i]]) # `gather()` by `axes` res <- tidyr::gather(data, key = !! key_var, value = !! value_var, axes, factor_key = TRUE) res[[value_var]] <- factor(res[[value_var]], levels = strata) # recombine with `diffuse_data` if (! is.null(diffuse)) { res <- merge(diffuse_data, res, by = id_var, all.x = FALSE, all.y = TRUE) } res } #' @rdname alluvial-data #' @export to_alluvia_form <- function(data, key, value, id, distill = FALSE) { key_var <- vars_pull(names(data), !! enquo(key)) value_var <- vars_pull(names(data), !! enquo(value)) id_var <- vars_pull(names(data), !! enquo(id)) stopifnot(is_lodes_form(data, key_var, value_var, id_var, silent = TRUE)) # handle any variables that vary within `id`s uniq_id <- length(unique(data[[id_var]])) uniq_data <- unique(data[setdiff(names(data), c(key_var, value_var))]) if (! uniq_id == nrow(uniq_data)) { distill_vars <- names(which(sapply( setdiff(names(uniq_data), id_var), function(x) nrow(unique(uniq_data[c(id_var, x)])) ) > uniq_id)) if (is.logical(distill)) { if (isTRUE(distill)) { distill <- "first" } else { warning("The following variables vary within `id`s ", "and will be dropped: ", paste(distill_vars, collapse = ", ")) distill <- NULL } # } else if (is.character(distill)) { # distill <- get(distill) } else { distill <- distill_fun(distill) } if (! is.null(distill)) { stopifnot(is.function(distill)) message("Distilled variables: ", paste(distill_vars, collapse = ", ")) distill_data <- stats::aggregate( data[distill_vars], data[id_var], distill ) if (length(distill_vars) == 1) names(distill_data)[-1] <- distill_vars } data <- data[setdiff(names(data), distill_vars)] } else { distill <- NULL } # `spread()` by designated `key` and `value` res <- tidyr::spread(data, key = !! key_var, value = !! value_var) # recombine with `distill_data` if (! is.null(distill)) { res <- merge(distill_data, res, by = id_var, all.x = FALSE, all.y = TRUE) } res } # require different character strings to represent strata at different axes discern_data <- function(data, axes, sep = ".") { # strata at each axis in order list_levels <- lapply(lapply(data[axes], as.factor), levels) # concatenated vector of strata at all axes cat_levels <- unlist(list_levels) # vector of uniquified strata across all axes new_levels <- make.unique(unname(cat_levels)) # cumulative number of strata before each axis i_levels <- cumsum(c(0, sapply(list_levels, length))) # characterized, uniquified strata at each axis for (i in seq_along(axes)) { axis_levels <- as.numeric(as.factor(data[[axes[i]]])) level_inds <- (i_levels[i] + 1):i_levels[i + 1] data[[axes[i]]] <- new_levels[level_inds][axis_levels] } data } # mimic the behavior of `tbl_at_vars()` in `select_at()` data_at_vars <- function(data, vars) { data_vars <- names(data) if (is_character(vars)) { vars } else if (is_integerish(vars)) { data_vars[vars] } else if (is_quosures(vars)) { # create a named list to pass to `tidyselect::eval_select()` data_names <- rlang::set_names(seq_along(data_vars), data_vars) out <- eval_select(rlang::expr(c(!!! vars)), data_names) out <- names(out) if (! any(have_name(vars))) { names(out) <- NULL } out } else { stop("Either a character or numeric vector ", "or a `vars()` object ", "is required.") } } ggalluvial/vignettes/0000755000176200001440000000000015146567322014424 5ustar liggesusersggalluvial/vignettes/labels.rmd0000644000176200001440000001537114370022542016365 0ustar liggesusers--- title: "Labeling small strata" author: "Jason Cory Brunson" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{labeling small strata} %\VignetteEngine{knitr::rmarkdown} \usepackage[utf8]{inputenc} --- ## Setup This brief vignette uses the `vaccinations` dataset included in {ggalluvial}. As in [the technical introduction](http://corybrunson.github.io/ggalluvial/articles/ggalluvial.html), the order of the levels is reversed to be more intuitive. Objects from other {ggplot2} extensions are accessed via `::` and `:::`. ```{r setup} knitr::opts_chunk$set(fig.width = 6, fig.height = 4, fig.align = "center") library(ggalluvial) data(vaccinations) vaccinations <- transform(vaccinations, response = factor(response, rev(levels(response)))) ``` ## Problem The issue on the table: Strata are most helpful when they're overlaid with text labels. Yet the strata often vary in height, and the labels in length, to such a degree that fitting the text inside the strata at a uniform size renders them illegible. In principle, the user could treat `size` as a variable aesthetic and manually fit text to strata, but this is cumbersome, and doesn't help anyway in cases where large text is needed. To illustrate the problem, check out the plot below. It's by no means an egregious case, but it'll do. (For a more practical example, see [this question on StackOverflow](https://stackoverflow.com/questions/50720718/labelling-and-theme-of-ggalluvial-plot-in-r), which prompted this vignette.) ```{r raw} ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + scale_x_discrete(expand = c(.1, 0)) + geom_flow(width = 1/4) + geom_stratum(alpha = .5, width = 1/4) + geom_text(stat = "stratum", size = 4) + theme(legend.position = "none") + ggtitle("vaccination survey responses", "labeled using `geom_text()`") ``` ### Fix One option is to simply omit those labels that don't fit within their strata. In response to [an issue](https://github.com/corybrunson/ggalluvial/issues/27), `v0.9.2` includes parameters in `stat_stratum()` to exclude strata outside a specified height range; while few would use this to omit the rectangles themselves, it can be used in tandem with `geom_text()` to shirk this problem, at least when the labels are concise: ```{r omit} ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + scale_x_discrete(expand = c(.1, 0)) + geom_flow(width = 1/4) + geom_stratum(alpha = .5, width = 1/4) + geom_text(stat = "stratum", size = 4, min.y = 100) + theme(legend.position = "none") + ggtitle( "vaccination survey responses", "labeled using `geom_text()` with `min.y = 100`" ) ``` This is a useful fix for some cases. Still, if the goal is a publication-ready graphic, then it reaffirms the need for more adaptable and elegant solutions. Fortunately, two wonderful packages deliver with, shall we say, flowing colors. ## Solutions Two {ggplot2} extensions are well-suited to this problem: [{ggrepel}](https://github.com/slowkow/ggrepel) and [{ggfittext}](https://github.com/wilkox/ggfittext). They provide new geom layers that use the output of existing stat layers to situate text: `ggrepel::geom_text_repel()` takes the same aesthetics as `ggplot2::geom_text()`, namely `x`, `y`, and `label`. In contrast, `ggfittext::geom_fit_text()` only specifically requires `label` but also needs enough information to determine the rectangle that will contain the text. This can be encoded as `xmin` and `xmax` or as `x` and `width` for the horizontal direction, and as `ymin` and `ymax` or as `y` and `height` for the vertical direction. Conveniently, `ggalluvial::stat_stratum()` produces more than enough information for both geoms, including `x`, `xmin`, `xmax`, and their vertical counterparts. All this can be gleaned from the `ggproto` objects that construct the layers: ```{r aesthetics} print(ggrepel::GeomTextRepel$required_aes) print(ggfittext:::GeomFitText$required_aes) print(ggfittext:::GeomFitText$setup_data) print(StatStratum$compute_panel) ``` I reached the specific solutions through trial and error. They may not be the best tricks for most cases, but they demonstrate what these packages can do. For many more examples, see the respective package vignettes: [for {ggrepel}](https://CRAN.R-project.org/package=ggrepel/vignettes/ggrepel.html), and [for {ggfittext}](https://CRAN.R-project.org/package=ggfittext/vignettes/introduction-to-ggfittext.html). ### Solution 1: {ggrepel} {ggrepel} is most often (in my experience) used to repel text away from symbols in a scatterplot, in whatever directions prevent them from overlapping the symbols and each other. In this case, however, it makes much more sense to align them vertically a fixed horizontal distance (`nudge_x`) away from the strata and repel them vertically from each other (`direction = "y"`) just enough to print them without overlap. It takes an extra bit of effort to render text _only_ for the strata at the first (or at the last) axis, but the result is worth it. ```{r ggrepel} ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + scale_x_discrete(expand = c(.4, 0)) + geom_flow(width = 1/4) + geom_stratum(alpha = .5, width = 1/4) + scale_linetype_manual(values = c("blank", "solid")) + ggrepel::geom_text_repel( aes(label = ifelse(as.numeric(survey) == 1, as.character(response), NA)), stat = "stratum", size = 4, direction = "y", nudge_x = -.5 ) + ggrepel::geom_text_repel( aes(label = ifelse(as.numeric(survey) == 3, as.character(response), NA)), stat = "stratum", size = 4, direction = "y", nudge_x = .5 ) + theme(legend.position = "none") + ggtitle("vaccination survey responses", "labeled using `geom_text_repel()`") ``` ### Solution 2: {ggfittext} {ggfittext} is simplicity itself: The strata are just rectangles, so no more parameter specifications are necessary to fit the text into them. One key parameter is `min.size`, which defaults to `4` and controls how small the text is allowed to get without being omitted. ```{r ggfittext} ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + scale_x_discrete(expand = c(.1, 0)) + geom_flow(width = 1/4) + geom_stratum(alpha = .5, width = 1/4) + ggfittext::geom_fit_text(stat = "stratum", width = 1/4, min.size = 3) + theme(legend.position = "none") + ggtitle("vaccination survey responses", "labeled using `geom_fit_text()`") ``` Note that this solution requires {ggfittext} v0.6.0. ## Appendix ```{r session info} sessioninfo::session_info() ``` ggalluvial/vignettes/ggalluvial.rmd0000644000176200001440000004101215146427613017253 0ustar liggesusers--- title: "Alluvial Plots in ggplot2" author: "Jason Cory Brunson" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{alluvial plots in ggplot2} %\VignetteEngine{knitr::rmarkdown} \usepackage[utf8]{inputenc} --- The {ggalluvial} package is a {ggplot2} extension for producing alluvial plots in a [{tidyverse}](https://github.com/tidyverse) framework. The design and functionality were originally inspired by the [{alluvial}](https://github.com/mbojan/alluvial) package and have benefitted from the feedback of many users. This vignette - defines the essential components of alluvial plots as used in the naming schemes and documentation (_axis_, _alluvium_, _stratum_, _lode_, _flow_), - describes the alluvial data structures recognized by {ggalluvial}, - illustrates the new stats and geoms, and - showcases some popular variants on the theme and how to produce them. Unlike most alluvial and related diagrams, the plots produced by {ggalluvial} are uniquely determined by the data set and statistical transformation. The distinction is detailed in [this blog post](https://corybrunson.github.io/2019/09/13/flow-taxonomy/). Many other resources exist for visualizing categorical data in R, including several more basic plot types that are likely to more accurately convey proportions to viewers when the data are not so structured as to warrant an alluvial plot. In particular, check out Michael Friendly's [{vcd} and {vcdExtra} packages](https://friendly.github.io/vcdExtra/) for a variety of statistically-motivated categorical data visualization techniques, Hadley Wickham's [{productplots} package](https://github.com/hadley/productplots) and Haley Jeppson and Heike Hofmann's descendant [{ggmosaic} package](https://haleyjeppson.github.io/ggmosaic/) for product or mosaic plots, and Nicholas Hamilton's [{ggtern} package](https://bitbucket.org/nicholasehamilton/ggtern/) for ternary coordinates. Other related packages are mentioned below. ```{r setup, echo=FALSE, message=FALSE, results='hide'} library(ggalluvial) knitr::opts_chunk$set(fig.width = 6, fig.height = 4, fig.align = "center") ``` ## Alluvial plots Here's a quintessential alluvial plot: ```{r example alluvial plot using Titanic dataset, echo=FALSE} ggplot(data = to_lodes_form(as.data.frame(Titanic), key = "Demographic", axes = 1:3), aes(x = Demographic, stratum = stratum, alluvium = alluvium, y = Freq, label = stratum)) + scale_x_discrete(expand = c(.05, .05)) + geom_alluvium(aes(fill = Survived)) + geom_stratum() + geom_text(stat = "stratum") + ggtitle("passengers on the maiden voyage of the Titanic", "stratified by demographics and survival") ``` The next section details how the elements of this image encode information about the underlying dataset. For now, we use the image as a point of reference to define the following elements of a typical alluvial plot: - An _axis_ is a dimension (variable) along which the data are vertically arranged at a fixed horizontal position. The plot above uses three categorical axes: `Class`, `Sex`, and `Age`. - The groups at each axis are depicted as opaque blocks called _strata_. For example, the `Class` axis contains four strata: `1st`, `2nd`, `3rd`, and `Crew`. - Horizontal (x-) splines called _alluvia_ span the width of the plot. In this plot, each alluvium corresponds to a fixed value of each axis variable, indicated by its vertical position at the axis, as well as of the `Survived` variable, indicated by its fill color. - The segments of the alluvia between pairs of adjacent axes are _flows_. - The alluvia intersect the strata at _lodes_. The lodes are not visualized in the above plot, but they can be inferred as filled rectangles extending the flows through the strata at each end of the plot or connecting the flows on either side of the center stratum. As the examples in the next section will demonstrate, which of these elements are incorporated into an alluvial plot depends on both how the underlying data is structured and what the creator wants the plot to communicate. ## Alluvial data {ggalluvial} recognizes two formats of "alluvial data", treated in detail in the following subsections, but which basically correspond to the "wide" and "long" formats of categorical repeated measures data. A third, tabular (or array), form is popular for storing data with multiple categorical dimensions, such as the `Titanic` and `UCBAdmissions` datasets.[^tableform] For consistency with tidy data principles and {ggplot2} conventions, {ggalluvial} does not accept tabular input; `base::as.data.frame()` converts such an array to an acceptable data frame. [^tableform]: See Friendly's tutorial, linked above, for a discussion. ### Alluvia (wide) format The wide format reflects the visual arrangement of an alluvial plot, but "untwisted": Each row corresponds to a cohort of observations that take a specific value at each variable, and each variable has its own column. An additional column contains the quantity of each row, e.g. the number of observational units in the cohort, which may be used to control the heights of the strata.[^weight-y] Basically, the wide format consists of _one row per alluvium_. This is the format into which the base function `as.data.frame()` transforms a frequency table, for instance the 3-dimensional `UCBAdmissions` dataset: ```{r alluvia format of Berkeley admissions dataset} head(as.data.frame(UCBAdmissions), n = 12) is_alluvia_form(as.data.frame(UCBAdmissions), axes = 1:3, silent = TRUE) ``` This format is inherited from the first release of {ggalluvial}, which modeled it after usage in {alluvial}: The user declares any number of axis variables, which `stat_alluvium()` and `stat_stratum()` recognize and process in a consistent way:[^width] [^width]: Note that the spacing parameter `width` is set to the same value in each alluvial layer. ```{r alluvial plot of UC Berkeley admissions dataset} ggplot(as.data.frame(UCBAdmissions), aes(y = Freq, axis1 = Gender, axis2 = Dept)) + geom_alluvium(aes(fill = Admit), width = 1/12) + geom_stratum(width = 1/12, fill = "black", color = "grey") + geom_label(stat = "stratum", aes(label = after_stat(stratum))) + scale_x_discrete(limits = c("Gender", "Dept"), expand = c(.05, .05)) + scale_fill_brewer(type = "qual", palette = "Set1") + ggtitle("UC Berkeley admissions and rejections, by sex and department") ``` An important feature of these plots is the meaningfulness of the vertical axis: No gaps are inserted between the strata, so the total height of the plot reflects the cumulative quantity of the observations. The plots produced by {ggalluvial} conform (somewhat; keep reading) to the "grammar of graphics" principles of {ggplot2}, and this prevents users from producing "free-floating" visualizations like the Sankey diagrams showcased [here](https://developers.google.com/chart/interactive/docs/gallery/sankey).[^ggforce] {ggalluvial} parameters and native {ggplot2} functionality can also produce [parallel sets](https://eagereyes.org/parallel-sets) plots, illustrated here using the `HairEyeColor` dataset:[^ggparallel][^crayola] [^ggforce]: [The {ggforce} package](https://ggforce.data-imaginist.com/) includes parallel set geom and stat layers to produce similar diagrams that can be allowed to free-float. [^ggparallel]: A greater variety of parallel sets plots are implemented in the [{ggparallel}](https://github.com/heike/ggparallel) and [{ggpcp}](https://github.com/yaweige/ggpcp) packages. [^crayola]: Eye color hex codes are taken from [Crayola's Colors of the World crayons](https://en.wikipedia.org/wiki/List_of_Crayola_crayon_colors). ```{r parallel sets plot of hair and eye color dataset} ggplot(as.data.frame(HairEyeColor), aes(y = Freq, axis1 = Hair, axis2 = Eye, axis3 = Sex)) + geom_alluvium(aes(fill = Eye), width = 1/8, knot.pos = 0, reverse = FALSE) + scale_fill_manual(values = c(Brown = "#70493D", Hazel = "#E2AC76", Green = "#3F752B", Blue = "#81B0E4")) + guides(fill = "none") + geom_stratum(alpha = .25, width = 1/8, reverse = FALSE) + geom_text(stat = "stratum", aes(label = after_stat(stratum)), reverse = FALSE) + scale_x_continuous(breaks = 1:3, labels = c("Hair", "Eye", "Sex")) + coord_flip() + ggtitle("Eye colors of 592 subjects, by sex and hair color") ``` (The warning is due to the "Hair" and "Eye" axes having the value "Brown" in common.) This format and functionality are useful for many applications and will be retained in future versions. They also involve some conspicuous deviations from {ggplot2} norms: - The `axis[0-9]*` position aesthetics are non-standard: they are not an explicit set of parameters but a family based on a regular expression pattern; and at least one, but no specific one, is required. - `stat_alluvium()` ignores any argument to the `group` aesthetic; instead, `StatAlluvium$compute_panel()` uses `group` to link the rows of the internally-transformed dataset that correspond to the same alluvium. - The horizontal axis must be manually corrected (using `scale_x_discrete()` or `scale_x_continuous()`) to reflect the implicit categorical variable identifying the axis. Furthermore, format aesthetics like `fill` are necessarily fixed for each alluvium; they cannot, for example, change from axis to axis according to the value taken at each. This means that, although they can reproduce the branching-tree structure of parallel sets, this format cannot be used to produce alluvial plots with color schemes such as those featured [here](https://developers.google.com/chart/interactive/docs/gallery/sankey) ("Controlling colors"), which are "reset" at each axis. Note also that the `stratum` variable produced by `stat_stratum()` (called by `geom_text()`) is computed during the statistical transformation and must be recovered using `after_stat()` as a [calculated aesthetic](https://corybrunson.github.io/2020/04/17/calculate-aesthetics/). ### Lodes (long) format The long format recognized by {ggalluvial} contains _one row per lode_, and can be understood as the result of "gathering" (in a deprecated {dplyr} sense) or "pivoting" (in the Microsoft Excel or current {dplyr} sense) the axis columns of a dataset in the alluvia format into a key-value pair of columns encoding the axis as the key and the stratum as the value. This format requires an additional indexing column that links the rows corresponding to a common cohort, i.e. the lodes of a single alluvium: ```{r lodes format of Berkeley admissions dataset} UCB_lodes <- to_lodes_form(as.data.frame(UCBAdmissions), axes = 1:3, id = "Cohort") head(UCB_lodes, n = 12) is_lodes_form(UCB_lodes, key = x, value = stratum, id = Cohort, silent = TRUE) ``` The functions that convert data between wide (alluvia) and long (lodes) format include several parameters that help preserve ancillary information. See `help("alluvial-data")` for examples. The same stat and geom can receive data in this format using a different set of positional aesthetics, also specific to {ggalluvial}: - `x`, the "key" variable indicating the axis to which the row corresponds, which are to be arranged along the horizontal axis; - `stratum`, the "value" taken by the axis variable indicated by `x`; and - `alluvium`, the indexing scheme that links the rows of a single alluvium. Heights can vary from axis to axis, allowing users to produce bump charts like those showcased [here](https://imgur.com/gallery/gI5p7).[^geom-area] In these cases, the strata contain no more information than the alluvia and often are not plotted. For convenience, both `stat_alluvium()` and `stat_flow()` will accept arguments for `x` and `alluvium` even if none is given for `stratum`.[^arguments] As an example, we can group countries in the `Refugees` dataset by region, in order to compare refugee volumes at different scales: [^geom-area]: If bumping is unnecessary, consider using [`geom_area()`](https://r-graph-gallery.com/136-stacked-area-chart) instead. [^arguments]: `stat_stratum()` will similarly accept arguments for `x` and `stratum` without `alluvium`. If both strata and either alluvia or flows are to be plotted, though, all three parameters need arguments. ```{r time series alluvia plot of refugees dataset} data(Refugees, package = "alluvial") country_regions <- c( Afghanistan = "Middle East", Burundi = "Central Africa", `Congo DRC` = "Central Africa", Iraq = "Middle East", Myanmar = "Southeast Asia", Palestine = "Middle East", Somalia = "Horn of Africa", Sudan = "Central Africa", Syria = "Middle East", Vietnam = "Southeast Asia" ) Refugees$region <- country_regions[Refugees$country] ggplot(data = Refugees, aes(x = year, y = refugees, alluvium = country)) + geom_alluvium(aes(fill = country, colour = country), alpha = .75, decreasing = FALSE, outline.type = "upper") + scale_x_continuous(breaks = seq(2003, 2013, 2)) + theme_bw() + theme(axis.text.x = element_text(angle = -30, hjust = 0)) + scale_fill_brewer(type = "qual", palette = "Set3") + scale_color_brewer(type = "qual", palette = "Set3") + facet_wrap(~ region, scales = "fixed") + ggtitle("refugee volume by country and region of origin") ``` The format allows us to assign aesthetics that change from axis to axis along the same alluvium, which is useful for repeated measures datasets. This requires generating a separate graphical object for each flow, as implemented in `geom_flow()`. The plot below uses a set of (changes to) students' academic curricula over the course of several semesters. Since `geom_flow()` calls `stat_flow()` by default (see the next example), we override it with `stat_alluvium()` in order to track each student across all semesters: ```{r alluvial plot of majors dataset} data(majors) majors$curriculum <- as.factor(majors$curriculum) ggplot(majors, aes(x = semester, stratum = curriculum, alluvium = student, fill = curriculum, label = curriculum)) + scale_fill_brewer(type = "qual", palette = "Set2") + geom_flow(stat = "alluvium", lode.guidance = "frontback", color = "darkgray") + geom_stratum() + theme(legend.position = "bottom") + ggtitle("student curricula across several semesters") ``` The stratum heights `y` are unspecified, so each row is given unit height. This example demonstrates one way {ggalluvial} handles missing data. The alternative is to set the parameter `na.rm` to `TRUE`.[^na.rm] Missing data handling (specifically, the order of the strata) also depends on whether the `stratum` variable is character or factor/numeric. [^na.rm]: Be sure to set `na.rm` consistently in each layer, in this case both the flows and the strata. Finally, lode format gives us the option to aggregate the flows between adjacent axes, which may be appropriate when the transitions between adjacent axes are of primary importance. We can demonstrate this option on data from the influenza vaccination surveys conducted by the [RAND American Life Panel](https://alpdata.rand.org/). The data, including one question from each of three surveys, has been aggregated by response profile: Each "subject" (mapped to `alluvium`) actually represents a cohort of subjects who responded the same way on all three questions, and the size of each cohort (mapped to `y`) is recorded in "freq". ```{r alluvial plot of vaccinations dataset} data(vaccinations) vaccinations <- transform(vaccinations, response = factor(response, rev(levels(response)))) ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + scale_x_discrete(expand = c(.1, .1)) + geom_flow() + geom_stratum(alpha = .5) + geom_text(stat = "stratum", size = 3) + theme(legend.position = "none") + ggtitle("vaccination survey responses at three points in time") ``` This plot ignores any continuity between the flows between axes. This "memoryless" statistical transformation yields a less cluttered plot, in which at most one flow proceeds from each stratum at one axis to each stratum at the next, but at the cost of being able to track each cohort across the entire plot. ## Appendix ```{r session info} sessioninfo::session_info() ``` [^weight-y]: Previously, quantities were passed to the `weight` aesthetic rather than to `y`. This prevented `scale_y_continuous()` from correctly transforming scales, and anyway it was inconsistent with the behavior of `geom_bar()`. As of version 0.12.0, `weight` is an optional parameter used only by computed variables intended for labeling, not by polygonal graphical elements. ggalluvial/vignettes/shiny.Rmd0000644000176200001440000005112114370022542016206 0ustar liggesusers--- title: "Tooltips for ggalluvial plots in Shiny apps" author: "Quentin D. Read" date: "`r Sys.Date()`" output: rmarkdown::html_vignette: self_contained: no runtime: shiny vignette: > %\VignetteIndexEntry{ggalluvial in Shiny apps} %\VignetteEngine{knitr::rmarkdown} \usepackage[utf8]{inputenc} --- ```{r setup, echo = FALSE, message = FALSE, warning = FALSE} knitr::opts_chunk$set(fig.width = 6, fig.height = 3, fig.align = "center") library(ggalluvial) pdf(NULL) ``` ## Problem In an interactive visualization, it is visually cleaner and better for interpretation if labels and other information appear as "tooltips" when the user hovers over or clicks on elements of the plot, rather than displaying all the labels on the plot at one time. However, the {ggalluvial} package does not natively include this functionality. It is possible to enable this using functions from several other packages. This vignette illustrates how to create Shiny apps that display an alluvial plot with tooltips that appear when the user hovers over two different plot elements: strata created with `geom_stratum()` and alluvia created with `geom_alluvium()`. An example is provided for wide-format alluvial data (the `UCBAdmissions` dataset) and long-format alluvial data (the `vaccinations` dataset). The tooltips that appear when the user hovers over elements of the plot show a text label and the count in each group. If the user hovers or clicks somewhere inside a ggplot panel, Shiny automatically returns information about the location of the mouse cursor *in plot coordinates*. That means the main work we have to do is to extract or manually recalculate the coordinates of the different plot elements. With that information, we can determine which plot element the cursor is hovering over and display the appropriate information in the tooltip or other output method. _Note:_ The app demonstrated here depends on the packages {htmltools} and {sp}, in addition of course to {ggalluvial} and {shiny}. Please be aware that all of these packages will need to be installed on the server where your Shiny app is running. ### Hovering over and clicking on strata Enabling hovering over and clicking on strata is straightforward because of their rectangular shape. We only need the minimum and maximum `x` and `y` coordinates for each of the rectangles. The rectangles are evenly spaced along the x-axis, centered on positive integers beginning with 1. The width is set in `geom_stratum()` so, for example, we know that the x-coordinates of the first stratum are `c(1 - width/2, 1 + width/2)`. The y-coordinates can be determined from the number of rows in the input data multiplied by their weights. ### Hovering over and clicking on alluvia Hovering over and clicking on alluvia are more difficult because the shapes of the alluvia are more complex. The default shape of the polygons includes an `xspline` curve drawn using the {grid} package. We need to manually reconstruct the coordinates of the polygons, then use `sp::pointInPolygon()` to detect which, if any, polygons the cursor is over. ## App with wide-format alluvial data The app is embedded below, followed by a walkthrough of the source code. If you aren't connected to the internet, or if you loaded this vignette using `vignette('shiny', package = 'ggalluvial')` rather than `browseVignettes(package = 'ggalluvial')`, the app will not display in the window above. You can view the app locally by running this line of code in your console: ```{r run wide app locally, eval = FALSE} shiny::shinyAppDir(system.file("examples/ex-shiny-wide-data", package="ggalluvial")) ``` ## Structure of the example app Here, we will go over each section of the code in detail. The full source code is included in the package's `examples` directory. The app first (1) loads the data and (2) builds the plot. Then, (3) information is extracted from the built plot object to (4) manually recalculate the coordinates of the polygons that make up the plot. Internally, {ggalluvial} uses the {grid} package to draw the polygons, so the next steps are (5) to define the minima and maxima of the x and y axes in {grid} units and the units that appear on the plot's coordinate system, and (6) to convert the polygon coordinates from {grid} units plot units. Next, the user interface is defined, including output of (7) the plot image and (8) the tooltip. The final block of code is the server function, which first (9) renders the plot. Finally, the tooltip is defined. This includes (10) logic to determine whether the mouse cursor is inside the plot panel, then (11) whether it is hovering over a stratum, (12) an alluvium, or neither, based on the mouse coordinates provided by Shiny. If the mouse is hovering over a plot element, the app finds appropriate information and prints it in a small "tooltip" box next to the mouse cursor (11b and 12b). This is the structure of the app in pseudocode. ```{r pseudocode, eval = FALSE} '<(1) Load data.>' '<(2) Create "ggplot" object for alluvial plot and build it.>' '<(3) Extract data from built plot object used to create alluvium polygons.>' for (polygon in polygons) { '<(4) Use polygon splines to generate coordinates of alluvium boundaries.>' } '<(5) Define range of coordinates in grid units and plot units.>' for (polygon in polygons) { '<(6) Convert coordinates from grid units to plot units.>' } ui <- fluidPage( '<(7) Output plot with hovering enabled.>' '<(8) Output tooltip.>' ) server <- function(input, output, session) { output$alluvial_plot <- renderPlot({ '<(9) Render the plot.>' }) output$tooltip <- renderText({ if ('<(10) mouse cursor is within the plot panel>') { if ('<(11) mouse cursor is within a stratum box>') { '<(11b) Render stratum tooltip.>' } else { if ('<(12) mouse cursor is within an alluvium polygon>') { '<(12b) Render alluvium tooltip.>' } } } }) } ``` ### Loading data The UC-Berkeley admissions dataset, `UCBAdmissions`, is used in this example. After loading the necessary packages, the first thing we do in the app is load the data and coerce from array to data frame. ```{r load dataset, eval = FALSE} data(UCBAdmissions) ucb_admissions <- as.data.frame(UCBAdmissions) ``` Next we set `offset`, the distance from cursor to tooltip, in pixels, in both x and y directions. We also set `node_width` and `alluvium_width` here, which are used as arguments to `geom_stratum()` and `geom_alluvium()` below, and again later to determine whether the mouse cursor is hovering over a stratum/alluvium. ```{r set options, eval = FALSE} # Offset, in pixels, for location of tooltip relative to mouse cursor, # in both x and y direction. offset <- 5 # Width of node boxes node_width <- 1/4 # Width of alluvia alluvium_width <- 1/3 ``` ### Drawing the plot and extracting coordinates Next, we create the `ggplot` object for the alluvial plot, then we call the `ggplot_build()` function to build the plot without displaying it. ```{r draw and build plot, eval = FALSE} # Draw plot. p <- ggplot(ucb_admissions, aes(y = Freq, axis1 = Gender, axis2 = Dept)) + geom_alluvium(aes(fill = Admit), knot.pos = 1/4, width = alluvium_width) + geom_stratum(width = node_width, reverse = TRUE, fill = 'black', color = 'grey') + geom_label(aes(label = after_stat(stratum)), stat = "stratum", reverse = TRUE, size = rel(2)) + theme_bw() + scale_fill_brewer(type = "qual", palette = "Set1") + scale_x_discrete(limits = c("Gender", "Dept"), expand = c(.05, .05)) + scale_y_continuous(expand = c(0, 0)) + ggtitle("UC Berkeley admissions and rejections", "by sex and department") + theme(plot.title = element_text(size = rel(1)), plot.subtitle = element_text(size = rel(1)), legend.position = 'bottom') # Build the plot. pbuilt <- ggplot_build(p) ``` Now for the hard part: reverse-engineering the coordinates of the alluvia polygons. This makes use of `pbuilt$data[[1]]`, a data frame with the individual elements of the alluvial plot. We add an additional column for `width` using the value we set above, then split the data frame by group (groups correspond to the individual alluvium polygons). We apply the function `data_to_alluvium()` to each element of the list to get the coordinates of the "skeleton" of the x-spline curve. Then, we pass these coordinates to the function `grid::xsplineGrob()` to fill in the smooth spline curves and convert them into a {grid} object. We pass the resulting object to `grid::xsplinePoints()`, which converts back into numeric vectors. At this point we now have the coordinates of the alluvium polygons. The object `xspline_points` is a list with length equal to the number of alluvium polygons in the plot. Each element of the list is a list with elements `x` and `y`, which are numeric vectors. ```{r get xsplines and draw curves, eval = FALSE} # Add width parameter, and then convert built plot data to xsplines data_draw <- transform(pbuilt$data[[1]], width = alluvium_width) groups_to_draw <- split(data_draw, data_draw$group) group_xsplines <- lapply(groups_to_draw, data_to_alluvium) # Convert xspline coordinates to grid object. xspline_coords <- lapply( group_xsplines, function(coords) grid::xsplineGrob(x = coords$x, y = coords$y, shape = coords$shape, open = FALSE) ) # Use grid::xsplinePoints to draw the curve for each polygon xspline_points <- lapply(xspline_coords, grid::xsplinePoints) ``` The coordinates we have are in {grid} plotting units but we need to convert them into the same units as the axes on the plot. We do this by determining the range of the x and y-axes in {grid} units (`xrange_old` and `yrange_old`). Then we fix the range of the x axis as 1 to the number of strata, adjusted by half the alluvium width on each side. Next we fix the range of the y-axis to the sum of the counts across all alluvia at one node. ```{r get coordinate ranges, eval = FALSE} # Define the x and y axis limits in grid coordinates (old) and plot # coordinates (new) xrange_old <- range(unlist(lapply( xspline_points, function(pts) as.numeric(pts$x) ))) yrange_old <- range(unlist(lapply( xspline_points, function(pts) as.numeric(pts$y) ))) xrange_new <- c(1 - alluvium_width/2, max(pbuilt$data[[1]]$x) + alluvium_width/2) yrange_new <- c(0, sum(pbuilt$data[[2]]$count[pbuilt$data[[2]]$x == 1])) ``` We define a function `new_range_transform()` inline and apply it to each set of coordinates. This returns another list, `polygon_coords`, with the same structure as `xspline_points`. Now we have the coordinates of the polygons in plot units! ```{r transform coordinates, eval = FALSE} # Define function to convert grid graphics coordinates to data coordinates new_range_transform <- function(x_old, range_old, range_new) { (x_old - range_old[1])/(range_old[2] - range_old[1]) * (range_new[2] - range_new[1]) + range_new[1] } # Using the x and y limits, convert the grid coordinates into plot coordinates. polygon_coords <- lapply(xspline_points, function(pts) { x_trans <- new_range_transform(x_old = as.numeric(pts$x), range_old = xrange_old, range_new = xrange_new) y_trans <- new_range_transform(x_old = as.numeric(pts$y), range_old = yrange_old, range_new = yrange_new) list(x = x_trans, y = y_trans) }) ``` ### User interface The app includes a minimal user interface with two output elements. ```{r ui, eval = FALSE} ui <- fluidPage( fluidRow(tags$div( style = "position: relative;", plotOutput("alluvial_plot", height = "650px", hover = hoverOpts(id = "plot_hover") ), htmlOutput("tooltip"))) ) ``` The elements are: - a `plotOutput` with the argument `hover` defined, to enable behavior determined by the cursor's plot coordinates whenever the user hovers over the plot. - an `htmlOutput` for the tooltip that appears next to the cursor on hover. The elements are wrapped in a `fluidRow()` and a `div()` tag. _Note:_ This vignette only illustrates how to display output when the user hovers over an element. If you want to display output when the user clicks on an element, the corresponding argument to `plotOutput()` is `click = clickOpts(id = "plot_click")`. This will return the location of the mouse cursor in plot coordinates when the user clicks somewhere within the plot panel. _Also Note:_ In the example presented here, all of the plot drawing and coordinate extracting code is outside the `server()` function, because the plot itself does not change with user input. However if you are building an app where the plot changes in response to user input, for example a menu of options of which variables to display, the plot drawing code has to be inside the `renderPlot()` expression. This means that the coordinates may need to be recalculated each time the user input changes as well. In that case, you may need to use the global assignment operator `<<-` so that the coordinates are accessible outside the `renderPlot()` expression. ### Server function In the server function, we first call `renderPlot()` to draw the plot in the app window. ```{r renderPlot, eval = FALSE} output$alluvial_plot <- renderPlot(p, res = 200) ``` Next, we define the tooltip with a `renderText()` expression. Within that expression, we first extract the cursor's plot coordinates from the user input. We determine whether the cursor is hovering over a stratum and if so, display the appropriate tooltip. ![screenshot of tooltip on stratum](https://raw.githubusercontent.com/corybrunson/ggalluvial/main/vignettes/img/hover_stratum.png) If the mouse cursor is not hovering over a stratum, we determine whether it is hovering over an alluvium polygon and if so, display different information in the tooltip. ![screenshot of tooltip on alluvium](https://raw.githubusercontent.com/corybrunson/ggalluvial/main/vignettes/img/hover_alluvium.png) If the mouse cursor is hovering over an empty region of the plot, `renderText()` returns nothing and no tooltip appears. ![screenshot of cursor over empty region](https://raw.githubusercontent.com/corybrunson/ggalluvial/main/vignettes/img/hover_empty_area.png) Let's take a deeper dive into the logic used to determine the text that appears in the tooltip. First, we check whether the cursor is inside the plot panel. If it is not, the element `plot_hover` of the input will be `NULL`. In that case `renderText()` will return nothing and no tooltip will appear. ```{r, eval = FALSE} output$tooltip <- renderText( if(!is.null(input$plot_hover)) { ... } ... ) ``` #### Hovering over a stratum Next, we check whether the cursor is over a stratum. We round the x-coordinate of the mouse cursor in data units to the nearest integer, then determine whether the x-coordinate is within `node_width/2` of that integer. If so, the mouse cursor is horizontally within the box. Here the `if`-`else` statement includes behavior to display the tooltip for a stratum if true, and an alluvium if false. ```{r, eval = FALSE} hover <- input$plot_hover x_coord <- round(hover$x) if(abs(hover$x - x_coord) < (node_width / 2)) { ... } else { ... } ``` If the condition is true, we need to find the index of the row of the input data that goes with the stratum the cursor is on. The data frame `pbuilt$data[[2]]` includes columns `x`, `ymin`, and `ymax` that define the x-coordinate of the center of the stratum, and the minimum and maximum y-coordinates of the stratum. We find the row index of that data frame where `x` is equal to the rounded x-coordinate of the cursor, and the y-coordinate of the cursor falls between `ymin` and `ymax`. ```{r, eval = FALSE} node_row <- pbuilt$data[[2]]$x == x_coord & hover$y > pbuilt$data[[2]]$ymin & hover$y < pbuilt$data[[2]]$ymax ``` To find the information to display in the tooltip, we get the name of the stratum as well as its width from the data in `pbuilt`. ```{r, eval = FALSE} node_label <- pbuilt$data[[2]]$stratum[node_row] node_n <- pbuilt$data[[2]]$count[node_row] ``` Finally, we render a tooltip using the `div` tag. We provide the text to display as arguments to `htmltools::renderTags()`. We also paste CSS style information together and pass it to the `style` argument. Note that the tooltip positioning is provided in CSS coordinates (pixels), not data coordinates. This does not require any additional effort on our part because `plot_hover` also includes an element called `coords_css`, which contains the mouse cursor location in pixel units. ```{r render strata tooltip, eval = FALSE} renderTags( tags$div( node_label, tags$br(), "n =", node_n, style = paste0( "position: absolute; ", "top: ", hover$coords_css$y + offset, "px; ", "left: ", hover$coords_css$x + offset, "px; ", "background: gray; ", "padding: 3px; ", "color: white; " ) ) )$html ``` #### Hovering over an alluvium If the cursor is not over a stratum, the next nested `if`-statement checks whether it is over an alluvium. This is done using the function `sp::point.in.polygon()` applied across each of the polygons for which we defined the coordinates inside the `renderPlot()` expression. ```{r test within polygon, eval = FALSE} hover_within_flow <- sapply( polygon_coords, function(pol) point.in.polygon(point.x = hover$x, point.y = hover$y, pol.x = pol$x, pol.y = pol$y) ) ``` If at least one polygon is beneath the mouse cursor, we locate the corresponding row in the input data and extract information to display in the tooltip. (If the condition is not met, that means the cursor is hovering over an empty area of the plot, so no tooltip appears.) ```{r, eval = FALSE} if (any(hover_within_flow)) { ... } ``` In the situation where there are more than one polygon overlapping, we get the information for the polygon that is plotted last by calling `rev()` on the logical vector returned by `point.in.polygon()`. This means that the tooltip will display information from the alluvium that appears "on top" in the plot. In this example, we display the names of the nodes that the alluvium connects, with arrows between them, and the width of the alluvium. ```{r info for alluvia tooltip, eval = FALSE} coord_id <- rev(which(hover_within_flow == 1))[1] flow_label <- paste(groups_to_draw[[coord_id]]$stratum, collapse = ' -> ') flow_n <- groups_to_draw[[coord_id]]$count[1] ``` We render a tooltip using identical syntax to the one above. ```{r render alluvia tooltip, eval = FALSE} renderTags( tags$div( flow_label, tags$br(), "n =", flow_n, style = paste0( "position: absolute; ", "top: ", hover$coords_css$y + offset, "px; ", "left: ", hover$coords_css$x + offset, "px; ", "background: gray; ", "padding: 3px; ", "color: white; " ) ) )$html ``` ## App with long-format alluvial data The `vaccinations` dataset is used for long-format alluvial data. The app is embedded at the bottom of this document, but we don't need to walk through the source code because it's almost identical to the code above. The output of `ggplot_build()` that is used to find the polygon coordinates and information for the tooltips has a consistent structure regardless of the initial format of the input data. Therefore, the calculation of polygon coordinates, user interface, and server functions of the two apps are identical. The only difference is in the initial creation of the `ggplot()` object. Refer back to the [primary vignette](ggalluvial.html) for several example plots made both with long and with wide data. The app is embedded below. Again, if the app doesn't display in the window above for whatever reason, you can view it locally by running this line of code in your console: ```{r run long app locally, eval = FALSE} shiny::shinyAppDir(system.file("examples/ex-shiny-long-data", package="ggalluvial")) ``` ## Conclusion This vignette demonstrates how to enable tooltips for {ggalluvial} plots in Shiny apps. This is one of many possible ways to do that. It may not be the optimal way — other solutions are certainly possible! The full source code for both of these Shiny apps is included with the {ggalluvial} package in the 'examples' subdirectory where the package is installed: the source files are `ggalluvial/examples/ex-shiny-wide-data/app.R` and `ggalluvial/examples/ex-shiny-long-data/app.R`. ggalluvial/vignettes/order-rectangles.rmd0000644000176200001440000005314014370022542020357 0ustar liggesusers--- title: "The Order of the Rectangles" author: "Jason Cory Brunson" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{order of rectangles} %\VignetteEngine{knitr::rmarkdown} \usepackage[utf8]{inputenc} --- How the strata and lodes at each axis are ordered, and how to control their order, is a complicated but essential part of {ggalluvial}'s functionality. This vignette explains the motivations behind the implementation and explores the functionality in greater detail than the examples. ## Setup ```{r setup} knitr::opts_chunk$set(fig.width = 6, fig.height = 3, fig.align = "center") library(ggalluvial) ``` All of the functionality discussed in this vignette is exported by {ggalluvial}. We'll also need a toy data set to play with. I conjured the data frame `toy` to be nearly as small as possible while complex enough to illustrate the positional controls: ```{r data} # toy data set set.seed(0) toy <- data.frame( subject = rep(LETTERS[1:5], times = 4), collection = rep(1:4, each = 5), category = rep( sample(c("X", "Y"), 16, replace = TRUE), rep(c(1, 2, 1, 1), times = 4) ), class = c("one", "one", "one", "two", "two") ) print(toy) ``` The subjects are classified into categories at each collection point but are also members of fixed classes. Here's how {ggalluvial} visualizes these data under default settings: ```{r plot} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + geom_alluvium(aes(fill = class)) + geom_stratum() ``` ## Motivations The amount of control the stat layers `stat_alluvial()` and `stat_flow()` exert over the [positional aesthetics](https://ggplot2.tidyverse.org/reference/aes_position.html) of graphical objects (grobs) is unusual, by the standards of {ggplot2} and many of its extensions. In [the layered grammar of graphics framework](https://www.tandfonline.com/doi/abs/10.1198/jcgs.2009.07098), the role of a statistical transformation is usually to summarize the original data, for example by binning (`stat_bin()`) or by calculating quantiles (`stat_qq()`). These transformed data are then sent to geom layers for positioning. The positions of grobs may be adjusted after the statistical transformation, for example when points are jittered (`geom_jitter()`), but the numerical data communicated by the plot are still the product of the stat. In {ggalluvial}, the stat layers exert slightly more control. For one thing, the transformation is more sophisticated than a single value or a fixed-length vector, such as a mean, standard deviation, or five-number summary. Instead, the values of `y` (which default to `1`) within each collection are, after reordering, transformed using `cumsum()` and some additional arithmetic to obtain coordinates for the centers `y` and lower and upper limits `ymin` and `ymax` of the strata representing the categories. Additionally, the reordering of lodes within each collection relies on a hierarchy of sorting variables, based on the strata at nearby axes as well as the present one and, optionally, on the values of differentiation aesthetics like `fill`. How this hierarchy is invoked depends on the choices of several plotting parameters (`decreasing`, `reverse`, and `absolute`). Thus, the results of the statistical transformations are not as intrinsically meaningful as others and are subject to much more intervention by the user. Only once the transformations have produced these coordinates do the geom layers use them to position the rectangles and splines that constitute the plot. There are two key reasons for this division of labor: 1. The coordinates returned by some stat layers can be coupled with multiple geom layers. For example, all four geoms can couple with the `alluvium` stat. Moreover, as showcased in [the examples](http://corybrunson.github.io/ggalluvial/reference/index.html), the stats can also meaningfully couple with exogenous geoms like `text`, `pointrange`, and `errorbar`. (In principle, the geoms could also couple with exogenous stats, but i haven't done this or seen it done in the wild.) 2. Different parameters control the calculations of the coordinates (e.g. `aes.bind` and `cement.alluvia`) and the rendering of the graphical elements (`width`, `knot.pos`, and `aes.flow`), and it makes intuitive sense to handle these separately. For example, the heights of the strata and lodes convey information about the underlying data, whereas their widths are arbitrary. (If the data are provided in alluvia format, then `Stat*$setup_data()` converts them to lodes format in preparation for the main transformation. This can be done manually using [the exported conversion functions](http://corybrunson.github.io/ggalluvial/reference/alluvial-data.html), and this vignette will assume the data are already in lodes format.) ## Positioning strata Each stat layer demarcates one stack for each data collection point and one rectangle within each stack for each (non-empty) category.[^yneg] In [{ggalluvial} terms](http://corybrunson.github.io/ggalluvial/articles/ggalluvial.html), the collection points are axes and the rectangles are strata or lodes. [^yneg]: The one exception, discussed below, is for stratum variables that take both positive and negative values. To generate a sequence of stacked bar plots with no connecting flows, only the aesthetics `x` (standard) and `stratum` (custom) are required: ```{r strata} # collection point and category variables only data <- structure(toy[, 2:3], names = c("x", "stratum")) # required fields for stat transformations data$y <- 1 data$PANEL <- 1 # stratum transformation StatStratum$compute_panel(data) ``` Comparing this output to `toy`, notice first that the data have been aggregated: Each distinct combination of `x` and `stratum` occupies only one row. `x` encodes the axes and is subject to layers specific to this positional aesthetic, e.g. `scale_x_*()` transformations. `ymin` and `ymax` are the lower and upper bounds of the rectangles, and `y` is their vertical centers. Each stacked rectangle begins where the one below it ends, and their heights are the numbers of subjects (or the totals of their `y` values, if `y` is passed a numerical variable) that take the corresponding category value at the corresponding collection point. Here's the plot this strata-only transformation yields: ```{r strata plot} ggplot(toy, aes(x = collection, stratum = category)) + stat_stratum() + stat_stratum(geom = "text", aes(label = category)) ``` In this vignette, i'll use the `stat_*()` functions to add layers, so that the parameters that control their behavior are accessible via tab-completion. ### Reversing the strata Within each axis, `stratum` defaults to reverse order so that the bars proceed in the original order from top to bottom. This can be overridden by setting `reverse = FALSE` in `stat_stratum()`: ```{r strata reverse} # stratum transformation with strata in original order StatStratum$compute_panel(data, reverse = FALSE) ggplot(toy, aes(x = collection, stratum = category)) + stat_stratum(reverse = FALSE) + stat_stratum(geom = "text", aes(label = category), reverse = FALSE) ``` **Warning:** The caveat to this is that, _if `reverse` is declared in any layer, then it must be declared in every layer_, lest the layers be misaligned. This includes any `alluvium`, `flow`, and `lode` layers, since their graphical elements are organized within the bounds of the strata. ### Sorting the strata by size When the strata are defined by a character or factor variable, they default to the order of the variable (lexicographic in the former case). This can be overridden by the `decreasing` parameter, which defaults to `NA` but can be set to `TRUE` or `FALSE` to arrange the strata in decreasing or increasing order in the `y` direction: ```{r strata decreasing} # stratum transformation with strata in original order StatStratum$compute_panel(data, reverse = FALSE) ggplot(toy, aes(x = collection, stratum = category)) + stat_stratum(decreasing = TRUE) + stat_stratum(geom = "text", aes(label = category), decreasing = TRUE) ``` **Warning:** The same caveat applies to `decreasing` as to `reverse`: Make sure that all layers using alluvial stats are passed the same values! Henceforth, we'll use the default (reverse and categorical) ordering of the strata themselves. ## Positioning lodes within strata ### Alluvia and flows In the strata-only plot, each subject is represented once at each axis. _Alluvia_ are x-splines that connect these multiple representations of the same subjects across the axes. In order to avoid having these splines overlap at the axes, the `alluvium` stat must stack the alluvial cohorts---subsets of subjects who have a common profile across all axes---within each stratum. These smaller cohort-specific rectangles are the _lodes_. This calculation requires the additional custom `alluvium` aesthetic, which identifies common subjects across the axes: ```{r alluvia} # collection point, category, and subject variables data <- structure(toy[, 1:3], names = c("alluvium", "x", "stratum")) # required fields for stat transformations data$y <- 1 data$PANEL <- 1 # alluvium transformation StatAlluvium$compute_panel(data) ``` The transformed data now contain _one row per cohort_---instead of per category---_per collection point_. The vertical positional aesthetics describe the lodes rather than the strata, and the `group` variable encodes the `alluvia` (a convenience for the geom layer, and the reason that {ggalluvial} stat layers ignore variables passed to `group`). Here's how this transformation translates into the alluvial plot that began the vignette, labeling the subject of each alluvium at each intersection with a stratum: ```{r alluvia plot} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class)) + stat_stratum(alpha = .25) + stat_alluvium(geom = "text", aes(label = subject)) ``` The `flow` stat differs from the `alluvium` stat by allowing the orders of the lodes within strata to differ from one side of an axis to the other. Put differently, the `flow` stat allows _mixing_ at the axes, rather than requiring that each case or cohort is follows a continuous trajectory from one end of the plot to the other. As a result, flow plots are often much less cluttered, the trade-off being that cases or cohorts cannot be tracked through them. ```{r flows} # flow transformation StatFlow$compute_panel(data) ``` The `flow` stat transformation yields _one row per cohort per side per flow_. Each intermediate axis appears twice in the data, once for the incoming flow and once for the outgoing flow. (The starting and ending axes only have rows for outgoing and incoming flows, respectively.) Here is the flow version of the preceding alluvial plot, labeling each side of each flow with the corresponding subject: ```{r flows plot} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_stratum() + stat_flow(aes(fill = class)) + stat_flow(geom = "text", aes(label = subject, hjust = after_stat(flow) == "to")) ``` The [computed variable](https://ggplot2.tidyverse.org/reference/aes_eval.html) `flow` indicates whether each row of the `compute_panel()` output corresponds to a flow _to_ or _from_ its axis; the values are used to nudge the labels toward their respective flows (to avoid overlap). Mismatches between adjacent labels indicate where lodes are ordered differently on either side of a stratum. ### Lode guidance As the number of strata at each axis grows, heterogeneous cases or cohorts can produce highly complex alluvia and very messy plots. {ggalluvial} mitigates this by strategically arranging the lodes---the intersections of the alluvia with the strata---so as to reduce their crossings between adjacent axes. This strategy is executed locally: At each axis (call it the _index_ axis), the order of the lodes is guided by several totally or partially ordered variables. In order of priority: 1. the strata at the index axis 2. the strata at the other axes to which the index axis is linked by alluvia or flows---namely, all other axes in the case of an alluvium, or a single adjacent axis in the case of a flow 3. the alluvia themselves, i.e. the variable passed to `alluvium` In the alluvium case, the prioritization of the remaining axes is determined by a _lode guidance function_. A lode guidance function can be passed to the `lode.guidance` parameter, which defaults to `"zigzag"`. This function puts the nearest (adjacent) axes first, then zigzags outward from there, initially (the "zig") in the direction of the closer extreme: ```{r lode zigzag} for (i in 1:4) print(lode_zigzag(4, i)) ``` Several alternative `lode_*()` functions are available: - `"zagzig"` behaves like `"zigzag"` except initially "zags" toward the farther extreme. - `"frontback"` and `"backfront"` behave like `"zigzag"` but extend completely in one outward direction from the index axis before the other. - `"forward"` and `"backward"` put the remaining axes in increasing and decreasing order, regardless of the relative position of the index axis. Two alternatives are illustrated below: ```{r alluvia plot w/ backfront guidance} for (i in 1:4) print(lode_backfront(4, i)) ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class), lode.guidance = "backfront") + stat_stratum() + stat_alluvium(geom = "text", aes(label = subject), lode.guidance = "backfront") ``` The difference between `"backfront"` guidance and `"zigzag"` guidance can be seen in the order of the lodes of the `"Y"` stratum at axis `3`: Whereas `"zigzag"` minimized the crossings between axes `3` and `4`, locating the distinctive class-`"one"` case above the others, `"backfront"` minimized the crossings between axes `2` and `3` (axis `2` being immediately before axis `3`), locating this case below the others. ```{r alluvia plot w/ backward guidance} for (i in 1:4) print(lode_backward(4, i)) ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class), lode.guidance = "backward") + stat_stratum() + stat_alluvium(geom = "text", aes(label = subject), lode.guidance = "backward") ``` The effect of `"backward"` guidance is to keep the right part of the plot as tidy as possible while allowing the left part to become as messy as necessary. (`"forward"` has the opposite effect.) ### Aesthetic binding It often makes sense to bundle together the cases and cohorts that fall into common groups used to assign differentiation aesthetics: most commonly `fill`, but also `alpha`, which controls the opacity of the `fill` colors, and `colour`, `linetype`, and `size`, which control the borders of the alluvia, flows, and lodes. The `aes.bind` parameter defaults to `"none"`, in which case aesthetics play no role in the order of the lodes. Setting the parameter to `"flows"` prioritizes any such aesthetics _after_ the strata of any other axes but _before_ the alluvia of the index axis (effectively ordering the flows at each axis by aesthetic), while setting it to `"alluvia"` prioritizes aesthetics _before_ the strata of any other axes (effectively ordering the alluvia). In the toy example, the stronger option results in the lodes within each stratum being sorted first by class: ```{r alluvia plot w/ strong aesthetic binding} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class, label = subject), aes.bind = "alluvia") + stat_stratum() + stat_alluvium(geom = "text", aes(fill = class, label = subject), aes.bind = "alluvia") ``` The more flexible option groups the lodes by class only after they've been ordered according to the strata at the remaining axes: ```{r alluvia plot w/ weak aesthetic binding} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class, label = subject), aes.bind = "flows") + stat_stratum() + stat_alluvium(geom = "text", aes(fill = class, label = subject), aes.bind = "flows") ``` **Warning:** In addition to parameters like `reverse`, _when aesthetic variables are prioritized at all, overlaid alluvial layers must include the same aesthetics in the same order_. (This can produce warnings when the aesthetics are not recognized by the geom.) Try removing `fill = class` from the text geom above to see the risk posed by neglecting this check. Rather than ordering lodes _within_, the `flow` stat separately orders the flows _into_ and _out from_, each stratum. (This precludes a corresponding `"alluvia"` option for `aes.bind`.) By default, the flows are ordered with respect first to the orders of the strata at the present axis and second to those at the adjacent axis. Setting `aes.bind` to the non-default option `"flows"` tells `stat_flow()` to prioritize flow aesthetics after the strata of the index axis but before the strata of the adjacent axis: ```{r flows plots w/ aesthetic binding} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_flow(aes(fill = class, label = subject), aes.bind = "flows") + stat_stratum() + stat_flow(geom = "text", aes(fill = class, label = subject, hjust = after_stat(flow) == "to"), aes.bind = "flows") ``` Note: The `aes.flow` parameter tells `geom_flow()` how flows should inherit differentiation aesthetics from adjacent axes---`"forward"` or `"backward"`. It does _not_ influence their positions. ### Manual lode ordering Finally, one may wish to put the lodes at each axis in a predefined order, subject to their being located in the correct strata. This can be done by passing a data column to the `order` aesthetic. For the toy example, we can pass a vector that puts the cases in the order of their IDs in the data at every axis: ```{r alluvia plot w/ manual lode ordering} lode_ord <- rep(seq(5), times = 4) ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class, order = lode_ord)) + stat_stratum() + stat_alluvium(geom = "text", aes(fill = class, order = lode_ord, label = subject)) ``` ```{r flows plot w/ manual lode ordering} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_flow(aes(fill = class, order = lode_ord)) + stat_stratum() + stat_flow(geom = "text", aes(fill = class, order = lode_ord, label = subject, hjust = after_stat(flow) == "to")) ``` Within each stratum at each axis, the cases are now in order from top to bottom. ## Negative strata In response to an elegant real-world use case, {ggalluvial} can now handle negative observations in the same way as `geom_bar()`: by grouping these observations into negative strata and stacking these strata in the negative `y` direction (i.e. in the opposite direction of the positive strata). This new functionality complicates the above discussion in two ways: 1. _Positioning strata:_ The negative strata could be reverse-ordered with respect to the positive strata, as in `geom_bar()`, or ordered in the same way (vertically, without regard for sign). 2. _Positioning lodes within strata:_ Two strata may correspond to the same stratum variable at an axis (one positive and one negative), which under-determines the ordering of lodes within strata. The first issue is binary: Once `decreasing` and `reverse` are chosen, there are only two options for the negative strata. The choice is made by setting the new `absolute` parameter to either `TRUE` (the default), which yields a mirror-image ordering, or `FALSE`, which adopts the same vertical ordering. This setting also influences the ordering of lodes within strata at the same nexus as `reverse`, namely at the level of the alluvium variable. The second issue is then handled by creating a `deposit` variable with unique values corresponding to each _signed_ stratum variable value, in the order prescribed by `decreasing`, `reverse`, and `absolute`. The `deposit` variable is then used in place of `stratum` for all of the lode-ordering tasks above. As a point of reference, here is a bar plot of the toy data, with a randomized sign variable used to indicate negative-valued observations: ```{r bar plot with negative observations} set.seed(78) toy$sign <- sample(c(-1, 1), nrow(toy), replace = TRUE) print(toy) ggplot(toy, aes(x = collection, y = sign)) + geom_bar(aes(fill = class), stat = "identity") ``` The default behavior, illustrated here with flows, is for the positive strata to proceed downward and the negative strata to proceed upward, in both cases from larger absolute values to zero: ```{r flows plot w/ negative strata} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject, y = sign)) + geom_flow(aes(fill = class)) + geom_stratum() + geom_text(stat = "stratum", aes(label = category)) ``` To instead have the strata proceed downward at each axis, and the lodes downward within each stratum, set `absolute = FALSE` (now plotting alluvia): ```{r alluvia plot w/ negative strata} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject, y = sign)) + geom_alluvium(aes(fill = class), absolute = FALSE) + geom_stratum(absolute = FALSE) + geom_text(stat = "alluvium", aes(label = subject), absolute = FALSE) ``` Note again that the labels are consistent with the alluvia and flows, despite the omission of the `fill` aesthetic from the text geom, because the aesthetic variables are not prioritized in the ordering of the lodes. ## More examples More examples of all of the functionality showcased here can be found in the documentation for the `stat_*()` functions, [browsable on the package website](http://corybrunson.github.io/ggalluvial/reference/index.html). ## Appendix ```{r session info} sessioninfo::session_info() ``` ggalluvial/vignettes/img/0000755000176200001440000000000014166562215015175 5ustar liggesusersggalluvial/vignettes/img/hover_empty_area.png0000644000176200001440000004321614166562215021242 0ustar liggesusersPNG  IHDRj'SzTXtRaw profile type exifxڭi7s`?C)&UB{O\^O5?w|.K~>?./Ͽ }(iDׅׅR"|]`|f?NaN_Wכl.'xRH1?dѧ~k u??xyϋY~[;X~η=ٍ\Y5oSy?ɒ__g{;#{!~zv󾯰b'"zWe 7ZiM%w7ށwłR_^^|}_+ CWE@G-𷿿Q\,o~~.1K-QzNSkX"]LHDאJ[؈BzRf1T N7K fj2B V`#,7rhTr)+2jZU߰dيU3kmr+6k͵F=nঃ+>=x34,Nm9*.[ͭƎ;mpbm T:SvT[nvw|ZpߏZ"7Qo7Eo!:HU("F =vDos "rN9n,܋PwmZ@nU]lNa{Jڭxn[ #O,7*jt(5a:k薊mb,yrhF/;:i>4]*Wf3VH)XQbc(mJ8;B[R'Xs5UM͏:z轄<R=P3kh%K]>:Xl󅬯 UeC+9]biq9ۓ59:sɪɗ;ST`^yj) Aed7kxcgI=mF^==InX ; |/.כˈ;vbQEۨj͓rv:ZgF2f# yoVTQme=E^dc3iw2ڛl'b7ykhaȐc{;"s7ruE[ٖsa!nYjP*mo0;F)greT]uRn=\?nb9<Ʉ%ύtpzlr-)Jr4jQ8;DS^`#ҩ@$TFuj:|J$GkQ6K' mߨNw;(jwvW@ڀ bfku!(uibnxg}p@`'^u@2nةodIy=wvn|=42y՘Y3r5x7ejղ9@8|6Ȟ*,%H~7`I>kkŸ)EnFWCfNe @>^ XeZh'VU|JrZCD:f#PV>/Rp~i=1 ^_팜.ѡ?Jo?iK+g ϓzBN}P˱@_Xyt"*yp@ &%Dz7ƍY^+@Qwd6_elrBJJJɈ. ^`%x&#$l#G5<h0p#s`A!q57㠊Y a9ئ硊s.0މ XZH ;0ZG#=5hc:>5jH*/c*+> mK!P:eIQdn>8AkrjL ^ RT:K%^dvʐ O.(F%$zxHۓCZ&R:;9ޡQ n[e`hR:(5zeA* ̲@i,H(8#d,v΂E ņ37n= \EU"4Ƈ"5dZCk5I?=c^tJ*Q?|]fH&A8AOK^ o2QKL*y K@͐Ĥ5Qk/Z,6S؏%톇!P|>ƞs1I;4x$3w{k"xs_ש&QM y] o+r+,aYڤK.z Dž yi<IJrAv ϋ :>qp~C9*%D΍N4uiD+ttUc1a:iE |9͈jA3jrxN imbQԚ}O8%>>‚cv1$0Y3mI)ę)V܍)c1Ρ}Щ CZmr[2 dtIGQL*Wt[uv6K4yuAg;6y+γL!%Bw2Lk:Š LrAWGGѢg?UM=R=sRMo)U2ކ+u-h(-mQDuOe%bReb8oυqV͆kpM]c[4joP}gd,d  9`&5WA6%rMҚMn%e!STaO};2d_g먒~fO+eSR pZI SF;1ƭz#rd&5)}r0R- n&9qr͘PgAm\Fxgn4L e M<+SvHxu^g[iLj{<[葞SFI$gsi K{}0v;yuK\FvN_I(V]51NvCɣ/i%K:f3 z@!#L1yȿ|vw^(Ǡ"D8+mO2`,>7 ^5vIqpߓ81v=-tXEg"ӠVlѩ щK*Z"qu8pJ]5"0CTf_MOS5p"G3᠕B>" ":r|uj4ߏDHrJk]D97BgtBZДǮbAv yw9`0\[zg~ ДT oS]5|*}V#ȡ)BqZO#5؄89B!qtO=Xξn4Ӆ}w~5LPE;]/o$GQ gUT:i]=?Q^,Jﬧl$f:h]v%ZHM')b]|գήKc?L.P| 'X%B sxb A QAL(!œz h YzGYGhtx;6d~:M{L *B CxP1}_TRϯ9>ީ7k`'Qi:oA ['dyՔzyz]exuơG Bj , A͇^Srj 'SJb%'8mO)\d)֨UbF&V2DŽVT(O&C#jU2,!OAq|LX"HcE#ؾ3֤Bv;d΋/~&60H{T;=sj}gk8`ZRw.nT!Ҧ+"I=%kOq1_rF2]-Vھ7C"cQв -pzzTuqC=3L̴I'lmq:f=qֳ,GUW&1K!tδayM\ژ !0x%5d3L:=S4 OgY=`Wrw`Y%k.MKlD1ԕ[S+schsF֑)+he V$z>\\'jw>|JtTg݀D?orG jz MZm'r&Q[tP@*ZDW&m\h[ ,:)0%dS8z(kQ^s@ۋ^IPtnׁt1:e wܟ pjA'jAn +Q]Q7E;m8ZٝFXxB |R fTudx>A! <-7dҡշ)&Ans:H2=żg2IjG ʊ5YV`e 勉vЪ:NhUh,7jO7b]GBKmf3Jm#AXNoh[/OԍmH%TY مtGd;eGJHpױq$tH?Zy#O$o88"xY{sh:zC3!l@z S}Q4^`: O  A1Q]Hь,LQw.?zxQ覧q'#C{^;:ye? ,,rK힔F\[v!?s>v4`ג6X=Xpqq r|y^]ϗ[?_ Y[i=,܌=$:z>MsURk˖95Y̒8׹XA]nB!/Yc^hAL:u=a(ʫ 7Ԣi]o( =/ <ɷ-;dQ/GO g7LA#""x Haqˮ(=FԓyŷB|=} 8gQ ֵ9Arnje_6^}%T쏪]XY錉} FMf/w>'ԣyG68=N'u 㾼 $I`~P؛ՄG PTt_OOǿoCo/~s1ӋE\U8Ӌ z1r?ww/N[b?u1_]J߮'5O$08sTuyQ.IiCCPICC profilex}=HPOS"-VuP,8J`Zu0y4iHR\ׂ?Ug]\AIEJ/)}wQa5e11[a! @'ҋx=uSEywߟR&|" xxf9YIRω #e8xfȤbf%C%&(FBegRc{JFHBʨBv):y\2`X@*$gk&ݤ` ~Q 4}l \im~^ok#onkp >!9P(gM9]s:Y-X=9{Z,rG!iTXtXML:com.adobe.xmp uH pHYs+tIME N2g IDATxOV30Pfe@pMd).;E ]v;WU,]Zp1EtVE被d7T`릐@`i"ad\}{<|7ft޹ZЂ0~ī=B{3-%(w$k#áKwotXFtso{jn"*Kz&Dc֎{&aZ5>ݹH(ʽ^-=}g1WϽY~~rO ρ{{O7ʽGy&܃B_~gcW)? |߼!x|lNRCdb|s)Яg,?UK[,FS>c]A[UC )~)ܟf6b[OT qLJ_^U|]xG1.PƘyCbAp yߝ<\|b~³r4d$VD|{cLQlA93nZS^:R򎎾ߊ׃VŤBMwJ:< }n \> @=({!su;?rtZ<GΒΌO~__]}L?}opcѲ9r=$\=x̓I>zuqc1sWɓ?1؇vRq)TVAw,\do7mM Ies*3{/#S܇/ݺߜ$.ù:=Dwdwr0{ DJ.ΐDKnm-;޴3f=TT#o{޾'s}13J7vW+uflf=%~^}'~:ͮ߸ϊ%^7uv>}aiG&ݕJRЭZ iҹ~o!G#ߝ5Ž_7S@pO˙Zs7n[z@SMic>nwKhROC/"jWc~̾6{j`!2}to `<&ǯ{ofH::E2AÉOWYPAEqtYUf}z/Wݿ<&nbH=r3^Ч/yGC/ֽ=ޱD M?%wkDt^o^zi1>{4 wЏ|< lV$~CŴ 5Ţ}M>3_L[yV)zI@ПnЇ^2=& }U1etVKX =sF/yUְ[.w֕pyuSq#/{N1;#<1<{Th'giM7Ƚ/nQ7;/c{]0on{8͇ۺ7kbK0{=OTf0n7h4nq8GK5pYt-MgTZj>g_w3dcv+{+Эx8b{s_l~½8ҖX^'ɩ]˂jx0F}ЇUZZށ B]z3`0+ޜM>i%;iw54. .}|;?d M9wOw{j!i]Kۉ@/;{5ZÈ~\*6\4ݫC^VhbaJ5p}fKЍF&z@=,, =?z=|t{6=})]f3'n*=3=3M{q)s۵টgxFӧO|~?^$9L:hw;wB;INh$p'Ĺ>$9% ՝wBN ;!p'wwBN ;!p'wBN ;!p'D[N8U TwBlxMwBN ;!p'wBN ;!p'2+pWA}68IENDB`ggalluvial/vignettes/img/hover_stratum.png0000644000176200001440000003501714166562215020613 0ustar liggesusersPNG  IHDRj`zTXtRaw profile type exifxڭivcr0;HReYI7=W}&Rs/|EϿ~;}sxu}y>5T-گ_zu4"ϋj 译V)<x^;wpLp^߼)!?٘]Sa~6u:sV5gv=fL_zOý-SM.S ;q~k[}n2%^E` qǗk>Lx~nJqw4 F6tB9[?lŸasz*"7mǜpxY(y΅{$Fa`Dm)AB%*Q^qұtsMyq׍e vsֶgq05I&@<?3Э#N&R; $pJ{nb/uPMt-$/xQS }7Q&z5 yǸ7V݀o7eN4e4FSoʼo2?2]o2?G?iJWֻMuyPճŀr󨘹O < vJe4?5$tZ 9ȤGJ,DꝒe܋7R.0/NfAiEO BR,-eJi YɫQ`B`* 0(ۥwP[Oɓlr<벴Kء[R2SFgaj!ʎ3``oIQٗ/sG Sls8UT L| =>fDiLخ6~#Qk8lPFq\ 7u-قo:na#jZn*CwTBK"A C7HZWn\xr>%)$ԐwUKչNL0R7U[fKR.hbA L ~JWef;t^U?F|o4Pf]G=Sנ6U86tBsqgB5x Ŝ S̬ӕ3 =ʴ[ʪH(ю.<{06ȧZa(˵(Rm!Ml{ꃅk Yn4D\]xN=:\c%v1W1Br%8!-ٔy{4?E8$Aw`J ;uI7@dR!|iՓ#i3cp 1FF0ʺ/$xzRTKO<\P={2HEP+KUG_%Sq7D& pp@$:QS)"hD&_A2ulD C>"嵐GDhϙ}QipqكmDcA6P70=2jDp&?Bɟbtk=!*~Q:b fO^qv$Dn8$^ckjaY%̝!7Zor(("MY "UhIKM`dߨXlٴTb+Yk$*ϒLAzX",sp;x0jXLQ yH[7DACC{TTbEeOs (kJ412gY@]܇k ".az̰@Y^z[hH !0V`ly\H TZƠX`wr<ԝ@JrCuwďW1/f&$AHj@'Z.h>$bwQ U#2:{5b \zB1]n$"A[P P\㖸@\{<F4Ov9b{QEL5m*Db"+dbM)Ww ,)(P2,]k_iP\;^D %3vZ/)]0>"bd3*`XNːinĜ̬'(>v-vڅڝhҶ]/Xmf\.i\br; m!S  E3 |?z@"_ }LJv^&D#?5rB}W8& rLM',d}nA1$BAʱeU?H<\%: 1|2}6JNQu0"b_$"vh:yDEGVc2# EıvH4u xʳ&ψQz7E:@5/}OI lMG LaCQzL"`G;ǘE:@۠"=$SyHug%wFt`xϩ&6-+ Cwb:MLqK'=h?6ۑ.D tş6뤼?qc\,g Q̛dxT*ǜyk6yWGvMM)\PpJ{$ r ukX-#M{p\i/6΍։qyb-Rau]#+|S b(+0f u,8J9T)E xݳLT/ TMCN).agKy`!+-SkHBa]Ifw CV<F:T koD*(_kVV0UצG M-2?Po67^iN{Fׅ Wl T<VH^*Sj=id`#Z&FEL4'^=+ARnGxn!El(ds." !@>Z~25?Tɺ89I֙ܓĪCi|7zOv6Cꎲ>; i}#֞%ٞj?6&I\ccj~MGjuQ'.j)6YMطؙd~"i.=DȮAbRd!Ye%xlzOǶLF9ZfsyarDYWW bbwuܟ\s0pY.T46h0R7ZZH\(@ G6lH-G>vU9YGvElKt`)i?MShƪe+X=\j1ᵞFV zo1,J<~T8fb=DraĞJp*k]c`XO:8kC!#t+HN"}BAٵwࢹQ᝕3yTTsiGʆd݃*RB" -[)r½8[cI69;*@'db܈\RJ@>QS#JBJҮj1̓a:']n{uTu^x>umnvSRĤܐ O-G$%&=gе ]";m Ci ӑװ&5^]>ϡBn(+BQ|X8<=l8c g TKBGU-ʻ& +!NQl,qZa{KMNNuwU${ϼI;̿M;\1qPWZ:G(@zLFV,ey?𜉱ﯘrz壎gƷ %YpDo#}!dscf9D]DL-hg4S( dBduR&>b!N-E¾ẲmrD;)n7 *{ rЊeH7B]E @p'*:b$~ lKMt8Bw;Zƚږ |QͥJZkA%PK,+8n3w07DӶ)_Ꮵ=(#KL II=1}DmDKȊ%HDD[6{v:Kʥ׃&.uH <FÎq`9 q'"lLX{qa"Å1Dm olT "KK/ňB٬Η:@3o隩aʈŅ˨覀%'OR_,yOWxWiRܢ[e^-Zi:9z(:(9ggM!잵Z.'-g 9Y2_arH;riv<,qq,ۍ4on&x[ze~OlkˑgSG_ARPo3sLRV>w3dľX ÈO@[!PnGϠrn55p:$"VỀ+ZF/> 'uFh4sxIk|P:R  źIttr Eĉwc[U6h9u Є4J <> )}h柜VT=6Ucjܓ ()zM5^ۂbҩyuTg]A*! 8t}㺜s:HT{X:{XϠYy 2ʴmh+M >$mLnSllȝy&Nφ:F>KҼԗ4_>d?2Ȓ5fYt970s.V}uȜN5<~u|{+uѿy!kSx`6sձHJO|$4' /ww\oCH3r?MP6̯1߹o= ƙ|-i5{7}@.mҍl`N hMSGl颅XO/Bed#bP/Ԓ ZI_h6}\.2xm~EQ To- GQ&9k0yR4=:]Sb̘(Bh D9ThX^3þqf/,j P%)ֈ)Zj# R6^>d]ȩbRr:JJZl-*%gP̎OY67_<4SkA%BWCzK(qm %Cv:3&[m"NCxIuL}hN ښC+#tvL[ :|< $s!3N5v`,aVb.F6( c8&fȃTM'5 !m׻eŢbhaV=A|!R"$yp3yhY Vl;hHxMҷ㶸(HkNi]"Ng%Dn#ٴRJ~!9P(gM9]s:Y-X=9{Z,rG!iTXtXML:com.adobe.xmp pHYs+tIME /# IDATx]H[ivB !Ym A0ze7f/b":sc7 [2Brd4P/V- g/Ny9Mr^9'.-sSYD4M\.L ~WSnͬ& Auq;@w q;@Aw @u}X_C_ikk[[[ ^HrlXW?b7p}n4^i^ @EOUhPUk׮ /o/nfoh&$~ÿN0CK"%KE;'=4;]/]q/y2a*7qʹ/;Eq;jQwX9Uɓ>sD"GTw qGml:\:::b+4q?{d29;z#gYzG" 7>S_i3r7hKl 7&8؜|tc04h3onu&߬\2tu縡u<4sl=oٯN/fE$7NV$ܢ)5۟(KYt܋Q?+Tnz˼ƥ ŝ56'qL?2;>GCk$9qj֏Ii;xS-\ߎ}=+"}d,+36 &Ed+&w;}{%6Ѣ3}w?"Twko|jkKc.$6o0@u;P̯(*La=/I$`3Ҍ5oss o3?w$?|C /DCtNޑnӥtOn/;hPwttd×YX04ZB_p?'6oD( ;Pw{n_{G"}O>[ᕝճJSawWY ~YT!xh?wXqhzxYw=jm9(9y8<ĽJޥx,v0EɄ㝝oް1I; 3}C wS`F,dԻ%^fKxwN(K]C~Nܭ?9=ws#ˠ\\%l>g߭{~zUDdcceF$ qLzWh0˪yY[[fu)cccee=,תE*;]ݍj U&Uĸh^ G//ٛذ',|z9+v1իbY%;;`դiZٱPJ?8qwwBXC]\CwĽE]Y}iW|wǝɌTf2*#MCw0v f TwF?>UpF@eoU86{5yήpPiˢs w OZ;VtoFfh;@p*v;1ݬfO|Wawlʉ;e;`X_La⯴4ak_j,%}fmm7~J'MMo nG?r㞝.717~G+tæ MgbB\q;@w @ z&NKLdž^'qG3 OhUtNT*,PpXci%m566Ŧ|"Zn?x,.̿NjzQ0_&70k[\ȌV|'hO胆SD(񓬋&=SFSѬGSN fw'"iأ U91H"Zp^㉬#h:bI:'m~q7yEDvvS|BD:'b}o4>2s$SlLn-תo/7eG8UxEDvUQ=q=SVݶFᑚw$;4)zk3DOTw;v43()Ns>:q ,HgI-O_1LL)<0w>)eq*ΉĂr28~LЮ/հFY+SF_D,1ғ|>QUc:ᴀSU: |nϞ3?DZ{SϢSf27= >Iu)b\awTw q;@Aw @fHIENDB`ggalluvial/vignettes/img/hover_alluvium.png0000644000176200001440000003735014166562215020754 0ustar liggesusersPNG  IHDRjzTXtRaw profile type exifxڭWv$DYX9Y\C$E~]T2# s3c_5lb*5-bw~u3[oO@u>~keDA+^@?j| c??f?cz+1O~,u&t~pCBo U^yoxWcow{kO3>/j1i~ۭܟp`p]ߍ/;tyr\tuwܾM{?qޫcQ%kqwv2r\9y\W~89 yl}8ː/Ww(]K~ x0]3Wn 1{Ŗ(\G.L>z ;.$-c?\RUB9knSܽ' fr("FXB)JŜr% z %Tr)Vz 5Ts-jo1Jޙ3r۝ z~GyQG}>34,f_~Nʪ&vi]vmCpI'ri{͙ǭ^so^S{6$ xh/bFldE29cx0nq/~31\~~kKf`2 ޾v8AV}W3q ZO_9msAǽz0՘~@+7 S[#Xڻ"gdp*F:|í>v[m>3JЋXEO[0YX'` DNRă}'7Pک>6: O{0B _D(54Q(o B<,e 㱠n*Ü0iDO3sR(VpOvfa':K]&JJmENd`I08 ]ttE[Rl<-zkOmMC &hmPp+g`l,vw~oy8PLMU"J2gTj"1 fc0kTX̍`T*@k3$⮎ؓS?*  =݆y!B&Q#AV{rO"S-,-L5TN9|&)G^Œ9Gd w')XkE>bS_%1Գ2Ј4UVu9;( 8p.OEDZ, bNDž$-><^TOq =nSHBp(F9fWPK(V mUr rŚߋ}e] )BBcv4_W Mu. DenJ0$%X)dW4@ɁSFnb $%Q*^E e` dh`q̈,S9S|*#p# BM#G("H[d,P*FP X; Q)`(}  \3[EiB 6GŧN C(j[dcQ,kh`.nY J&xr^i2sa6pEfHE\FJ+3S|eF`M$x*LBa`e@P0h覣ex/jmlV^-u1Tj-cܧJycE#g S>>5_?&A+3!-a8'wې=5[|S4B+AFzLfG.dMy~ 58p%ypRM`RBxjXN]9k;bf֩28M$7%qI\Pv]5D#  /AA3xZ\R$wnB% %ªKEzLP ˻lme fdBhTd[Wq,̆o};Pu^aiְ@LjB[U|s|@abvH1sf&G ] bˎfAYQiy.@HZɊD^`{qyA>F&sGgy\!%KLGK|RF*A܌Qj 5tfZ\#lY|(%|pOyR(mZjc\la/*| J$,B ;zBQFj ZcH E.zA9_`xTiRk>\(K\iR/R|鮖2Q:Ej+BW*ɯv 91 ujNbn?a58{U ] s}I| y~wT! ֨dSRGG$mKEyXaV1V7y5١6:=mBR^Gx$mO? \bކ7w \!9eF|(Ggr66uPٙA6b96HW~i?i[CwI 4CqSxT.P Nde- |+Hh ق(܂D#tS tyt@!4њ, * 0W֮}Xl@q㳽)PƎh2v0C|=! S( i SN+';3`Uu_qGnuԑ~$=c  CBun/M#~+j 1X̒@FO}:wh!4j>z{7Ȯ=)Cmo7d]DlAU˱O)a/(KݮRu_nLXÖe%QGZcV]%8oW M x Uz\5$nf%kC'xRmjWaZWߟ;4iUR *'o.#FrO_h~'҂*y#ߡ(`gB@L0Q_Ƚh~Ma9 #:䓲X8ea|TNV/JIFg3bm z[e"֧6v<~_f+<^~P[d&JGO$l(t+kdfQ̪_x( V=!}`芇tRf]luTʫB6jv'PT!;1fwc ADNDKN?+k7qo(P<iB76Qtju Kvrt^  05#IAkwˉT)~8hC - QM32 TzH|X'o*:l"Ę>%e'P(&ϙ>Q{Ve,|7`Pvw@PGadTi\}e"By@- [ vuon^9sO rQ[e6ʃ# 2O y6v^jw6$7&bZ:+dfץvVیTBOҐ,ɞРRcy|f3w(Rg MxB"I&c w.*9;펊4LXT(/Iz[]?jW j*B~#?P60\;5M&kpl慈Ml[OưTxҋO{̵㐁A~!p#cj` 7"}s d $y(,c? Cjz@D@n,lD ;KguF=d2YQ[=:tiO!;kJ{›"FT<2]O5'YI)3-AѠ.@N O^Rt|s< 8EaT=yDqF)1 )$޶: Hkc aՀ/17л~4X-ʺ%9Θk:΄XQr-x3"Pu.h^vT@pRԜrTp9J%Uz4<E {lR)`XVcP 玗wFN>npʌZ4$PioA$^"ؚQ/0:6uV+n:F+]ۆߠKCIUyjўJljNվ92ЁNDT]a o}w˔ @CQQ\jZ:3PNt<l6 L>lRIS*lDH&`bz׵>7d'?Or7Q:}tE2/Maԕ)8"(y:j$w*}.@ gЃ"HB(EM 7F4 x qPWtZl-x1JRw2|+DK,&$6Ǜg.懌U{ >ðtx'{Su櫬{}>^!Wէ up1\١oTmUz>g1ӟᛍp+B?%;;jv祔s^KGN0mO:tJ<Ucy{-2WZ*9=~'Go'))>M*e^ ҧ2zpW~QZW3Bw}ݺ?KOO9|yu[;ُk+dJnq2=m2ʥG9gUfsݍC1w~?` ])ؿ߁t c*=L*yAb cOwaކGtwSD}"4&7PuLB(|bHEuX&k[AurWcm( ?X*Xp %FP<`_qD^[k+ݓϞT*9nTZO]XYZ] -L(<֗\Q%)`(`M%]e>KFlϡ]z5h|4y&|łNO5*>xVNyD:͟qs=2]DFn-xnʮ)uvd~Aw.+D"#]ƒ$IIv]0E{COT@O5-$dqWvnJ…RW'[4D'ԅ3|cH,4|=U+]Eᜈ˞Mx6,[G@VPƉB䧉 z\FOobXPF+UӨ F@Ǫ5]Gf}:v 9ewC:0Υ%M279:o{rG-=Fө%:tN-JsFɻl"rc p\-gfS{$=;s[x}?(9 G2dbVO6έڙSFܚ7v{1͝Ca&X࿈vWGHI fNL)쇌ƫz2Ŀ .=%֌2=}16( tJ:6Df%+>o+*f(W=X"8=niCCPICC profilex}=HPOS"-VuP,8J`Zu0y4iHR\ׂ?Ug]\AIEJ/)}wQa5e11[a! @'ҋx=uSEywߟR&|" xxf9YIRω #e8xfȤbf%C%&(FBegRc{JFHBʨBv):y\2`X@*$gk&ݤ` ~Q 4}l \im~^ok#onkp >!9P(gM9]s:Y-X=9{Z,rG!iTXtXML:com.adobe.xmp Ï pHYs+tIME -aN FIDATx]h[_&q=cD֔AY Y7!-Z7řх TCuєE0v%0K=7QJJjbjmi:HtG?y>lXK0R}fsS<`輞Fw t,!!&xjwt@wt@wt@wt@wt@w@wt@wt@wFj@`*KW" 0PIHT۷1Һדlhq:V N ݸ*1NwTn+": 4X(/O+wW>[wW4{Ա:@Mt/;_Q$$*D9hwНUD9=XZ;WbEzғJ F+33`tj`AwDΞ !}uN*]W:J^'y)%B;;{H|w7SBDDy?XFM'N@w+++scN6LT7GDdeIGw(FWWioAp>f_wMu5 8d/޵*ׅXs]|fisۏ}UPEU5{.=f/x/JXWZr;W&o gYlED^8nxu9לGҶ,ɵR.OΊ֚UK#(7BΉH?v^w}Vt%eQȢx|ζ쭾Vja6ڋ/O^,+HM򎭈~ۮyfζ֢Ff^>2vNY9ݾ)}~5,reFդ-꓈]ظͭA$wwE?O3`#tJ-UڙJ_=1.fntdw`F\ ^fX~}}k<@׋u16>~]xd7ة)HGN`9+wLbL.︳53 8>? tQ [uۛʾ<{LmG)d"c=בV t3bk}}u-^*{nY:Hkެ&S˴d^lD?qŒ#"YyO0TZJv/ XZIHVlLܾ}ty榈ē`bNyX:A\ф-;00^z6᧯Y`a`3dj^?z`b!ES|~p,%P̀T3Fz9t4V.`$wqTze ^ *$sttLʈH0 K r\m ZGD`!+ B 0 b̩O >X;n|g)zz}AB@y5yty;}]ff+e ea;;;@ `<TjP܀!V4@w'1̈́dwt@wt@wt@wt@wt۫J+t=bsȧGD߿Ov@wt@wt%\;;;;DBĤy&sl?ip8'ϝ=QDṅA,Cg|8c#MID~bM$[7.#Xx/33VlEp] ;D$f+ݭ%wGñYWNODnߍbB 9e~tj(LwkFZq;C$8:ѐݡ~ŸՄZeh0q]DbHpthJ:5TUH882-N6eFb"%aDX8Qm0 8ZZRJ&XZZt^~ﴋ7c>""uF)| %2oGwXq O'PfyDWtCDdk3&"PXs~qCmu-j:4s]ŭKA!3 %eOݡ2;Xtt@wCCW)q.%hIENDB`ggalluvial/data/0000755000176200001440000000000014112432105013303 5ustar liggesusersggalluvial/data/vaccinations.rda0000644000176200001440000000106014112432105016451 0ustar liggesusersWN@'$Q myBi*ZؕPJlqرT_ E3VBE^ϝϝ;QxTdeY?Hvgx c[7Ni=0 ymr4;쀗I[}vv󜾶luN+tBsMԐI]-ξ ߮ [V_UFjydT7oT=1r|[J9 N{ns 93wN;L9 N{|.@9sYR=Qӿd䷰|=!]G =T" h܂^3h6,'|$X ggalluvial/data/majors.rda0000644000176200001440000000056514112432105015274 0ustar liggesusersUn@2}%tKivN CIB4QcQ3>ps5BXCrtԁ{+ 7R<(;d:?\ 4E`E0RD[C̺}j\_$"]˴Y~ JlXbx>9Da-Nn1BExJ8=nق w i('dDd|kH wY %K3:ft~ i^9\}s5~VW! X~ݱHf4DLGPsK8gIPkOfL;,po*ؚAzs%4OYP ggalluvial/NAMESPACE0000644000176200001440000000237615127216606013636 0ustar liggesusers# Generated by roxygen2: do not edit by hand export(GeomAlluvium) export(GeomFlow) export(GeomLode) export(GeomStratum) export(StatAlluvium) export(StatFlow) export(StatStratum) export(data_to_alluvium) export(geom_alluvium) export(geom_flow) export(geom_lode) export(geom_stratum) export(is_alluvia_form) export(is_alluvial) export(is_alluvial_alluvia) export(is_alluvial_lodes) export(is_lodes_form) export(lode_backfront) export(lode_backward) export(lode_forward) export(lode_frontback) export(lode_leftright) export(lode_leftward) export(lode_rightleft) export(lode_rightward) export(lode_zagzig) export(lode_zigzag) export(positions_to_flow) export(self_adjoin) export(stat_alluvium) export(stat_flow) export(stat_stratum) export(to_alluvia) export(to_alluvia_form) export(to_lodes) export(to_lodes_form) import(ggplot2) importFrom(rlang,"%||%") importFrom(rlang,.data) importFrom(rlang,enexpr) importFrom(rlang,enexprs) importFrom(rlang,enquo) importFrom(rlang,enquos) importFrom(rlang,have_name) importFrom(rlang,is_character) importFrom(rlang,is_empty) importFrom(rlang,is_integerish) importFrom(rlang,is_quosures) importFrom(rlang,quo_name) importFrom(rlang,quos) importFrom(tidyselect,eval_select) importFrom(tidyselect,vars_pull) importFrom(tidyselect,vars_select) ggalluvial/NEWS.md0000644000176200001440000004572215146422772013523 0ustar liggesusers# ggalluvial 0.12.6 This patch includes some of several fixes in progress but was prompted by the deprecation by **dplyr** of `select_vars()`. ## use `eval_select()` rather than `select_vars()` in data transformations See issue #154. Thanks to @DavisVaughan. ## outline type The parameter `outline.type` from `ggplot2::geom_ribbon()` has been adapted to `geom_alluvium()` and `geom_flow()` with the same options and default. ## remove test dependency on {alluvial} The tests that use the `Refugees` data set from **alluvial** are now only run if that package is installed; see #131 and thanks to @MichaelChirico. ## `cumulate()` fix The `cumulate()` function previously broke if an axis had zero total alluvial height (#146); it has been debugged. # ggalluvial 0.12.5 This patch fixes a bug involving the {dplyr} functions `first()` and `last()` that was shifted but not fixed in 0.12.4. Rather than being imported during build, they are accessed internally and thus imported during use. See issues #107 and #108 on GitHub for details. # ggalluvial 0.12.4 ## `linewidth` aesthetic (breaking change) An upcoming release of **ggplot2** controls stroke width using the new `linewidth` aesthetic rather than `size`. This release adapts to this change internally by updating row and column layers as recommended here: ## Curve constructors Various curve constructors for alluvia and flows are consolidated into `data_to_alluvium()` and `positions_to_flow()`, which are now exported to the user as well as used internally by `GeomAlluvium$draw_group` and `GeomFlow$draw_panel`, respectively. ## Error handling Rather than throw an error when `y` values are `NA`, the stat layers now follow **ggplot2** convention, using `remove_missing()` at the setup step with the `na.rm` parameter passed to each layer. ## Aesthetic defaults To address #78 and for clarity, the legacy default `colour = 0` of three `Geom*()`s is changed to `colour = "transparent"`. ## Skipping examples `\dontrun` markers have been replace by `\donttest`, per the advice here: . More have been added in order to reduce the time required to run. ## Vignette revisions The primary vignette now uses the `HairEyeColor` data set, rather than over-using `Titanic`, to illustrate the parallel sets plot. The Shiny vignette includes an embedded app using IFrame. ## Dependency upgrades The deprecated `.dots` argument of `dplyr::group_by()` has been replaced with `dplyr::across()`, preventing a warning. # 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 (`Date`s, 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: * `is_lodes_form()` now returns `FALSE` if any axis-alluvium pairs are duplicated, and throws the previous warning as a message. This should be more helpful than the previous behavior of suppressing the warning and leaving `tidyr::gather()` to throw an error referring to rows of the already-transformed internal data. * Default aesthetic specifications `stratum = NULL` and `alluvium = NULL` have been added to the stats. This prevents the "unknown aesthetics" warnings that print when these aesthetics are passed to layers rather than to the plot initialization. ## 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()`). ## Options 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 ## Dependencies 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 - The `min.height` and `max.height` parameters of `stat_stratum()` are deprecated in favor of `min.y` and `max.y` (which better adhere to **ggplot2** conventions) and extended to the other `stat_*()` layers. - The `label.strata` parameter of `stat_stratum()` is deprecated in favor of `infer.label`, which is extended to the other `stat_*()` layers and sets `label` to `alluvium` in those cases rather than to `stratum`. - The `aggregate.y` parameter of `stat_alluvium()` is deprecated in favor of `cement.alluvia`, and the underlying procedure is debugged. - The `aes.bind` parameter of `stat_flow()` and `stat_alluvium()` now prefers character string options to logical values, described in the lode ordering vignette: `"none"`, `"flows"`, and `"alluvia"`. The default `"none"` produces different behavior than the previous default `FALSE`, in that under this setting the aesthetic variables are _not at all_ prioritized. - The previously defunct stat parameters `weight` and `aggregate.wts` are discontinued. ## 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): - `weight` in the `stat_*()`s (replaced with `y`) - `aggregate.wts` in `stat_alluvium()` (replaced with `aggregate.y`) - `logical` in the `is_*_form()`s ## 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 `README.md`) 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 - The `weight` aesthetic for the three `stat_*()` functions is replaced by the `y` aesthetic, so that `scale_y_continuous()` will correctly transform the vertical scales of the layers. An example is provided in the documentation for `stat_alluvium()`. _The `y` aesthetic must be present in order for scales to be correctly transformed._ The `weight` parameter is still available but deprecated. - For consistency with the switch from `weight` to `y`, the `aggregate.wts` parameter to `stat_alluvium()` is replaced with `aggregate.y`; `aggregate.wts` is deprecated. ## Alluvial data functionality - Tests for alluvial format are silenced inside the `stat_*()` functions. # 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. - The functions `is_alluvial_*()` and `to_*()` are renamed to `is_*_form()` and `to_*_form()` for consistency. Their old names are deprecated. - `is_alluvial()` is deprecated and will be removed in a future version. - The parameter `logical` is deprecated. In a future version, the functions `is_*_form()` will only return logical values. - The setting `silent = TRUE` now silences all messages. - The functions `is_*_form()` now return `FALSE` if any weights are negative, with a message to this effect. - These functions now accept unquoted variable names for the `key`, `value`, `id`, `weight`, and `diffuse` parameters, using up-to-date **rlang** and **tidyselect** functionality. - The `axes` parameter in `is_alluvia_form()` and `to_lodes_form()` now accepts `dplyr::vars()` objects, as in `dplyr::select_at()`. Alternatively, variables can be fed to these functions as in `dplyr::select()`, to be collected by `rlang::quos(...)` and used as axis variables. If `axes` is not `NULL`, then such additional arguments are ignored. - The functions `to_*_form()` now merge their internal reshapen data frames with the distilled or diffused variables in a consistent order, placing the distilled or diffused variables to the left. # ggalluvial 0.6.0 ## CRAN checks for v0.5.0 - The package now `Depends` on R `v3.3.0` (patch number zero) instead of `v3.3.1`. I've been unable to install this version locally, so there is a slight chance of incompatibility that i'll be watchful for going forward. - The **grid** and **alluvial** packages are now `Suggests` rather than `Imports`. ## Alluvial data functionality - Source files and documentation for `is_alluvial_*()` and `to_*()` functions are combined; see `help("alluvial-data")`. - `is_alluvial_alluvia` now prints a message rather than a warning when some combinations of strata are not linked by any alluvia. - `to_lodes()` now has a `diffuse` parameter to join any original variables to the reformatted data by the `id` variable (alluvium). This makes it possible to assign original variables to aesthetics after reformatting, as illustrated in a new example. - `to_alluvia()` now has a `distill` parameter to control the inclusion of any original variables that vary within values of `id` into the reformatted data, based on a distilling function that returns a single value from a vector. - `to_lodes()` now has a logical `discern` parameter that uses `make.unique()` to make stratum values that appear at different axes distinct. The `stat_*()` functions can pass the same parameter internally and print a warning if the data is already in lodes form. ## Layer internals - `GeomFlow$draw_panel()` now begins by restricting to `complete.cases()`, corresponding to flows with both starting and terminating axes. (This is not done in `StatFlow$compute_panel()`, which would have the effect of excluding missing aesthetic values from legends.) - `GeomAlluvium$setup_data()` now throws a warning if some color or differentiation aesthetics vary within alluvia. - A bug in the processing of a custom `lode.ordering` argument by `StatAlluvium$compute_panel()` has been fixed. # ggalluvial 0.5.0 ## Backward incompatibilities The `ggalluvial()` shortcut function, which included a formula interface, deprecated in version 0.4.0, is removed. # ggalluvial < 0.5.0 I only started maintaining `NEWS.md` with version 0.5.0. ggalluvial/inst/0000755000176200001440000000000015146567321013370 5ustar liggesusersggalluvial/inst/CITATION0000644000176200001440000000251014166562215014521 0ustar liggesusers# format authors (based on `citation()`) author <- .read_authors_at_R_field(meta$`Authors@R`) author <- format(author, include = c("given", "family")) # formatted description fields descr <- list( author = paste(paste(head(author, -1L), collapse = ", "), tail(author, 1L), sep = " and "), year = sub("-.*", "", meta$Date), title = paste0(meta$Package, ": ", meta$Title), note = sprintf("R package version %s", meta$Version), url = meta$URL ) # Package citation bibentry( bibtype = "Misc", textVersion = paste0( descr$author, " (", descr$year, "). ", descr$title, ". ", descr$note, ". ", descr$url ), header = gettextf("To cite package %s in publications, use:", sQuote("ggalluvial")), key = "ggalluvial-package", title = descr$title, author = descr$author, year = descr$year, note = descr$note, url = descr$url ) # JOSS article citation bibentry( bibtype = "Article", header = gettextf("To cite layered alluvial plots as implemented in %s:", sQuote("ggalluvial")), key = "ggalluvial-article", title = "{ggalluvial}: Layered Grammar for Alluvial Plots", author = "Jason Cory Brunson", year = "2020", journal = "Journal of Open Source Software", volume = "5", number = "49", pages = "2017", doi = "10.21105/joss.02017" ) ggalluvial/inst/examples/0000755000176200001440000000000015000311045015161 5ustar liggesusersggalluvial/inst/examples/ex-stat-stratum.r0000644000176200001440000000564414112432105020443 0ustar liggesusersdata(vaccinations) # only `stratum` assignment is necessary to generate strata ggplot(vaccinations, aes(y = freq, x = survey, stratum = response, fill = response)) + stat_stratum(width = .5) # lode data, positioning with y labels ggplot(vaccinations, aes(y = freq, x = survey, stratum = response, alluvium = subject, label = after_stat(count))) + stat_stratum(geom = "errorbar") + geom_text(stat = "stratum") # alluvium data, positioning with stratum labels ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, axis4 = Survived)) + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + stat_stratum(geom = "errorbar") + scale_x_discrete(limits = c("Class", "Sex", "Age", "Survived")) # omit labels for strata outside a y range ggplot(vaccinations, aes(y = freq, x = survey, stratum = response, fill = response, label = response)) + stat_stratum(width = .5) + geom_text(stat = "stratum", min.y = 100) # date-valued axis variables ggplot(vaccinations, aes(x = end_date, y = freq, stratum = response, alluvium = subject, fill = response)) + stat_alluvium(geom = "flow", lode.guidance = "forward", width = 30) + stat_stratum(width = 30) + labs(x = "Survey date", y = "Number of respondents") admissions <- as.data.frame(UCBAdmissions) admissions <- transform(admissions, Count = Freq * (-1) ^ (Admit == "Rejected")) # use negative y values to encode rejection versus acceptance ggplot(admissions, aes(y = Count, axis1 = Dept, axis2 = Gender)) + geom_alluvium(aes(fill = Dept), width = 1/12) + geom_stratum(width = 1/12, fill = "black", color = "grey") + geom_label(stat = "stratum", aes(label = after_stat(stratum)), min.y = 200) + scale_x_discrete(limits = c("Department", "Gender"), expand = c(.05, .05)) # computed variable 'deposit' indicates order of each signed stratum ggplot(admissions, aes(y = Count, axis1 = Dept, axis2 = Gender)) + geom_alluvium(aes(fill = Dept), width = 1/12) + geom_stratum(width = 1/12, fill = "black", color = "grey") + geom_text(stat = "stratum", aes(label = after_stat(deposit)), color = "white") + scale_x_discrete(limits = c("Department", "Gender"), expand = c(.05, .05)) # fixed-width strata with acceptance and rejection totals ggplot(admissions, aes(y = sign(Count), weight = Count, axis1 = Dept, axis2 = Gender)) + geom_alluvium(aes(fill = Dept), width = 1/8) + geom_stratum(width = 1/8, fill = "black", color = "grey") + geom_text(stat = "stratum", aes(label = paste0(stratum, ifelse(nchar(as.character(stratum)) == 1L, ": ", "\n"), after_stat(n))), color = "white", size = 3) + scale_x_discrete(limits = c("Department", "Gender"), expand = c(.05, .05)) ggalluvial/inst/examples/ex-geom-flow.r0000644000176200001440000000461114452602415017672 0ustar liggesusers# 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 quintic 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, outline.type = "full") # 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, outline.type = "upper") # hold the knot positions fixed ggplot(wph, aes(x = Year, alluvium = Region, y = Telephones)) + geom_flow(aes(fill = Region, colour = Region), width = 0, outline.type = "lower", knot.prop = FALSE) \donttest{ # 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 fixed-width 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"))) } ggalluvial/inst/examples/ex-shiny-wide-data/0000755000176200001440000000000014166562215020605 5ustar liggesusersggalluvial/inst/examples/ex-shiny-wide-data/app.R0000644000176200001440000001367014166562215021517 0ustar liggesuserslibrary(ggalluvial) library(shiny) library(htmltools) library(sp) data(UCBAdmissions) ucb_admissions <- as.data.frame(UCBAdmissions) # Offset, in pixels, for location of tooltip relative to mouse cursor, # in both x and y direction. offset <- 5 # Width of node boxes node_width <- 1/4 # Width of alluvia alluvium_width <- 1/3 # Draw plot. p <- ggplot(ucb_admissions, aes(y = Freq, axis1 = Gender, axis2 = Dept)) + geom_alluvium(aes(fill = Admit), knot.pos = 1/4, width = alluvium_width) + geom_stratum(width = node_width, reverse = TRUE, fill = 'black', color = 'grey') + geom_label(aes(label = after_stat(stratum)), stat = "stratum", reverse = TRUE, size = rel(2)) + theme_bw() + scale_fill_brewer(type = "qual", palette = "Set1") + scale_x_discrete(limits = c("Gender", "Dept"), expand = c(.05, .05)) + scale_y_continuous(expand = c(0, 0)) + ggtitle("UC Berkeley admissions and rejections", "by sex and department") + theme(plot.title = element_text(size = rel(1)), plot.subtitle = element_text(size = rel(1)), legend.position = 'bottom') # Build the plot. pbuilt <- ggplot_build(p) # Use built plot data to recalculate the locations of the flow polygons: # Add width parameter, and then convert built plot data to xsplines data_draw <- transform(pbuilt$data[[1]], width = alluvium_width) groups_to_draw <- split(data_draw, data_draw$group) group_xsplines <- lapply(groups_to_draw, data_to_alluvium) # Convert xspline coordinates to grid object. xspline_coords <- lapply( group_xsplines, function(coords) grid::xsplineGrob(x = coords$x, y = coords$y, shape = coords$shape, open = FALSE) ) # Use grid::xsplinePoints to draw the curve for each polygon xspline_points <- lapply(xspline_coords, grid::xsplinePoints) # Define the x and y axis limits in grid coordinates (old) and plot # coordinates (new) xrange_old <- range(unlist(lapply( xspline_points, function(pts) as.numeric(pts$x) ))) yrange_old <- range(unlist(lapply( xspline_points, function(pts) as.numeric(pts$y) ))) xrange_new <- c(1 - alluvium_width/2, max(pbuilt$data[[1]]$x) + alluvium_width/2) yrange_new <- c(0, sum(pbuilt$data[[2]]$count[pbuilt$data[[2]]$x == 1])) # Define function to convert grid graphics coordinates to data coordinates new_range_transform <- function(x_old, range_old, range_new) { (x_old - range_old[1])/(range_old[2] - range_old[1]) * (range_new[2] - range_new[1]) + range_new[1] } # Using the x and y limits, convert the grid coordinates into plot coordinates. polygon_coords <- lapply(xspline_points, function(pts) { x_trans <- new_range_transform(x_old = as.numeric(pts$x), range_old = xrange_old, range_new = xrange_new) y_trans <- new_range_transform(x_old = as.numeric(pts$y), range_old = yrange_old, range_new = yrange_new) list(x = x_trans, y = y_trans) }) # User interface ui <- fluidPage( fluidRow(tags$div( style = "position: relative;", plotOutput("alluvial_plot", height = "650px", hover = hoverOpts(id = "plot_hover") ), htmlOutput("tooltip"))) ) server <- function(input, output, session) { # Draw plot and extract coordinates output$alluvial_plot <- renderPlot(p, res = 200) output$tooltip <- renderText( if(!is.null(input$plot_hover)) { hover <- input$plot_hover x_coord <- round(hover$x) if(abs(hover$x - x_coord) < (node_width / 2)) { # Display node information if cursor is over a stratum box. # Determine stratum name from x and y coord, and the n. node_row <- pbuilt$data[[2]]$x == x_coord & hover$y > pbuilt$data[[2]]$ymin & hover$y < pbuilt$data[[2]]$ymax node_label <- pbuilt$data[[2]]$stratum[node_row] node_n <- pbuilt$data[[2]]$count[node_row] # Render tooltip renderTags( tags$div( node_label, tags$br(), "n =", node_n, style = paste0( "position: absolute; ", "top: ", hover$coords_css$y + offset, "px; ", "left: ", hover$coords_css$x + offset, "px; ", "background: gray; ", "padding: 3px; ", "color: white; " ) ) )$html } else { # Display flow information if cursor is over a flow polygon: what # alluvia does it pass through? # Calculate whether coordinates of hovering cursor are inside one of the # polygons. hover_within_flow <- sapply( polygon_coords, function(pol) point.in.polygon(point.x = hover$x, point.y = hover$y, pol.x = pol$x, pol.y = pol$y) ) if (any(hover_within_flow)) { # Find the alluvium that is plotted on top. (last) coord_id <- rev(which(hover_within_flow == 1))[1] # Find the strata labels and n corresponding to that alluvium in the data. flow_label <- paste(groups_to_draw[[coord_id]]$stratum, collapse = ' -> ') flow_n <- groups_to_draw[[coord_id]]$count[1] # Render tooltip renderTags( tags$div( flow_label, tags$br(), "n =", flow_n, style = paste0( "position: absolute; ", "top: ", hover$coords_css$y + offset, "px; ", "left: ", hover$coords_css$x + offset, "px; ", "background: gray; ", "padding: 3px; ", "color: white; " ) ) )$html } } } ) } shinyApp(ui = ui, server = server) ggalluvial/inst/examples/ex-geom-alluvium.r0000644000176200001440000000373015000311045020544 0ustar liggesusers# 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 (sigmoid 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) \donttest{ # 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) # coarsely-segmented 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) # custom-ranged 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) } ggalluvial/inst/examples/ex-shiny-long-data/0000755000176200001440000000000014166562215020614 5ustar liggesusersggalluvial/inst/examples/ex-shiny-long-data/app.R0000644000176200001440000001347014166562215021524 0ustar liggesuserslibrary(ggalluvial) library(shiny) library(htmltools) library(sp) data(vaccinations) vaccinations <- transform(vaccinations, response = factor(response, rev(levels(response)))) # Offset, in pixels, for location of tooltip relative to mouse cursor, # in both x and y direction. offset <- 5 # Width of node boxes node_width <- 1/3 # Width of alluvia alluvium_width <- 1/3 # Draw plot and extract coordinates p <- ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + scale_x_discrete(expand = c(.1, .1)) + scale_y_continuous(expand = c(0, 0)) + geom_flow(knot.pos = 1/4, width = alluvium_width) + geom_stratum(width = node_width) + geom_text(stat = "stratum", size = rel(2)) + theme_bw() + theme(legend.position = "none") + ggtitle("Vaccination responses on three surveys") + theme(plot.title = element_text(size = rel(1)), legend.position = 'bottom') # Build the plot. pbuilt <- ggplot_build(p) # Use built plot data to recalculate the locations of the flow polygons: # Add width parameter, and then convert built plot data to xsplines data_draw <- transform(pbuilt$data[[1]], width = alluvium_width) groups_to_draw <- split(data_draw, data_draw$group) group_xsplines <- lapply(groups_to_draw, data_to_alluvium) # Convert xspline coordinates to grid object. xspline_coords <- lapply( group_xsplines, function(coords) grid::xsplineGrob(x = coords$x, y = coords$y, shape = coords$shape, open = FALSE) ) # Use grid::xsplinePoints to draw the curve for each polygon xspline_points <- lapply(xspline_coords, grid::xsplinePoints) # Define the x and y axis limits in grid coordinates (old) and plot # coordinates (new) xrange_old <- range(unlist(lapply( xspline_points, function(pts) as.numeric(pts$x) ))) yrange_old <- range(unlist(lapply( xspline_points, function(pts) as.numeric(pts$y) ))) xrange_new <- c(1 - alluvium_width/2, max(pbuilt$data[[1]]$x) + alluvium_width/2) yrange_new <- c(0, sum(pbuilt$data[[2]]$count[pbuilt$data[[2]]$x == 1])) # Define function to convert grid graphics coordinates to data coordinates new_range_transform <- function(x_old, range_old, range_new) { (x_old - range_old[1])/(range_old[2] - range_old[1]) * (range_new[2] - range_new[1]) + range_new[1] } # Using the x and y limits, convert the grid coordinates into plot coordinates. polygon_coords <- lapply(xspline_points, function(pts) { x_trans <- new_range_transform(x_old = as.numeric(pts$x), range_old = xrange_old, range_new = xrange_new) y_trans <- new_range_transform(x_old = as.numeric(pts$y), range_old = yrange_old, range_new = yrange_new) list(x = x_trans, y = y_trans) }) # User interface ui <- fluidPage( fluidRow(tags$div( style = "position: relative;", plotOutput("alluvial_plot", height = "650px", hover = hoverOpts(id = "plot_hover") ), htmlOutput("tooltip"))) ) server <- function(input, output, session) { # Draw plot output$alluvial_plot <- renderPlot(p, res = 200) # Display tooltip output$tooltip <- renderText( if(!is.null(input$plot_hover)) { hover <- input$plot_hover x_coord <- round(hover$x) if(abs(hover$x - x_coord) < (node_width / 2)) { # Display node information if cursor is over a stratum box. # Determine stratum name from x and y coord, and the n. node_row <- pbuilt$data[[2]]$x == x_coord & hover$y > pbuilt$data[[2]]$ymin & hover$y < pbuilt$data[[2]]$ymax node_label <- pbuilt$data[[2]]$stratum[node_row] node_n <- pbuilt$data[[2]]$count[node_row] # Render tooltip renderTags( tags$div( node_label, tags$br(), "n =", node_n, style = paste0( "position: absolute; ", "top: ", hover$coords_css$y + offset, "px; ", "left: ", hover$coords_css$x + offset, "px; ", "background: gray; ", "padding: 3px; ", "color: white; " ) ) )$html } else { # Display flow information if cursor is over a flow polygon: what # alluvia does it pass through? # Calculate whether coordinates of hovering cursor are inside one of the # polygons. hover_within_flow <- sapply( polygon_coords, function(pol) point.in.polygon(point.x = hover$x, point.y = hover$y, pol.x = pol$x, pol.y = pol$y) ) if (any(hover_within_flow)) { # Find the alluvium that is plotted on top. (last) coord_id <- rev(which(hover_within_flow == 1))[1] # Find the strata labels and n corresponding to that alluvium in the data. flow_label <- paste(groups_to_draw[[coord_id]]$stratum, collapse = ' -> ') flow_n <- groups_to_draw[[coord_id]]$count[1] # Render tooltip renderTags( tags$div( flow_label, tags$br(), "n =", flow_n, style = paste0( "position: absolute; ", "top: ", hover$coords_css$y + offset, "px; ", "left: ", hover$coords_css$x + offset, "px; ", "background: gray; ", "padding: 3px; ", "color: white; " ) ) )$html } } } ) } shinyApp(ui = ui, server = server) ggalluvial/inst/examples/ex-stat-flow.r0000644000176200001440000000465414370022542017721 0ustar liggesusers# illustrate positioning ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, color = Survived)) + stat_stratum(geom = "errorbar") + geom_line(stat = "flow") + stat_flow(geom = "pointrange") + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + scale_x_discrete(limits = c("Class", "Sex", "Age")) # alluvium--flow comparison data(vaccinations) gg <- ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_stratum(alpha = .5) + geom_text(aes(label = response), stat = "stratum") # rightward alluvial aesthetics for vaccine survey data gg + geom_flow(stat = "alluvium", lode.guidance = "forward") # memoryless flows for vaccine survey data gg + geom_flow() # size filter examples gg <- ggplot(vaccinations, aes(y = freq, x = survey, stratum = response, alluvium = subject, fill = response, label = response)) + stat_stratum(alpha = .5) + geom_text(stat = "stratum") # omit small flows gg + geom_flow(min.y = 50) # omit large flows gg + geom_flow(max.y = 100) # negate missing entries ggplot(vaccinations, aes(y = freq, x = survey, stratum = response, alluvium = subject, fill = response, label = response, alpha = response != "Missing")) + stat_stratum(negate.strata = "Missing") + geom_flow(negate.strata = "Missing") + geom_text(stat = "stratum", alpha = 1, negate.strata = "Missing") + scale_alpha_discrete(range = c(.2, .6)) + guides(alpha = "none") \donttest{ # aesthetics that vary betwween and within strata data(vaccinations) vaccinations$subgroup <- LETTERS[1:2][rbinom( n = length(unique(vaccinations$subject)), size = 1, prob = .5 ) + 1][vaccinations$subject] ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + geom_flow(aes(alpha = subgroup)) + scale_alpha_discrete(range = c(1/3, 2/3)) + geom_stratum(alpha = .5) + geom_text(stat = "stratum") # can even set aesthetics that vary both ways ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, label = response)) + geom_flow(aes(fill = interaction(response, subgroup)), aes.bind = "flows") + scale_alpha_discrete(range = c(1/3, 2/3)) + geom_stratum(alpha = .5) + geom_text(stat = "stratum") } ggalluvial/inst/examples/ex-geom-lode.r0000644000176200001440000000100314112432105017624 0ustar liggesusers# one axis ggplot(as.data.frame(Titanic), aes(y = Freq, axis = Class)) + geom_lode(aes(fill = Class, alpha = Survived)) + scale_x_discrete(limits = c("Class")) + scale_alpha_manual(values = c(.25, .75)) gg <- ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, fill = Survived)) # alluvia and lodes gg + geom_alluvium() + geom_lode() # lodes as strata gg + geom_alluvium() + geom_stratum(stat = "alluvium") ggalluvial/inst/examples/ex-stat-alluvium.r0000644000176200001440000001130715000311045020567 0ustar liggesusers# illustrate positioning ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, color = Survived)) + stat_stratum(geom = "errorbar") + geom_line(stat = "alluvium") + stat_alluvium(geom = "pointrange") + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + scale_x_discrete(limits = c("Class", "Sex", "Age")) # lode ordering examples gg <- ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age)) + geom_stratum() + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + scale_x_discrete(limits = c("Class", "Sex", "Age")) # use of lode controls gg + geom_flow(aes(fill = Survived, alpha = Sex), stat = "alluvium", lode.guidance = "forward") # prioritize aesthetic binding gg + geom_flow(aes(fill = Survived, alpha = Sex), stat = "alluvium", aes.bind = "alluvia", lode.guidance = "forward") # use of custom lode order gg + geom_flow(aes(fill = Survived, alpha = Sex, order = sample(x = 32)), stat = "alluvium") # use of custom luide guidance function lode_custom <- function(n, i) { stopifnot(n == 3) switch( i, `1` = 1:3, `2` = c(2, 3, 1), `3` = 3:1 ) } gg + geom_flow(aes(fill = Survived, alpha = Sex), stat = "alluvium", aes.bind = "flow", lode.guidance = lode_custom) # omit missing elements & reverse the `y` axis ggplot(ggalluvial::majors, aes(x = semester, stratum = curriculum, alluvium = student, y = 1)) + geom_alluvium(fill = "darkgrey", na.rm = TRUE) + geom_stratum(aes(fill = curriculum), color = NA, na.rm = TRUE) + theme_bw() + scale_y_reverse() \donttest{ # alluvium cementation examples gg <- ggplot(ggalluvial::majors, aes(x = semester, stratum = curriculum, alluvium = student, fill = curriculum)) + geom_stratum() # diagram with outlined alluvia and labels gg + geom_flow(stat = "alluvium", color = "black") + geom_text(aes(label = after_stat(lode)), stat = "alluvium") # cemented diagram with default distillation (first most common alluvium) gg + geom_flow(stat = "alluvium", color = "black", cement.alluvia = TRUE) + geom_text(aes(label = after_stat(lode)), stat = "alluvium", cement.alluvia = TRUE) # cemented diagram with custom label distillation gg + geom_flow(stat = "alluvium", color = "black", cement.alluvia = TRUE) + geom_text(aes(label = after_stat(lode)), stat = "alluvium", cement.alluvia = TRUE, distill = function(x) paste(x, collapse = "; ")) } \donttest{ data(babynames, package = "babynames") # a discontiguous alluvium bn <- subset(babynames, prop >= .01 & sex == "F" & year > 1962 & year < 1968) ggplot(data = bn, aes(x = year, alluvium = name, y = prop)) + geom_alluvium(aes(fill = name, color = name == "Tammy"), decreasing = TRUE, show.legend = FALSE) + scale_color_manual(values = c("#00000000", "#000000")) # expanded to include missing values bn2 <- merge(bn, expand.grid(year = unique(bn$year), name = unique(bn$name)), all = TRUE) ggplot(data = bn2, aes(x = year, alluvium = name, y = prop)) + geom_alluvium(aes(fill = name, color = name == "Tammy"), decreasing = TRUE, show.legend = FALSE) + scale_color_manual(values = c("#00000000", "#000000")) # with missing values filled in with zeros bn2$prop[is.na(bn2$prop)] <- 0 ggplot(data = bn2, aes(x = year, alluvium = name, y = prop)) + geom_alluvium(aes(fill = name, color = name == "Tammy"), decreasing = TRUE, show.legend = FALSE) + scale_color_manual(values = c("#00000000", "#000000")) } # use negative y values to encode deaths versus survivals titanic <- as.data.frame(Titanic) titanic <- transform(titanic, Lives = Freq * (-1) ^ (Survived == "No")) ggplot(subset(titanic, Class != "Crew"), aes(axis1 = Class, axis2 = Sex, axis3 = Age, y = Lives)) + geom_alluvium(aes(alpha = Survived, fill = Class), absolute = FALSE) + geom_stratum(absolute = FALSE) + geom_text(stat = "stratum", aes(label = after_stat(stratum)), absolute = FALSE) + scale_x_discrete(limits = c("Class", "Sex", "Age"), expand = c(.1, .05)) + scale_alpha_discrete(range = c(.25, .75), guide = "none") # faceting with common alluvia ggplot(titanic, aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age)) + facet_wrap(~ Survived) + geom_alluvium() + geom_stratum() + geom_text(stat = "stratum", aes(label = after_stat(stratum))) ggplot(transform(alluvial::Refugees, id = 1), aes(y = refugees, x = year, alluvium = id)) + facet_wrap(~ country) + geom_alluvium(alpha = .75, color = "darkgrey") + scale_x_continuous(breaks = seq(2004, 2012, 4)) ggalluvial/inst/examples/ex-self-adjoin.r0000644000176200001440000000150714112432105020160 0ustar liggesusers# self-adjoin `majors` data data(majors) major_changes <- self_adjoin(majors, key = semester, by = "student", link = c("semester", "curriculum")) major_changes$change <- major_changes$curriculum.x == major_changes$curriculum.y head(major_changes) # self-adjoin `vaccinations` data data(vaccinations) vaccination_steps <- self_adjoin(vaccinations, key = survey, by = "subject", link = c("survey", "response"), keep.x = c("freq")) head(vaccination_steps) vaccination_steps <- self_adjoin(vaccinations, key = survey, by = "subject", link = c("survey", "response"), keep.x = c("freq"), keep.y = c("start_date", "end_date")) head(vaccination_steps) ggalluvial/inst/examples/ex-geom-stratum.r0000644000176200001440000000116114112432105020405 0ustar liggesusers# full axis width ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, axis4 = Survived)) + geom_stratum(width = 1) + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + scale_x_discrete(limits = c("Class", "Sex", "Age", "Survived")) # use of facets ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex)) + geom_flow(aes(fill = Survived)) + geom_stratum() + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + scale_x_discrete(limits = c("Class", "Sex")) + facet_wrap(~ Age, scales = "free_y") ggalluvial/inst/examples/ex-alluvial-data.r0000644000176200001440000000563714166562215020534 0ustar liggesusers# Titanic data in alluvia format titanic_alluvia <- as.data.frame(Titanic) head(titanic_alluvia) is_alluvia_form(titanic_alluvia, weight = "Freq") # Titanic data in lodes format titanic_lodes <- to_lodes_form(titanic_alluvia, key = "x", value = "stratum", id = "alluvium", axes = 1:4) head(titanic_lodes) is_lodes_form(titanic_lodes, key = "x", value = "stratum", id = "alluvium", weight = "Freq") # again in lodes format, this time diffusing the `Class` variable titanic_lodes2 <- to_lodes_form(titanic_alluvia, key = variable, value = value, id = cohort, 1:3, diffuse = Class) head(titanic_lodes2) is_lodes_form(titanic_lodes2, key = variable, value = value, id = cohort, weight = Freq) # use `site` to separate data before lode testing is_lodes_form(titanic_lodes2, key = variable, value = value, id = Class, weight = Freq) is_lodes_form(titanic_lodes2, key = variable, value = value, id = Class, weight = Freq, site = cohort) # curriculum data in lodes format data(majors) head(majors) is_lodes_form(majors, key = "semester", value = "curriculum", id = "student") # curriculum data in alluvia format majors_alluvia <- to_alluvia_form(majors, key = "semester", value = "curriculum", id = "student") head(majors_alluvia) is_alluvia_form(majors_alluvia, tidyselect::starts_with("CURR")) # distill variables that vary within `id` values set.seed(1) majors$hypo_grade <- LETTERS[sample(5, size = nrow(majors), replace = TRUE)] majors_alluvia2 <- to_alluvia_form(majors, key = "semester", value = "curriculum", id = "student", distill = "most") head(majors_alluvia2) # options to distinguish strata at different axes gg <- ggplot(majors_alluvia, aes(axis1 = CURR1, axis2 = CURR7, axis3 = CURR13)) gg + geom_alluvium(aes(fill = as.factor(student)), width = 2/5, discern = TRUE) + geom_stratum(width = 2/5, discern = TRUE) + geom_text(stat = "stratum", discern = TRUE, aes(label = after_stat(stratum))) gg + geom_alluvium(aes(fill = as.factor(student)), width = 2/5, discern = FALSE) + geom_stratum(width = 2/5, discern = FALSE) + geom_text(stat = "stratum", discern = FALSE, aes(label = after_stat(stratum))) # warning when inappropriate ggplot(majors[majors$semester %in% paste0("CURR", c(1, 7, 13)), ], aes(x = semester, stratum = curriculum, alluvium = student, label = curriculum)) + geom_alluvium(aes(fill = as.factor(student)), width = 2/5, discern = TRUE) + geom_stratum(width = 2/5, discern = TRUE) + geom_text(stat = "stratum", discern = TRUE) ggalluvial/inst/doc/0000755000176200001440000000000015146567321014135 5ustar liggesusersggalluvial/inst/doc/ggalluvial.html0000644000176200001440000226732315146567314017173 0ustar liggesusers Alluvial Plots in ggplot2

Alluvial Plots in ggplot2

Jason Cory Brunson

2026-02-22

The {ggalluvial} package is a {ggplot2} extension for producing alluvial plots in a {tidyverse} framework. The design and functionality were originally inspired by the {alluvial} package and have benefitted from the feedback of many users. This vignette

  • defines the essential components of alluvial plots as used in the naming schemes and documentation (axis, alluvium, stratum, lode, flow),
  • describes the alluvial data structures recognized by {ggalluvial},
  • illustrates the new stats and geoms, and
  • showcases some popular variants on the theme and how to produce them.

Unlike most alluvial and related diagrams, the plots produced by {ggalluvial} are uniquely determined by the data set and statistical transformation. The distinction is detailed in this blog post.

Many other resources exist for visualizing categorical data in R, including several more basic plot types that are likely to more accurately convey proportions to viewers when the data are not so structured as to warrant an alluvial plot. In particular, check out Michael Friendly’s {vcd} and {vcdExtra} packages for a variety of statistically-motivated categorical data visualization techniques, Hadley Wickham’s {productplots} package and Haley Jeppson and Heike Hofmann’s descendant {ggmosaic} package for product or mosaic plots, and Nicholas Hamilton’s {ggtern} package for ternary coordinates. Other related packages are mentioned below.

Alluvial plots

Here’s a quintessential alluvial plot:

The next section details how the elements of this image encode information about the underlying dataset. For now, we use the image as a point of reference to define the following elements of a typical alluvial plot:

  • An axis is a dimension (variable) along which the data are vertically arranged at a fixed horizontal position. The plot above uses three categorical axes: Class, Sex, and Age.
  • The groups at each axis are depicted as opaque blocks called strata. For example, the Class axis contains four strata: 1st, 2nd, 3rd, and Crew.
  • Horizontal (x-) splines called alluvia span the width of the plot. In this plot, each alluvium corresponds to a fixed value of each axis variable, indicated by its vertical position at the axis, as well as of the Survived variable, indicated by its fill color.
  • The segments of the alluvia between pairs of adjacent axes are flows.
  • The alluvia intersect the strata at lodes. The lodes are not visualized in the above plot, but they can be inferred as filled rectangles extending the flows through the strata at each end of the plot or connecting the flows on either side of the center stratum.

As the examples in the next section will demonstrate, which of these elements are incorporated into an alluvial plot depends on both how the underlying data is structured and what the creator wants the plot to communicate.

Alluvial data

{ggalluvial} recognizes two formats of “alluvial data”, treated in detail in the following subsections, but which basically correspond to the “wide” and “long” formats of categorical repeated measures data. A third, tabular (or array), form is popular for storing data with multiple categorical dimensions, such as the Titanic and UCBAdmissions datasets.1 For consistency with tidy data principles and {ggplot2} conventions, {ggalluvial} does not accept tabular input; base::as.data.frame() converts such an array to an acceptable data frame.

Alluvia (wide) format

The wide format reflects the visual arrangement of an alluvial plot, but “untwisted”: Each row corresponds to a cohort of observations that take a specific value at each variable, and each variable has its own column. An additional column contains the quantity of each row, e.g. the number of observational units in the cohort, which may be used to control the heights of the strata.2 Basically, the wide format consists of one row per alluvium. This is the format into which the base function as.data.frame() transforms a frequency table, for instance the 3-dimensional UCBAdmissions dataset:

head(as.data.frame(UCBAdmissions), n = 12)
##       Admit Gender Dept Freq
## 1  Admitted   Male    A  512
## 2  Rejected   Male    A  313
## 3  Admitted Female    A   89
## 4  Rejected Female    A   19
## 5  Admitted   Male    B  353
## 6  Rejected   Male    B  207
## 7  Admitted Female    B   17
## 8  Rejected Female    B    8
## 9  Admitted   Male    C  120
## 10 Rejected   Male    C  205
## 11 Admitted Female    C  202
## 12 Rejected Female    C  391
is_alluvia_form(as.data.frame(UCBAdmissions), axes = 1:3, silent = TRUE)
## [1] TRUE

This format is inherited from the first release of {ggalluvial}, which modeled it after usage in {alluvial}: The user declares any number of axis variables, which stat_alluvium() and stat_stratum() recognize and process in a consistent way:3

ggplot(as.data.frame(UCBAdmissions),
       aes(y = Freq, axis1 = Gender, axis2 = Dept)) +
  geom_alluvium(aes(fill = Admit), width = 1/12) +
  geom_stratum(width = 1/12, fill = "black", color = "grey") +
  geom_label(stat = "stratum", aes(label = after_stat(stratum))) +
  scale_x_discrete(limits = c("Gender", "Dept"), expand = c(.05, .05)) +
  scale_fill_brewer(type = "qual", palette = "Set1") +
  ggtitle("UC Berkeley admissions and rejections, by sex and department")

An important feature of these plots is the meaningfulness of the vertical axis: No gaps are inserted between the strata, so the total height of the plot reflects the cumulative quantity of the observations. The plots produced by {ggalluvial} conform (somewhat; keep reading) to the “grammar of graphics” principles of {ggplot2}, and this prevents users from producing “free-floating” visualizations like the Sankey diagrams showcased here.4 {ggalluvial} parameters and native {ggplot2} functionality can also produce parallel sets plots, illustrated here using the HairEyeColor dataset:56

ggplot(as.data.frame(HairEyeColor),
       aes(y = Freq,
           axis1 = Hair, axis2 = Eye, axis3 = Sex)) +
  geom_alluvium(aes(fill = Eye),
                width = 1/8, knot.pos = 0, reverse = FALSE) +
  scale_fill_manual(values = c(Brown = "#70493D", Hazel = "#E2AC76",
                               Green = "#3F752B", Blue = "#81B0E4")) +
  guides(fill = "none") +
  geom_stratum(alpha = .25, width = 1/8, reverse = FALSE) +
  geom_text(stat = "stratum", aes(label = after_stat(stratum)),
            reverse = FALSE) +
  scale_x_continuous(breaks = 1:3, labels = c("Hair", "Eye", "Sex")) +
  coord_flip() +
  ggtitle("Eye colors of 592 subjects, by sex and hair color")
## Warning in to_lodes_form(data = data, axes = axis_ind, discern =
## params$discern): Some strata appear at multiple axes.
## Warning in to_lodes_form(data = data, axes = axis_ind, discern =
## params$discern): Some strata appear at multiple axes.
## Warning in to_lodes_form(data = data, axes = axis_ind, discern =
## params$discern): Some strata appear at multiple axes.

(The warning is due to the “Hair” and “Eye” axes having the value “Brown” in common.)

This format and functionality are useful for many applications and will be retained in future versions. They also involve some conspicuous deviations from {ggplot2} norms:

  • The axis[0-9]* position aesthetics are non-standard: they are not an explicit set of parameters but a family based on a regular expression pattern; and at least one, but no specific one, is required.
  • stat_alluvium() ignores any argument to the group aesthetic; instead, StatAlluvium$compute_panel() uses group to link the rows of the internally-transformed dataset that correspond to the same alluvium.
  • The horizontal axis must be manually corrected (using scale_x_discrete() or scale_x_continuous()) to reflect the implicit categorical variable identifying the axis.

Furthermore, format aesthetics like fill are necessarily fixed for each alluvium; they cannot, for example, change from axis to axis according to the value taken at each. This means that, although they can reproduce the branching-tree structure of parallel sets, this format cannot be used to produce alluvial plots with color schemes such as those featured here (“Controlling colors”), which are “reset” at each axis.

Note also that the stratum variable produced by stat_stratum() (called by geom_text()) is computed during the statistical transformation and must be recovered using after_stat() as a calculated aesthetic.

Lodes (long) format

The long format recognized by {ggalluvial} contains one row per lode, and can be understood as the result of “gathering” (in a deprecated {dplyr} sense) or “pivoting” (in the Microsoft Excel or current {dplyr} sense) the axis columns of a dataset in the alluvia format into a key-value pair of columns encoding the axis as the key and the stratum as the value. This format requires an additional indexing column that links the rows corresponding to a common cohort, i.e. the lodes of a single alluvium:

UCB_lodes <- to_lodes_form(as.data.frame(UCBAdmissions),
                           axes = 1:3,
                           id = "Cohort")
head(UCB_lodes, n = 12)
##    Freq Cohort     x  stratum
## 1   512      1 Admit Admitted
## 2   313      2 Admit Rejected
## 3    89      3 Admit Admitted
## 4    19      4 Admit Rejected
## 5   353      5 Admit Admitted
## 6   207      6 Admit Rejected
## 7    17      7 Admit Admitted
## 8     8      8 Admit Rejected
## 9   120      9 Admit Admitted
## 10  205     10 Admit Rejected
## 11  202     11 Admit Admitted
## 12  391     12 Admit Rejected
is_lodes_form(UCB_lodes, key = x, value = stratum, id = Cohort, silent = TRUE)
## [1] TRUE

The functions that convert data between wide (alluvia) and long (lodes) format include several parameters that help preserve ancillary information. See help("alluvial-data") for examples.

The same stat and geom can receive data in this format using a different set of positional aesthetics, also specific to {ggalluvial}:

  • x, the “key” variable indicating the axis to which the row corresponds, which are to be arranged along the horizontal axis;
  • stratum, the “value” taken by the axis variable indicated by x; and
  • alluvium, the indexing scheme that links the rows of a single alluvium.

Heights can vary from axis to axis, allowing users to produce bump charts like those showcased here.7 In these cases, the strata contain no more information than the alluvia and often are not plotted. For convenience, both stat_alluvium() and stat_flow() will accept arguments for x and alluvium even if none is given for stratum.8 As an example, we can group countries in the Refugees dataset by region, in order to compare refugee volumes at different scales:

data(Refugees, package = "alluvial")
country_regions <- c(
  Afghanistan = "Middle East",
  Burundi = "Central Africa",
  `Congo DRC` = "Central Africa",
  Iraq = "Middle East",
  Myanmar = "Southeast Asia",
  Palestine = "Middle East",
  Somalia = "Horn of Africa",
  Sudan = "Central Africa",
  Syria = "Middle East",
  Vietnam = "Southeast Asia"
)
Refugees$region <- country_regions[Refugees$country]
ggplot(data = Refugees,
       aes(x = year, y = refugees, alluvium = country)) +
  geom_alluvium(aes(fill = country, colour = country),
                alpha = .75, decreasing = FALSE, outline.type = "upper") +
  scale_x_continuous(breaks = seq(2003, 2013, 2)) +
  theme_bw() +
  theme(axis.text.x = element_text(angle = -30, hjust = 0)) +
  scale_fill_brewer(type = "qual", palette = "Set3") +
  scale_color_brewer(type = "qual", palette = "Set3") +
  facet_wrap(~ region, scales = "fixed") +
  ggtitle("refugee volume by country and region of origin")

The format allows us to assign aesthetics that change from axis to axis along the same alluvium, which is useful for repeated measures datasets. This requires generating a separate graphical object for each flow, as implemented in geom_flow(). The plot below uses a set of (changes to) students’ academic curricula over the course of several semesters. Since geom_flow() calls stat_flow() by default (see the next example), we override it with stat_alluvium() in order to track each student across all semesters:

data(majors)
majors$curriculum <- as.factor(majors$curriculum)
ggplot(majors,
       aes(x = semester, stratum = curriculum, alluvium = student,
           fill = curriculum, label = curriculum)) +
  scale_fill_brewer(type = "qual", palette = "Set2") +
  geom_flow(stat = "alluvium", lode.guidance = "frontback",
            color = "darkgray") +
  geom_stratum() +
  theme(legend.position = "bottom") +
  ggtitle("student curricula across several semesters")

The stratum heights y are unspecified, so each row is given unit height. This example demonstrates one way {ggalluvial} handles missing data. The alternative is to set the parameter na.rm to TRUE.9 Missing data handling (specifically, the order of the strata) also depends on whether the stratum variable is character or factor/numeric.

Finally, lode format gives us the option to aggregate the flows between adjacent axes, which may be appropriate when the transitions between adjacent axes are of primary importance. We can demonstrate this option on data from the influenza vaccination surveys conducted by the RAND American Life Panel. The data, including one question from each of three surveys, has been aggregated by response profile: Each “subject” (mapped to alluvium) actually represents a cohort of subjects who responded the same way on all three questions, and the size of each cohort (mapped to y) is recorded in “freq”.

data(vaccinations)
vaccinations <- transform(vaccinations,
                          response = factor(response, rev(levels(response))))
ggplot(vaccinations,
       aes(x = survey, stratum = response, alluvium = subject,
           y = freq,
           fill = response, label = response)) +
  scale_x_discrete(expand = c(.1, .1)) +
  geom_flow() +
  geom_stratum(alpha = .5) +
  geom_text(stat = "stratum", size = 3) +
  theme(legend.position = "none") +
  ggtitle("vaccination survey responses at three points in time")

This plot ignores any continuity between the flows between axes. This “memoryless” statistical transformation yields a less cluttered plot, in which at most one flow proceeds from each stratum at one axis to each stratum at the next, but at the cost of being able to track each cohort across the entire plot.

Appendix

sessioninfo::session_info()
## ─ Session info ───────────────────────────────────────────────────────────────
##  setting  value
##  version  R version 4.5.2 (2025-10-31)
##  os       macOS Tahoe 26.2
##  system   aarch64, darwin20
##  ui       X11
##  language (EN)
##  collate  C
##  ctype    en_US.UTF-8
##  tz       America/New_York
##  date     2026-02-22
##  pandoc   2.19 @ /opt/homebrew/bin/ (via rmarkdown)
##  quarto   1.8.25 @ /usr/local/bin/quarto
## 
## ─ Packages ───────────────────────────────────────────────────────────────────
##  package      * version date (UTC) lib source
##  bslib          0.9.0   2025-01-30 [3] CRAN (R 4.5.0)
##  cachem         1.1.0   2024-05-16 [3] CRAN (R 4.5.0)
##  cli            3.6.5   2025-04-23 [3] CRAN (R 4.5.0)
##  digest         0.6.39  2025-11-19 [3] CRAN (R 4.5.2)
##  dplyr          1.1.4   2023-11-17 [3] CRAN (R 4.5.0)
##  evaluate       1.0.5   2025-08-27 [3] CRAN (R 4.5.0)
##  farver         2.1.2   2024-05-13 [3] CRAN (R 4.5.0)
##  fastmap        1.2.0   2024-05-15 [3] CRAN (R 4.5.0)
##  generics       0.1.4   2025-05-09 [3] CRAN (R 4.5.0)
##  ggalluvial   * 0.12.6  2026-02-22 [1] local
##  ggplot2      * 4.0.2   2026-02-03 [3] CRAN (R 4.5.2)
##  glue           1.8.0   2024-09-30 [3] CRAN (R 4.5.0)
##  gtable         0.3.6   2024-10-25 [3] CRAN (R 4.5.0)
##  htmltools      0.5.9   2025-12-04 [3] CRAN (R 4.5.2)
##  jquerylib      0.1.4   2021-04-26 [3] CRAN (R 4.5.0)
##  jsonlite       2.0.0   2025-03-27 [3] CRAN (R 4.5.0)
##  knitr          1.51    2025-12-20 [3] CRAN (R 4.5.2)
##  labeling       0.4.3   2023-08-29 [3] CRAN (R 4.5.0)
##  lifecycle      1.0.5   2026-01-08 [3] CRAN (R 4.5.2)
##  magrittr       2.0.4   2025-09-12 [3] CRAN (R 4.5.0)
##  otel           0.2.0   2025-08-29 [3] CRAN (R 4.5.0)
##  pillar         1.11.1  2025-09-17 [3] CRAN (R 4.5.0)
##  pkgconfig      2.0.3   2019-09-22 [3] CRAN (R 4.5.0)
##  purrr          1.2.1   2026-01-09 [3] CRAN (R 4.5.2)
##  R6             2.6.1   2025-02-15 [3] CRAN (R 4.5.0)
##  RColorBrewer   1.1-3   2022-04-03 [3] CRAN (R 4.5.0)
##  rlang          1.1.7   2026-01-09 [3] CRAN (R 4.5.2)
##  rmarkdown      2.30    2025-09-28 [3] CRAN (R 4.5.0)
##  S7             0.2.1   2025-11-14 [3] CRAN (R 4.5.2)
##  sass           0.4.10  2025-04-11 [3] CRAN (R 4.5.0)
##  scales         1.4.0   2025-04-24 [3] CRAN (R 4.5.0)
##  sessioninfo    1.2.3   2025-02-05 [3] CRAN (R 4.5.0)
##  tibble         3.3.1   2026-01-11 [3] CRAN (R 4.5.2)
##  tidyr          1.3.2   2025-12-19 [3] CRAN (R 4.5.2)
##  tidyselect     1.2.1   2024-03-11 [3] CRAN (R 4.5.0)
##  vctrs          0.7.1   2026-01-23 [3] CRAN (R 4.5.2)
##  withr          3.0.2   2024-10-28 [3] CRAN (R 4.5.0)
##  xfun           0.56    2026-01-18 [3] CRAN (R 4.5.2)
##  yaml           2.3.12  2025-12-10 [3] CRAN (R 4.5.2)
## 
##  [1] /private/var/folders/4p/3cy0qmp15x9216qsqhh84kzm0000gn/T/RtmpqAXS9Z/Rinste3c54c7b608a
##  [2] /private/var/folders/4p/3cy0qmp15x9216qsqhh84kzm0000gn/T/RtmpLJJlUG/temp_libpathe3a419d138
##  [3] /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/library
##  * ── Packages attached to the search path.
## 
## ──────────────────────────────────────────────────────────────────────────────

  1. See Friendly’s tutorial, linked above, for a discussion.↩︎

  2. Previously, quantities were passed to the weight aesthetic rather than to y. This prevented scale_y_continuous() from correctly transforming scales, and anyway it was inconsistent with the behavior of geom_bar(). As of version 0.12.0, weight is an optional parameter used only by computed variables intended for labeling, not by polygonal graphical elements.↩︎

  3. Note that the spacing parameter width is set to the same value in each alluvial layer.↩︎

  4. The {ggforce} package includes parallel set geom and stat layers to produce similar diagrams that can be allowed to free-float.↩︎

  5. A greater variety of parallel sets plots are implemented in the {ggparallel} and {ggpcp} packages.↩︎

  6. Eye color hex codes are taken from Crayola’s Colors of the World crayons.↩︎

  7. If bumping is unnecessary, consider using geom_area() instead.↩︎

  8. stat_stratum() will similarly accept arguments for x and stratum without alluvium. If both strata and either alluvia or flows are to be plotted, though, all three parameters need arguments.↩︎

  9. Be sure to set na.rm consistently in each layer, in this case both the flows and the strata.↩︎

ggalluvial/inst/doc/ggalluvial.R0000644000176200001440000001143015146567313016407 0ustar liggesusers## ----setup, echo=FALSE, message=FALSE, results='hide'------------------------- library(ggalluvial) knitr::opts_chunk$set(fig.width = 6, fig.height = 4, fig.align = "center") ## ----example alluvial plot using Titanic dataset, echo=FALSE------------------ ggplot(data = to_lodes_form(as.data.frame(Titanic), key = "Demographic", axes = 1:3), aes(x = Demographic, stratum = stratum, alluvium = alluvium, y = Freq, label = stratum)) + scale_x_discrete(expand = c(.05, .05)) + geom_alluvium(aes(fill = Survived)) + geom_stratum() + geom_text(stat = "stratum") + ggtitle("passengers on the maiden voyage of the Titanic", "stratified by demographics and survival") ## ----alluvia format of Berkeley admissions dataset---------------------------- head(as.data.frame(UCBAdmissions), n = 12) is_alluvia_form(as.data.frame(UCBAdmissions), axes = 1:3, silent = TRUE) ## ----alluvial plot of UC Berkeley admissions dataset-------------------------- ggplot(as.data.frame(UCBAdmissions), aes(y = Freq, axis1 = Gender, axis2 = Dept)) + geom_alluvium(aes(fill = Admit), width = 1/12) + geom_stratum(width = 1/12, fill = "black", color = "grey") + geom_label(stat = "stratum", aes(label = after_stat(stratum))) + scale_x_discrete(limits = c("Gender", "Dept"), expand = c(.05, .05)) + scale_fill_brewer(type = "qual", palette = "Set1") + ggtitle("UC Berkeley admissions and rejections, by sex and department") ## ----parallel sets plot of hair and eye color dataset------------------------- ggplot(as.data.frame(HairEyeColor), aes(y = Freq, axis1 = Hair, axis2 = Eye, axis3 = Sex)) + geom_alluvium(aes(fill = Eye), width = 1/8, knot.pos = 0, reverse = FALSE) + scale_fill_manual(values = c(Brown = "#70493D", Hazel = "#E2AC76", Green = "#3F752B", Blue = "#81B0E4")) + guides(fill = "none") + geom_stratum(alpha = .25, width = 1/8, reverse = FALSE) + geom_text(stat = "stratum", aes(label = after_stat(stratum)), reverse = FALSE) + scale_x_continuous(breaks = 1:3, labels = c("Hair", "Eye", "Sex")) + coord_flip() + ggtitle("Eye colors of 592 subjects, by sex and hair color") ## ----lodes format of Berkeley admissions dataset------------------------------ UCB_lodes <- to_lodes_form(as.data.frame(UCBAdmissions), axes = 1:3, id = "Cohort") head(UCB_lodes, n = 12) is_lodes_form(UCB_lodes, key = x, value = stratum, id = Cohort, silent = TRUE) ## ----time series alluvia plot of refugees dataset----------------------------- data(Refugees, package = "alluvial") country_regions <- c( Afghanistan = "Middle East", Burundi = "Central Africa", `Congo DRC` = "Central Africa", Iraq = "Middle East", Myanmar = "Southeast Asia", Palestine = "Middle East", Somalia = "Horn of Africa", Sudan = "Central Africa", Syria = "Middle East", Vietnam = "Southeast Asia" ) Refugees$region <- country_regions[Refugees$country] ggplot(data = Refugees, aes(x = year, y = refugees, alluvium = country)) + geom_alluvium(aes(fill = country, colour = country), alpha = .75, decreasing = FALSE, outline.type = "upper") + scale_x_continuous(breaks = seq(2003, 2013, 2)) + theme_bw() + theme(axis.text.x = element_text(angle = -30, hjust = 0)) + scale_fill_brewer(type = "qual", palette = "Set3") + scale_color_brewer(type = "qual", palette = "Set3") + facet_wrap(~ region, scales = "fixed") + ggtitle("refugee volume by country and region of origin") ## ----alluvial plot of majors dataset------------------------------------------ data(majors) majors$curriculum <- as.factor(majors$curriculum) ggplot(majors, aes(x = semester, stratum = curriculum, alluvium = student, fill = curriculum, label = curriculum)) + scale_fill_brewer(type = "qual", palette = "Set2") + geom_flow(stat = "alluvium", lode.guidance = "frontback", color = "darkgray") + geom_stratum() + theme(legend.position = "bottom") + ggtitle("student curricula across several semesters") ## ----alluvial plot of vaccinations dataset------------------------------------ data(vaccinations) vaccinations <- transform(vaccinations, response = factor(response, rev(levels(response)))) ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + scale_x_discrete(expand = c(.1, .1)) + geom_flow() + geom_stratum(alpha = .5) + geom_text(stat = "stratum", size = 3) + theme(legend.position = "none") + ggtitle("vaccination survey responses at three points in time") ## ----session info------------------------------------------------------------- sessioninfo::session_info() ggalluvial/inst/doc/labels.rmd0000644000176200001440000001537114370022542016077 0ustar liggesusers--- title: "Labeling small strata" author: "Jason Cory Brunson" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{labeling small strata} %\VignetteEngine{knitr::rmarkdown} \usepackage[utf8]{inputenc} --- ## Setup This brief vignette uses the `vaccinations` dataset included in {ggalluvial}. As in [the technical introduction](http://corybrunson.github.io/ggalluvial/articles/ggalluvial.html), the order of the levels is reversed to be more intuitive. Objects from other {ggplot2} extensions are accessed via `::` and `:::`. ```{r setup} knitr::opts_chunk$set(fig.width = 6, fig.height = 4, fig.align = "center") library(ggalluvial) data(vaccinations) vaccinations <- transform(vaccinations, response = factor(response, rev(levels(response)))) ``` ## Problem The issue on the table: Strata are most helpful when they're overlaid with text labels. Yet the strata often vary in height, and the labels in length, to such a degree that fitting the text inside the strata at a uniform size renders them illegible. In principle, the user could treat `size` as a variable aesthetic and manually fit text to strata, but this is cumbersome, and doesn't help anyway in cases where large text is needed. To illustrate the problem, check out the plot below. It's by no means an egregious case, but it'll do. (For a more practical example, see [this question on StackOverflow](https://stackoverflow.com/questions/50720718/labelling-and-theme-of-ggalluvial-plot-in-r), which prompted this vignette.) ```{r raw} ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + scale_x_discrete(expand = c(.1, 0)) + geom_flow(width = 1/4) + geom_stratum(alpha = .5, width = 1/4) + geom_text(stat = "stratum", size = 4) + theme(legend.position = "none") + ggtitle("vaccination survey responses", "labeled using `geom_text()`") ``` ### Fix One option is to simply omit those labels that don't fit within their strata. In response to [an issue](https://github.com/corybrunson/ggalluvial/issues/27), `v0.9.2` includes parameters in `stat_stratum()` to exclude strata outside a specified height range; while few would use this to omit the rectangles themselves, it can be used in tandem with `geom_text()` to shirk this problem, at least when the labels are concise: ```{r omit} ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + scale_x_discrete(expand = c(.1, 0)) + geom_flow(width = 1/4) + geom_stratum(alpha = .5, width = 1/4) + geom_text(stat = "stratum", size = 4, min.y = 100) + theme(legend.position = "none") + ggtitle( "vaccination survey responses", "labeled using `geom_text()` with `min.y = 100`" ) ``` This is a useful fix for some cases. Still, if the goal is a publication-ready graphic, then it reaffirms the need for more adaptable and elegant solutions. Fortunately, two wonderful packages deliver with, shall we say, flowing colors. ## Solutions Two {ggplot2} extensions are well-suited to this problem: [{ggrepel}](https://github.com/slowkow/ggrepel) and [{ggfittext}](https://github.com/wilkox/ggfittext). They provide new geom layers that use the output of existing stat layers to situate text: `ggrepel::geom_text_repel()` takes the same aesthetics as `ggplot2::geom_text()`, namely `x`, `y`, and `label`. In contrast, `ggfittext::geom_fit_text()` only specifically requires `label` but also needs enough information to determine the rectangle that will contain the text. This can be encoded as `xmin` and `xmax` or as `x` and `width` for the horizontal direction, and as `ymin` and `ymax` or as `y` and `height` for the vertical direction. Conveniently, `ggalluvial::stat_stratum()` produces more than enough information for both geoms, including `x`, `xmin`, `xmax`, and their vertical counterparts. All this can be gleaned from the `ggproto` objects that construct the layers: ```{r aesthetics} print(ggrepel::GeomTextRepel$required_aes) print(ggfittext:::GeomFitText$required_aes) print(ggfittext:::GeomFitText$setup_data) print(StatStratum$compute_panel) ``` I reached the specific solutions through trial and error. They may not be the best tricks for most cases, but they demonstrate what these packages can do. For many more examples, see the respective package vignettes: [for {ggrepel}](https://CRAN.R-project.org/package=ggrepel/vignettes/ggrepel.html), and [for {ggfittext}](https://CRAN.R-project.org/package=ggfittext/vignettes/introduction-to-ggfittext.html). ### Solution 1: {ggrepel} {ggrepel} is most often (in my experience) used to repel text away from symbols in a scatterplot, in whatever directions prevent them from overlapping the symbols and each other. In this case, however, it makes much more sense to align them vertically a fixed horizontal distance (`nudge_x`) away from the strata and repel them vertically from each other (`direction = "y"`) just enough to print them without overlap. It takes an extra bit of effort to render text _only_ for the strata at the first (or at the last) axis, but the result is worth it. ```{r ggrepel} ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + scale_x_discrete(expand = c(.4, 0)) + geom_flow(width = 1/4) + geom_stratum(alpha = .5, width = 1/4) + scale_linetype_manual(values = c("blank", "solid")) + ggrepel::geom_text_repel( aes(label = ifelse(as.numeric(survey) == 1, as.character(response), NA)), stat = "stratum", size = 4, direction = "y", nudge_x = -.5 ) + ggrepel::geom_text_repel( aes(label = ifelse(as.numeric(survey) == 3, as.character(response), NA)), stat = "stratum", size = 4, direction = "y", nudge_x = .5 ) + theme(legend.position = "none") + ggtitle("vaccination survey responses", "labeled using `geom_text_repel()`") ``` ### Solution 2: {ggfittext} {ggfittext} is simplicity itself: The strata are just rectangles, so no more parameter specifications are necessary to fit the text into them. One key parameter is `min.size`, which defaults to `4` and controls how small the text is allowed to get without being omitted. ```{r ggfittext} ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + scale_x_discrete(expand = c(.1, 0)) + geom_flow(width = 1/4) + geom_stratum(alpha = .5, width = 1/4) + ggfittext::geom_fit_text(stat = "stratum", width = 1/4, min.size = 3) + theme(legend.position = "none") + ggtitle("vaccination survey responses", "labeled using `geom_fit_text()`") ``` Note that this solution requires {ggfittext} v0.6.0. ## Appendix ```{r session info} sessioninfo::session_info() ``` ggalluvial/inst/doc/ggalluvial.rmd0000644000176200001440000004101215146427613016765 0ustar liggesusers--- title: "Alluvial Plots in ggplot2" author: "Jason Cory Brunson" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{alluvial plots in ggplot2} %\VignetteEngine{knitr::rmarkdown} \usepackage[utf8]{inputenc} --- The {ggalluvial} package is a {ggplot2} extension for producing alluvial plots in a [{tidyverse}](https://github.com/tidyverse) framework. The design and functionality were originally inspired by the [{alluvial}](https://github.com/mbojan/alluvial) package and have benefitted from the feedback of many users. This vignette - defines the essential components of alluvial plots as used in the naming schemes and documentation (_axis_, _alluvium_, _stratum_, _lode_, _flow_), - describes the alluvial data structures recognized by {ggalluvial}, - illustrates the new stats and geoms, and - showcases some popular variants on the theme and how to produce them. Unlike most alluvial and related diagrams, the plots produced by {ggalluvial} are uniquely determined by the data set and statistical transformation. The distinction is detailed in [this blog post](https://corybrunson.github.io/2019/09/13/flow-taxonomy/). Many other resources exist for visualizing categorical data in R, including several more basic plot types that are likely to more accurately convey proportions to viewers when the data are not so structured as to warrant an alluvial plot. In particular, check out Michael Friendly's [{vcd} and {vcdExtra} packages](https://friendly.github.io/vcdExtra/) for a variety of statistically-motivated categorical data visualization techniques, Hadley Wickham's [{productplots} package](https://github.com/hadley/productplots) and Haley Jeppson and Heike Hofmann's descendant [{ggmosaic} package](https://haleyjeppson.github.io/ggmosaic/) for product or mosaic plots, and Nicholas Hamilton's [{ggtern} package](https://bitbucket.org/nicholasehamilton/ggtern/) for ternary coordinates. Other related packages are mentioned below. ```{r setup, echo=FALSE, message=FALSE, results='hide'} library(ggalluvial) knitr::opts_chunk$set(fig.width = 6, fig.height = 4, fig.align = "center") ``` ## Alluvial plots Here's a quintessential alluvial plot: ```{r example alluvial plot using Titanic dataset, echo=FALSE} ggplot(data = to_lodes_form(as.data.frame(Titanic), key = "Demographic", axes = 1:3), aes(x = Demographic, stratum = stratum, alluvium = alluvium, y = Freq, label = stratum)) + scale_x_discrete(expand = c(.05, .05)) + geom_alluvium(aes(fill = Survived)) + geom_stratum() + geom_text(stat = "stratum") + ggtitle("passengers on the maiden voyage of the Titanic", "stratified by demographics and survival") ``` The next section details how the elements of this image encode information about the underlying dataset. For now, we use the image as a point of reference to define the following elements of a typical alluvial plot: - An _axis_ is a dimension (variable) along which the data are vertically arranged at a fixed horizontal position. The plot above uses three categorical axes: `Class`, `Sex`, and `Age`. - The groups at each axis are depicted as opaque blocks called _strata_. For example, the `Class` axis contains four strata: `1st`, `2nd`, `3rd`, and `Crew`. - Horizontal (x-) splines called _alluvia_ span the width of the plot. In this plot, each alluvium corresponds to a fixed value of each axis variable, indicated by its vertical position at the axis, as well as of the `Survived` variable, indicated by its fill color. - The segments of the alluvia between pairs of adjacent axes are _flows_. - The alluvia intersect the strata at _lodes_. The lodes are not visualized in the above plot, but they can be inferred as filled rectangles extending the flows through the strata at each end of the plot or connecting the flows on either side of the center stratum. As the examples in the next section will demonstrate, which of these elements are incorporated into an alluvial plot depends on both how the underlying data is structured and what the creator wants the plot to communicate. ## Alluvial data {ggalluvial} recognizes two formats of "alluvial data", treated in detail in the following subsections, but which basically correspond to the "wide" and "long" formats of categorical repeated measures data. A third, tabular (or array), form is popular for storing data with multiple categorical dimensions, such as the `Titanic` and `UCBAdmissions` datasets.[^tableform] For consistency with tidy data principles and {ggplot2} conventions, {ggalluvial} does not accept tabular input; `base::as.data.frame()` converts such an array to an acceptable data frame. [^tableform]: See Friendly's tutorial, linked above, for a discussion. ### Alluvia (wide) format The wide format reflects the visual arrangement of an alluvial plot, but "untwisted": Each row corresponds to a cohort of observations that take a specific value at each variable, and each variable has its own column. An additional column contains the quantity of each row, e.g. the number of observational units in the cohort, which may be used to control the heights of the strata.[^weight-y] Basically, the wide format consists of _one row per alluvium_. This is the format into which the base function `as.data.frame()` transforms a frequency table, for instance the 3-dimensional `UCBAdmissions` dataset: ```{r alluvia format of Berkeley admissions dataset} head(as.data.frame(UCBAdmissions), n = 12) is_alluvia_form(as.data.frame(UCBAdmissions), axes = 1:3, silent = TRUE) ``` This format is inherited from the first release of {ggalluvial}, which modeled it after usage in {alluvial}: The user declares any number of axis variables, which `stat_alluvium()` and `stat_stratum()` recognize and process in a consistent way:[^width] [^width]: Note that the spacing parameter `width` is set to the same value in each alluvial layer. ```{r alluvial plot of UC Berkeley admissions dataset} ggplot(as.data.frame(UCBAdmissions), aes(y = Freq, axis1 = Gender, axis2 = Dept)) + geom_alluvium(aes(fill = Admit), width = 1/12) + geom_stratum(width = 1/12, fill = "black", color = "grey") + geom_label(stat = "stratum", aes(label = after_stat(stratum))) + scale_x_discrete(limits = c("Gender", "Dept"), expand = c(.05, .05)) + scale_fill_brewer(type = "qual", palette = "Set1") + ggtitle("UC Berkeley admissions and rejections, by sex and department") ``` An important feature of these plots is the meaningfulness of the vertical axis: No gaps are inserted between the strata, so the total height of the plot reflects the cumulative quantity of the observations. The plots produced by {ggalluvial} conform (somewhat; keep reading) to the "grammar of graphics" principles of {ggplot2}, and this prevents users from producing "free-floating" visualizations like the Sankey diagrams showcased [here](https://developers.google.com/chart/interactive/docs/gallery/sankey).[^ggforce] {ggalluvial} parameters and native {ggplot2} functionality can also produce [parallel sets](https://eagereyes.org/parallel-sets) plots, illustrated here using the `HairEyeColor` dataset:[^ggparallel][^crayola] [^ggforce]: [The {ggforce} package](https://ggforce.data-imaginist.com/) includes parallel set geom and stat layers to produce similar diagrams that can be allowed to free-float. [^ggparallel]: A greater variety of parallel sets plots are implemented in the [{ggparallel}](https://github.com/heike/ggparallel) and [{ggpcp}](https://github.com/yaweige/ggpcp) packages. [^crayola]: Eye color hex codes are taken from [Crayola's Colors of the World crayons](https://en.wikipedia.org/wiki/List_of_Crayola_crayon_colors). ```{r parallel sets plot of hair and eye color dataset} ggplot(as.data.frame(HairEyeColor), aes(y = Freq, axis1 = Hair, axis2 = Eye, axis3 = Sex)) + geom_alluvium(aes(fill = Eye), width = 1/8, knot.pos = 0, reverse = FALSE) + scale_fill_manual(values = c(Brown = "#70493D", Hazel = "#E2AC76", Green = "#3F752B", Blue = "#81B0E4")) + guides(fill = "none") + geom_stratum(alpha = .25, width = 1/8, reverse = FALSE) + geom_text(stat = "stratum", aes(label = after_stat(stratum)), reverse = FALSE) + scale_x_continuous(breaks = 1:3, labels = c("Hair", "Eye", "Sex")) + coord_flip() + ggtitle("Eye colors of 592 subjects, by sex and hair color") ``` (The warning is due to the "Hair" and "Eye" axes having the value "Brown" in common.) This format and functionality are useful for many applications and will be retained in future versions. They also involve some conspicuous deviations from {ggplot2} norms: - The `axis[0-9]*` position aesthetics are non-standard: they are not an explicit set of parameters but a family based on a regular expression pattern; and at least one, but no specific one, is required. - `stat_alluvium()` ignores any argument to the `group` aesthetic; instead, `StatAlluvium$compute_panel()` uses `group` to link the rows of the internally-transformed dataset that correspond to the same alluvium. - The horizontal axis must be manually corrected (using `scale_x_discrete()` or `scale_x_continuous()`) to reflect the implicit categorical variable identifying the axis. Furthermore, format aesthetics like `fill` are necessarily fixed for each alluvium; they cannot, for example, change from axis to axis according to the value taken at each. This means that, although they can reproduce the branching-tree structure of parallel sets, this format cannot be used to produce alluvial plots with color schemes such as those featured [here](https://developers.google.com/chart/interactive/docs/gallery/sankey) ("Controlling colors"), which are "reset" at each axis. Note also that the `stratum` variable produced by `stat_stratum()` (called by `geom_text()`) is computed during the statistical transformation and must be recovered using `after_stat()` as a [calculated aesthetic](https://corybrunson.github.io/2020/04/17/calculate-aesthetics/). ### Lodes (long) format The long format recognized by {ggalluvial} contains _one row per lode_, and can be understood as the result of "gathering" (in a deprecated {dplyr} sense) or "pivoting" (in the Microsoft Excel or current {dplyr} sense) the axis columns of a dataset in the alluvia format into a key-value pair of columns encoding the axis as the key and the stratum as the value. This format requires an additional indexing column that links the rows corresponding to a common cohort, i.e. the lodes of a single alluvium: ```{r lodes format of Berkeley admissions dataset} UCB_lodes <- to_lodes_form(as.data.frame(UCBAdmissions), axes = 1:3, id = "Cohort") head(UCB_lodes, n = 12) is_lodes_form(UCB_lodes, key = x, value = stratum, id = Cohort, silent = TRUE) ``` The functions that convert data between wide (alluvia) and long (lodes) format include several parameters that help preserve ancillary information. See `help("alluvial-data")` for examples. The same stat and geom can receive data in this format using a different set of positional aesthetics, also specific to {ggalluvial}: - `x`, the "key" variable indicating the axis to which the row corresponds, which are to be arranged along the horizontal axis; - `stratum`, the "value" taken by the axis variable indicated by `x`; and - `alluvium`, the indexing scheme that links the rows of a single alluvium. Heights can vary from axis to axis, allowing users to produce bump charts like those showcased [here](https://imgur.com/gallery/gI5p7).[^geom-area] In these cases, the strata contain no more information than the alluvia and often are not plotted. For convenience, both `stat_alluvium()` and `stat_flow()` will accept arguments for `x` and `alluvium` even if none is given for `stratum`.[^arguments] As an example, we can group countries in the `Refugees` dataset by region, in order to compare refugee volumes at different scales: [^geom-area]: If bumping is unnecessary, consider using [`geom_area()`](https://r-graph-gallery.com/136-stacked-area-chart) instead. [^arguments]: `stat_stratum()` will similarly accept arguments for `x` and `stratum` without `alluvium`. If both strata and either alluvia or flows are to be plotted, though, all three parameters need arguments. ```{r time series alluvia plot of refugees dataset} data(Refugees, package = "alluvial") country_regions <- c( Afghanistan = "Middle East", Burundi = "Central Africa", `Congo DRC` = "Central Africa", Iraq = "Middle East", Myanmar = "Southeast Asia", Palestine = "Middle East", Somalia = "Horn of Africa", Sudan = "Central Africa", Syria = "Middle East", Vietnam = "Southeast Asia" ) Refugees$region <- country_regions[Refugees$country] ggplot(data = Refugees, aes(x = year, y = refugees, alluvium = country)) + geom_alluvium(aes(fill = country, colour = country), alpha = .75, decreasing = FALSE, outline.type = "upper") + scale_x_continuous(breaks = seq(2003, 2013, 2)) + theme_bw() + theme(axis.text.x = element_text(angle = -30, hjust = 0)) + scale_fill_brewer(type = "qual", palette = "Set3") + scale_color_brewer(type = "qual", palette = "Set3") + facet_wrap(~ region, scales = "fixed") + ggtitle("refugee volume by country and region of origin") ``` The format allows us to assign aesthetics that change from axis to axis along the same alluvium, which is useful for repeated measures datasets. This requires generating a separate graphical object for each flow, as implemented in `geom_flow()`. The plot below uses a set of (changes to) students' academic curricula over the course of several semesters. Since `geom_flow()` calls `stat_flow()` by default (see the next example), we override it with `stat_alluvium()` in order to track each student across all semesters: ```{r alluvial plot of majors dataset} data(majors) majors$curriculum <- as.factor(majors$curriculum) ggplot(majors, aes(x = semester, stratum = curriculum, alluvium = student, fill = curriculum, label = curriculum)) + scale_fill_brewer(type = "qual", palette = "Set2") + geom_flow(stat = "alluvium", lode.guidance = "frontback", color = "darkgray") + geom_stratum() + theme(legend.position = "bottom") + ggtitle("student curricula across several semesters") ``` The stratum heights `y` are unspecified, so each row is given unit height. This example demonstrates one way {ggalluvial} handles missing data. The alternative is to set the parameter `na.rm` to `TRUE`.[^na.rm] Missing data handling (specifically, the order of the strata) also depends on whether the `stratum` variable is character or factor/numeric. [^na.rm]: Be sure to set `na.rm` consistently in each layer, in this case both the flows and the strata. Finally, lode format gives us the option to aggregate the flows between adjacent axes, which may be appropriate when the transitions between adjacent axes are of primary importance. We can demonstrate this option on data from the influenza vaccination surveys conducted by the [RAND American Life Panel](https://alpdata.rand.org/). The data, including one question from each of three surveys, has been aggregated by response profile: Each "subject" (mapped to `alluvium`) actually represents a cohort of subjects who responded the same way on all three questions, and the size of each cohort (mapped to `y`) is recorded in "freq". ```{r alluvial plot of vaccinations dataset} data(vaccinations) vaccinations <- transform(vaccinations, response = factor(response, rev(levels(response)))) ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + scale_x_discrete(expand = c(.1, .1)) + geom_flow() + geom_stratum(alpha = .5) + geom_text(stat = "stratum", size = 3) + theme(legend.position = "none") + ggtitle("vaccination survey responses at three points in time") ``` This plot ignores any continuity between the flows between axes. This "memoryless" statistical transformation yields a less cluttered plot, in which at most one flow proceeds from each stratum at one axis to each stratum at the next, but at the cost of being able to track each cohort across the entire plot. ## Appendix ```{r session info} sessioninfo::session_info() ``` [^weight-y]: Previously, quantities were passed to the `weight` aesthetic rather than to `y`. This prevented `scale_y_continuous()` from correctly transforming scales, and anyway it was inconsistent with the behavior of `geom_bar()`. As of version 0.12.0, `weight` is an optional parameter used only by computed variables intended for labeling, not by polygonal graphical elements. ggalluvial/inst/doc/shiny.Rmd0000644000176200001440000005112114370022542015720 0ustar liggesusers--- title: "Tooltips for ggalluvial plots in Shiny apps" author: "Quentin D. Read" date: "`r Sys.Date()`" output: rmarkdown::html_vignette: self_contained: no runtime: shiny vignette: > %\VignetteIndexEntry{ggalluvial in Shiny apps} %\VignetteEngine{knitr::rmarkdown} \usepackage[utf8]{inputenc} --- ```{r setup, echo = FALSE, message = FALSE, warning = FALSE} knitr::opts_chunk$set(fig.width = 6, fig.height = 3, fig.align = "center") library(ggalluvial) pdf(NULL) ``` ## Problem In an interactive visualization, it is visually cleaner and better for interpretation if labels and other information appear as "tooltips" when the user hovers over or clicks on elements of the plot, rather than displaying all the labels on the plot at one time. However, the {ggalluvial} package does not natively include this functionality. It is possible to enable this using functions from several other packages. This vignette illustrates how to create Shiny apps that display an alluvial plot with tooltips that appear when the user hovers over two different plot elements: strata created with `geom_stratum()` and alluvia created with `geom_alluvium()`. An example is provided for wide-format alluvial data (the `UCBAdmissions` dataset) and long-format alluvial data (the `vaccinations` dataset). The tooltips that appear when the user hovers over elements of the plot show a text label and the count in each group. If the user hovers or clicks somewhere inside a ggplot panel, Shiny automatically returns information about the location of the mouse cursor *in plot coordinates*. That means the main work we have to do is to extract or manually recalculate the coordinates of the different plot elements. With that information, we can determine which plot element the cursor is hovering over and display the appropriate information in the tooltip or other output method. _Note:_ The app demonstrated here depends on the packages {htmltools} and {sp}, in addition of course to {ggalluvial} and {shiny}. Please be aware that all of these packages will need to be installed on the server where your Shiny app is running. ### Hovering over and clicking on strata Enabling hovering over and clicking on strata is straightforward because of their rectangular shape. We only need the minimum and maximum `x` and `y` coordinates for each of the rectangles. The rectangles are evenly spaced along the x-axis, centered on positive integers beginning with 1. The width is set in `geom_stratum()` so, for example, we know that the x-coordinates of the first stratum are `c(1 - width/2, 1 + width/2)`. The y-coordinates can be determined from the number of rows in the input data multiplied by their weights. ### Hovering over and clicking on alluvia Hovering over and clicking on alluvia are more difficult because the shapes of the alluvia are more complex. The default shape of the polygons includes an `xspline` curve drawn using the {grid} package. We need to manually reconstruct the coordinates of the polygons, then use `sp::pointInPolygon()` to detect which, if any, polygons the cursor is over. ## App with wide-format alluvial data The app is embedded below, followed by a walkthrough of the source code. If you aren't connected to the internet, or if you loaded this vignette using `vignette('shiny', package = 'ggalluvial')` rather than `browseVignettes(package = 'ggalluvial')`, the app will not display in the window above. You can view the app locally by running this line of code in your console: ```{r run wide app locally, eval = FALSE} shiny::shinyAppDir(system.file("examples/ex-shiny-wide-data", package="ggalluvial")) ``` ## Structure of the example app Here, we will go over each section of the code in detail. The full source code is included in the package's `examples` directory. The app first (1) loads the data and (2) builds the plot. Then, (3) information is extracted from the built plot object to (4) manually recalculate the coordinates of the polygons that make up the plot. Internally, {ggalluvial} uses the {grid} package to draw the polygons, so the next steps are (5) to define the minima and maxima of the x and y axes in {grid} units and the units that appear on the plot's coordinate system, and (6) to convert the polygon coordinates from {grid} units plot units. Next, the user interface is defined, including output of (7) the plot image and (8) the tooltip. The final block of code is the server function, which first (9) renders the plot. Finally, the tooltip is defined. This includes (10) logic to determine whether the mouse cursor is inside the plot panel, then (11) whether it is hovering over a stratum, (12) an alluvium, or neither, based on the mouse coordinates provided by Shiny. If the mouse is hovering over a plot element, the app finds appropriate information and prints it in a small "tooltip" box next to the mouse cursor (11b and 12b). This is the structure of the app in pseudocode. ```{r pseudocode, eval = FALSE} '<(1) Load data.>' '<(2) Create "ggplot" object for alluvial plot and build it.>' '<(3) Extract data from built plot object used to create alluvium polygons.>' for (polygon in polygons) { '<(4) Use polygon splines to generate coordinates of alluvium boundaries.>' } '<(5) Define range of coordinates in grid units and plot units.>' for (polygon in polygons) { '<(6) Convert coordinates from grid units to plot units.>' } ui <- fluidPage( '<(7) Output plot with hovering enabled.>' '<(8) Output tooltip.>' ) server <- function(input, output, session) { output$alluvial_plot <- renderPlot({ '<(9) Render the plot.>' }) output$tooltip <- renderText({ if ('<(10) mouse cursor is within the plot panel>') { if ('<(11) mouse cursor is within a stratum box>') { '<(11b) Render stratum tooltip.>' } else { if ('<(12) mouse cursor is within an alluvium polygon>') { '<(12b) Render alluvium tooltip.>' } } } }) } ``` ### Loading data The UC-Berkeley admissions dataset, `UCBAdmissions`, is used in this example. After loading the necessary packages, the first thing we do in the app is load the data and coerce from array to data frame. ```{r load dataset, eval = FALSE} data(UCBAdmissions) ucb_admissions <- as.data.frame(UCBAdmissions) ``` Next we set `offset`, the distance from cursor to tooltip, in pixels, in both x and y directions. We also set `node_width` and `alluvium_width` here, which are used as arguments to `geom_stratum()` and `geom_alluvium()` below, and again later to determine whether the mouse cursor is hovering over a stratum/alluvium. ```{r set options, eval = FALSE} # Offset, in pixels, for location of tooltip relative to mouse cursor, # in both x and y direction. offset <- 5 # Width of node boxes node_width <- 1/4 # Width of alluvia alluvium_width <- 1/3 ``` ### Drawing the plot and extracting coordinates Next, we create the `ggplot` object for the alluvial plot, then we call the `ggplot_build()` function to build the plot without displaying it. ```{r draw and build plot, eval = FALSE} # Draw plot. p <- ggplot(ucb_admissions, aes(y = Freq, axis1 = Gender, axis2 = Dept)) + geom_alluvium(aes(fill = Admit), knot.pos = 1/4, width = alluvium_width) + geom_stratum(width = node_width, reverse = TRUE, fill = 'black', color = 'grey') + geom_label(aes(label = after_stat(stratum)), stat = "stratum", reverse = TRUE, size = rel(2)) + theme_bw() + scale_fill_brewer(type = "qual", palette = "Set1") + scale_x_discrete(limits = c("Gender", "Dept"), expand = c(.05, .05)) + scale_y_continuous(expand = c(0, 0)) + ggtitle("UC Berkeley admissions and rejections", "by sex and department") + theme(plot.title = element_text(size = rel(1)), plot.subtitle = element_text(size = rel(1)), legend.position = 'bottom') # Build the plot. pbuilt <- ggplot_build(p) ``` Now for the hard part: reverse-engineering the coordinates of the alluvia polygons. This makes use of `pbuilt$data[[1]]`, a data frame with the individual elements of the alluvial plot. We add an additional column for `width` using the value we set above, then split the data frame by group (groups correspond to the individual alluvium polygons). We apply the function `data_to_alluvium()` to each element of the list to get the coordinates of the "skeleton" of the x-spline curve. Then, we pass these coordinates to the function `grid::xsplineGrob()` to fill in the smooth spline curves and convert them into a {grid} object. We pass the resulting object to `grid::xsplinePoints()`, which converts back into numeric vectors. At this point we now have the coordinates of the alluvium polygons. The object `xspline_points` is a list with length equal to the number of alluvium polygons in the plot. Each element of the list is a list with elements `x` and `y`, which are numeric vectors. ```{r get xsplines and draw curves, eval = FALSE} # Add width parameter, and then convert built plot data to xsplines data_draw <- transform(pbuilt$data[[1]], width = alluvium_width) groups_to_draw <- split(data_draw, data_draw$group) group_xsplines <- lapply(groups_to_draw, data_to_alluvium) # Convert xspline coordinates to grid object. xspline_coords <- lapply( group_xsplines, function(coords) grid::xsplineGrob(x = coords$x, y = coords$y, shape = coords$shape, open = FALSE) ) # Use grid::xsplinePoints to draw the curve for each polygon xspline_points <- lapply(xspline_coords, grid::xsplinePoints) ``` The coordinates we have are in {grid} plotting units but we need to convert them into the same units as the axes on the plot. We do this by determining the range of the x and y-axes in {grid} units (`xrange_old` and `yrange_old`). Then we fix the range of the x axis as 1 to the number of strata, adjusted by half the alluvium width on each side. Next we fix the range of the y-axis to the sum of the counts across all alluvia at one node. ```{r get coordinate ranges, eval = FALSE} # Define the x and y axis limits in grid coordinates (old) and plot # coordinates (new) xrange_old <- range(unlist(lapply( xspline_points, function(pts) as.numeric(pts$x) ))) yrange_old <- range(unlist(lapply( xspline_points, function(pts) as.numeric(pts$y) ))) xrange_new <- c(1 - alluvium_width/2, max(pbuilt$data[[1]]$x) + alluvium_width/2) yrange_new <- c(0, sum(pbuilt$data[[2]]$count[pbuilt$data[[2]]$x == 1])) ``` We define a function `new_range_transform()` inline and apply it to each set of coordinates. This returns another list, `polygon_coords`, with the same structure as `xspline_points`. Now we have the coordinates of the polygons in plot units! ```{r transform coordinates, eval = FALSE} # Define function to convert grid graphics coordinates to data coordinates new_range_transform <- function(x_old, range_old, range_new) { (x_old - range_old[1])/(range_old[2] - range_old[1]) * (range_new[2] - range_new[1]) + range_new[1] } # Using the x and y limits, convert the grid coordinates into plot coordinates. polygon_coords <- lapply(xspline_points, function(pts) { x_trans <- new_range_transform(x_old = as.numeric(pts$x), range_old = xrange_old, range_new = xrange_new) y_trans <- new_range_transform(x_old = as.numeric(pts$y), range_old = yrange_old, range_new = yrange_new) list(x = x_trans, y = y_trans) }) ``` ### User interface The app includes a minimal user interface with two output elements. ```{r ui, eval = FALSE} ui <- fluidPage( fluidRow(tags$div( style = "position: relative;", plotOutput("alluvial_plot", height = "650px", hover = hoverOpts(id = "plot_hover") ), htmlOutput("tooltip"))) ) ``` The elements are: - a `plotOutput` with the argument `hover` defined, to enable behavior determined by the cursor's plot coordinates whenever the user hovers over the plot. - an `htmlOutput` for the tooltip that appears next to the cursor on hover. The elements are wrapped in a `fluidRow()` and a `div()` tag. _Note:_ This vignette only illustrates how to display output when the user hovers over an element. If you want to display output when the user clicks on an element, the corresponding argument to `plotOutput()` is `click = clickOpts(id = "plot_click")`. This will return the location of the mouse cursor in plot coordinates when the user clicks somewhere within the plot panel. _Also Note:_ In the example presented here, all of the plot drawing and coordinate extracting code is outside the `server()` function, because the plot itself does not change with user input. However if you are building an app where the plot changes in response to user input, for example a menu of options of which variables to display, the plot drawing code has to be inside the `renderPlot()` expression. This means that the coordinates may need to be recalculated each time the user input changes as well. In that case, you may need to use the global assignment operator `<<-` so that the coordinates are accessible outside the `renderPlot()` expression. ### Server function In the server function, we first call `renderPlot()` to draw the plot in the app window. ```{r renderPlot, eval = FALSE} output$alluvial_plot <- renderPlot(p, res = 200) ``` Next, we define the tooltip with a `renderText()` expression. Within that expression, we first extract the cursor's plot coordinates from the user input. We determine whether the cursor is hovering over a stratum and if so, display the appropriate tooltip. ![screenshot of tooltip on stratum](https://raw.githubusercontent.com/corybrunson/ggalluvial/main/vignettes/img/hover_stratum.png) If the mouse cursor is not hovering over a stratum, we determine whether it is hovering over an alluvium polygon and if so, display different information in the tooltip. ![screenshot of tooltip on alluvium](https://raw.githubusercontent.com/corybrunson/ggalluvial/main/vignettes/img/hover_alluvium.png) If the mouse cursor is hovering over an empty region of the plot, `renderText()` returns nothing and no tooltip appears. ![screenshot of cursor over empty region](https://raw.githubusercontent.com/corybrunson/ggalluvial/main/vignettes/img/hover_empty_area.png) Let's take a deeper dive into the logic used to determine the text that appears in the tooltip. First, we check whether the cursor is inside the plot panel. If it is not, the element `plot_hover` of the input will be `NULL`. In that case `renderText()` will return nothing and no tooltip will appear. ```{r, eval = FALSE} output$tooltip <- renderText( if(!is.null(input$plot_hover)) { ... } ... ) ``` #### Hovering over a stratum Next, we check whether the cursor is over a stratum. We round the x-coordinate of the mouse cursor in data units to the nearest integer, then determine whether the x-coordinate is within `node_width/2` of that integer. If so, the mouse cursor is horizontally within the box. Here the `if`-`else` statement includes behavior to display the tooltip for a stratum if true, and an alluvium if false. ```{r, eval = FALSE} hover <- input$plot_hover x_coord <- round(hover$x) if(abs(hover$x - x_coord) < (node_width / 2)) { ... } else { ... } ``` If the condition is true, we need to find the index of the row of the input data that goes with the stratum the cursor is on. The data frame `pbuilt$data[[2]]` includes columns `x`, `ymin`, and `ymax` that define the x-coordinate of the center of the stratum, and the minimum and maximum y-coordinates of the stratum. We find the row index of that data frame where `x` is equal to the rounded x-coordinate of the cursor, and the y-coordinate of the cursor falls between `ymin` and `ymax`. ```{r, eval = FALSE} node_row <- pbuilt$data[[2]]$x == x_coord & hover$y > pbuilt$data[[2]]$ymin & hover$y < pbuilt$data[[2]]$ymax ``` To find the information to display in the tooltip, we get the name of the stratum as well as its width from the data in `pbuilt`. ```{r, eval = FALSE} node_label <- pbuilt$data[[2]]$stratum[node_row] node_n <- pbuilt$data[[2]]$count[node_row] ``` Finally, we render a tooltip using the `div` tag. We provide the text to display as arguments to `htmltools::renderTags()`. We also paste CSS style information together and pass it to the `style` argument. Note that the tooltip positioning is provided in CSS coordinates (pixels), not data coordinates. This does not require any additional effort on our part because `plot_hover` also includes an element called `coords_css`, which contains the mouse cursor location in pixel units. ```{r render strata tooltip, eval = FALSE} renderTags( tags$div( node_label, tags$br(), "n =", node_n, style = paste0( "position: absolute; ", "top: ", hover$coords_css$y + offset, "px; ", "left: ", hover$coords_css$x + offset, "px; ", "background: gray; ", "padding: 3px; ", "color: white; " ) ) )$html ``` #### Hovering over an alluvium If the cursor is not over a stratum, the next nested `if`-statement checks whether it is over an alluvium. This is done using the function `sp::point.in.polygon()` applied across each of the polygons for which we defined the coordinates inside the `renderPlot()` expression. ```{r test within polygon, eval = FALSE} hover_within_flow <- sapply( polygon_coords, function(pol) point.in.polygon(point.x = hover$x, point.y = hover$y, pol.x = pol$x, pol.y = pol$y) ) ``` If at least one polygon is beneath the mouse cursor, we locate the corresponding row in the input data and extract information to display in the tooltip. (If the condition is not met, that means the cursor is hovering over an empty area of the plot, so no tooltip appears.) ```{r, eval = FALSE} if (any(hover_within_flow)) { ... } ``` In the situation where there are more than one polygon overlapping, we get the information for the polygon that is plotted last by calling `rev()` on the logical vector returned by `point.in.polygon()`. This means that the tooltip will display information from the alluvium that appears "on top" in the plot. In this example, we display the names of the nodes that the alluvium connects, with arrows between them, and the width of the alluvium. ```{r info for alluvia tooltip, eval = FALSE} coord_id <- rev(which(hover_within_flow == 1))[1] flow_label <- paste(groups_to_draw[[coord_id]]$stratum, collapse = ' -> ') flow_n <- groups_to_draw[[coord_id]]$count[1] ``` We render a tooltip using identical syntax to the one above. ```{r render alluvia tooltip, eval = FALSE} renderTags( tags$div( flow_label, tags$br(), "n =", flow_n, style = paste0( "position: absolute; ", "top: ", hover$coords_css$y + offset, "px; ", "left: ", hover$coords_css$x + offset, "px; ", "background: gray; ", "padding: 3px; ", "color: white; " ) ) )$html ``` ## App with long-format alluvial data The `vaccinations` dataset is used for long-format alluvial data. The app is embedded at the bottom of this document, but we don't need to walk through the source code because it's almost identical to the code above. The output of `ggplot_build()` that is used to find the polygon coordinates and information for the tooltips has a consistent structure regardless of the initial format of the input data. Therefore, the calculation of polygon coordinates, user interface, and server functions of the two apps are identical. The only difference is in the initial creation of the `ggplot()` object. Refer back to the [primary vignette](ggalluvial.html) for several example plots made both with long and with wide data. The app is embedded below. Again, if the app doesn't display in the window above for whatever reason, you can view it locally by running this line of code in your console: ```{r run long app locally, eval = FALSE} shiny::shinyAppDir(system.file("examples/ex-shiny-long-data", package="ggalluvial")) ``` ## Conclusion This vignette demonstrates how to enable tooltips for {ggalluvial} plots in Shiny apps. This is one of many possible ways to do that. It may not be the optimal way — other solutions are certainly possible! The full source code for both of these Shiny apps is included with the {ggalluvial} package in the 'examples' subdirectory where the package is installed: the source files are `ggalluvial/examples/ex-shiny-wide-data/app.R` and `ggalluvial/examples/ex-shiny-long-data/app.R`. ggalluvial/inst/doc/order-rectangles.rmd0000644000176200001440000005314014370022542020071 0ustar liggesusers--- title: "The Order of the Rectangles" author: "Jason Cory Brunson" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{order of rectangles} %\VignetteEngine{knitr::rmarkdown} \usepackage[utf8]{inputenc} --- How the strata and lodes at each axis are ordered, and how to control their order, is a complicated but essential part of {ggalluvial}'s functionality. This vignette explains the motivations behind the implementation and explores the functionality in greater detail than the examples. ## Setup ```{r setup} knitr::opts_chunk$set(fig.width = 6, fig.height = 3, fig.align = "center") library(ggalluvial) ``` All of the functionality discussed in this vignette is exported by {ggalluvial}. We'll also need a toy data set to play with. I conjured the data frame `toy` to be nearly as small as possible while complex enough to illustrate the positional controls: ```{r data} # toy data set set.seed(0) toy <- data.frame( subject = rep(LETTERS[1:5], times = 4), collection = rep(1:4, each = 5), category = rep( sample(c("X", "Y"), 16, replace = TRUE), rep(c(1, 2, 1, 1), times = 4) ), class = c("one", "one", "one", "two", "two") ) print(toy) ``` The subjects are classified into categories at each collection point but are also members of fixed classes. Here's how {ggalluvial} visualizes these data under default settings: ```{r plot} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + geom_alluvium(aes(fill = class)) + geom_stratum() ``` ## Motivations The amount of control the stat layers `stat_alluvial()` and `stat_flow()` exert over the [positional aesthetics](https://ggplot2.tidyverse.org/reference/aes_position.html) of graphical objects (grobs) is unusual, by the standards of {ggplot2} and many of its extensions. In [the layered grammar of graphics framework](https://www.tandfonline.com/doi/abs/10.1198/jcgs.2009.07098), the role of a statistical transformation is usually to summarize the original data, for example by binning (`stat_bin()`) or by calculating quantiles (`stat_qq()`). These transformed data are then sent to geom layers for positioning. The positions of grobs may be adjusted after the statistical transformation, for example when points are jittered (`geom_jitter()`), but the numerical data communicated by the plot are still the product of the stat. In {ggalluvial}, the stat layers exert slightly more control. For one thing, the transformation is more sophisticated than a single value or a fixed-length vector, such as a mean, standard deviation, or five-number summary. Instead, the values of `y` (which default to `1`) within each collection are, after reordering, transformed using `cumsum()` and some additional arithmetic to obtain coordinates for the centers `y` and lower and upper limits `ymin` and `ymax` of the strata representing the categories. Additionally, the reordering of lodes within each collection relies on a hierarchy of sorting variables, based on the strata at nearby axes as well as the present one and, optionally, on the values of differentiation aesthetics like `fill`. How this hierarchy is invoked depends on the choices of several plotting parameters (`decreasing`, `reverse`, and `absolute`). Thus, the results of the statistical transformations are not as intrinsically meaningful as others and are subject to much more intervention by the user. Only once the transformations have produced these coordinates do the geom layers use them to position the rectangles and splines that constitute the plot. There are two key reasons for this division of labor: 1. The coordinates returned by some stat layers can be coupled with multiple geom layers. For example, all four geoms can couple with the `alluvium` stat. Moreover, as showcased in [the examples](http://corybrunson.github.io/ggalluvial/reference/index.html), the stats can also meaningfully couple with exogenous geoms like `text`, `pointrange`, and `errorbar`. (In principle, the geoms could also couple with exogenous stats, but i haven't done this or seen it done in the wild.) 2. Different parameters control the calculations of the coordinates (e.g. `aes.bind` and `cement.alluvia`) and the rendering of the graphical elements (`width`, `knot.pos`, and `aes.flow`), and it makes intuitive sense to handle these separately. For example, the heights of the strata and lodes convey information about the underlying data, whereas their widths are arbitrary. (If the data are provided in alluvia format, then `Stat*$setup_data()` converts them to lodes format in preparation for the main transformation. This can be done manually using [the exported conversion functions](http://corybrunson.github.io/ggalluvial/reference/alluvial-data.html), and this vignette will assume the data are already in lodes format.) ## Positioning strata Each stat layer demarcates one stack for each data collection point and one rectangle within each stack for each (non-empty) category.[^yneg] In [{ggalluvial} terms](http://corybrunson.github.io/ggalluvial/articles/ggalluvial.html), the collection points are axes and the rectangles are strata or lodes. [^yneg]: The one exception, discussed below, is for stratum variables that take both positive and negative values. To generate a sequence of stacked bar plots with no connecting flows, only the aesthetics `x` (standard) and `stratum` (custom) are required: ```{r strata} # collection point and category variables only data <- structure(toy[, 2:3], names = c("x", "stratum")) # required fields for stat transformations data$y <- 1 data$PANEL <- 1 # stratum transformation StatStratum$compute_panel(data) ``` Comparing this output to `toy`, notice first that the data have been aggregated: Each distinct combination of `x` and `stratum` occupies only one row. `x` encodes the axes and is subject to layers specific to this positional aesthetic, e.g. `scale_x_*()` transformations. `ymin` and `ymax` are the lower and upper bounds of the rectangles, and `y` is their vertical centers. Each stacked rectangle begins where the one below it ends, and their heights are the numbers of subjects (or the totals of their `y` values, if `y` is passed a numerical variable) that take the corresponding category value at the corresponding collection point. Here's the plot this strata-only transformation yields: ```{r strata plot} ggplot(toy, aes(x = collection, stratum = category)) + stat_stratum() + stat_stratum(geom = "text", aes(label = category)) ``` In this vignette, i'll use the `stat_*()` functions to add layers, so that the parameters that control their behavior are accessible via tab-completion. ### Reversing the strata Within each axis, `stratum` defaults to reverse order so that the bars proceed in the original order from top to bottom. This can be overridden by setting `reverse = FALSE` in `stat_stratum()`: ```{r strata reverse} # stratum transformation with strata in original order StatStratum$compute_panel(data, reverse = FALSE) ggplot(toy, aes(x = collection, stratum = category)) + stat_stratum(reverse = FALSE) + stat_stratum(geom = "text", aes(label = category), reverse = FALSE) ``` **Warning:** The caveat to this is that, _if `reverse` is declared in any layer, then it must be declared in every layer_, lest the layers be misaligned. This includes any `alluvium`, `flow`, and `lode` layers, since their graphical elements are organized within the bounds of the strata. ### Sorting the strata by size When the strata are defined by a character or factor variable, they default to the order of the variable (lexicographic in the former case). This can be overridden by the `decreasing` parameter, which defaults to `NA` but can be set to `TRUE` or `FALSE` to arrange the strata in decreasing or increasing order in the `y` direction: ```{r strata decreasing} # stratum transformation with strata in original order StatStratum$compute_panel(data, reverse = FALSE) ggplot(toy, aes(x = collection, stratum = category)) + stat_stratum(decreasing = TRUE) + stat_stratum(geom = "text", aes(label = category), decreasing = TRUE) ``` **Warning:** The same caveat applies to `decreasing` as to `reverse`: Make sure that all layers using alluvial stats are passed the same values! Henceforth, we'll use the default (reverse and categorical) ordering of the strata themselves. ## Positioning lodes within strata ### Alluvia and flows In the strata-only plot, each subject is represented once at each axis. _Alluvia_ are x-splines that connect these multiple representations of the same subjects across the axes. In order to avoid having these splines overlap at the axes, the `alluvium` stat must stack the alluvial cohorts---subsets of subjects who have a common profile across all axes---within each stratum. These smaller cohort-specific rectangles are the _lodes_. This calculation requires the additional custom `alluvium` aesthetic, which identifies common subjects across the axes: ```{r alluvia} # collection point, category, and subject variables data <- structure(toy[, 1:3], names = c("alluvium", "x", "stratum")) # required fields for stat transformations data$y <- 1 data$PANEL <- 1 # alluvium transformation StatAlluvium$compute_panel(data) ``` The transformed data now contain _one row per cohort_---instead of per category---_per collection point_. The vertical positional aesthetics describe the lodes rather than the strata, and the `group` variable encodes the `alluvia` (a convenience for the geom layer, and the reason that {ggalluvial} stat layers ignore variables passed to `group`). Here's how this transformation translates into the alluvial plot that began the vignette, labeling the subject of each alluvium at each intersection with a stratum: ```{r alluvia plot} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class)) + stat_stratum(alpha = .25) + stat_alluvium(geom = "text", aes(label = subject)) ``` The `flow` stat differs from the `alluvium` stat by allowing the orders of the lodes within strata to differ from one side of an axis to the other. Put differently, the `flow` stat allows _mixing_ at the axes, rather than requiring that each case or cohort is follows a continuous trajectory from one end of the plot to the other. As a result, flow plots are often much less cluttered, the trade-off being that cases or cohorts cannot be tracked through them. ```{r flows} # flow transformation StatFlow$compute_panel(data) ``` The `flow` stat transformation yields _one row per cohort per side per flow_. Each intermediate axis appears twice in the data, once for the incoming flow and once for the outgoing flow. (The starting and ending axes only have rows for outgoing and incoming flows, respectively.) Here is the flow version of the preceding alluvial plot, labeling each side of each flow with the corresponding subject: ```{r flows plot} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_stratum() + stat_flow(aes(fill = class)) + stat_flow(geom = "text", aes(label = subject, hjust = after_stat(flow) == "to")) ``` The [computed variable](https://ggplot2.tidyverse.org/reference/aes_eval.html) `flow` indicates whether each row of the `compute_panel()` output corresponds to a flow _to_ or _from_ its axis; the values are used to nudge the labels toward their respective flows (to avoid overlap). Mismatches between adjacent labels indicate where lodes are ordered differently on either side of a stratum. ### Lode guidance As the number of strata at each axis grows, heterogeneous cases or cohorts can produce highly complex alluvia and very messy plots. {ggalluvial} mitigates this by strategically arranging the lodes---the intersections of the alluvia with the strata---so as to reduce their crossings between adjacent axes. This strategy is executed locally: At each axis (call it the _index_ axis), the order of the lodes is guided by several totally or partially ordered variables. In order of priority: 1. the strata at the index axis 2. the strata at the other axes to which the index axis is linked by alluvia or flows---namely, all other axes in the case of an alluvium, or a single adjacent axis in the case of a flow 3. the alluvia themselves, i.e. the variable passed to `alluvium` In the alluvium case, the prioritization of the remaining axes is determined by a _lode guidance function_. A lode guidance function can be passed to the `lode.guidance` parameter, which defaults to `"zigzag"`. This function puts the nearest (adjacent) axes first, then zigzags outward from there, initially (the "zig") in the direction of the closer extreme: ```{r lode zigzag} for (i in 1:4) print(lode_zigzag(4, i)) ``` Several alternative `lode_*()` functions are available: - `"zagzig"` behaves like `"zigzag"` except initially "zags" toward the farther extreme. - `"frontback"` and `"backfront"` behave like `"zigzag"` but extend completely in one outward direction from the index axis before the other. - `"forward"` and `"backward"` put the remaining axes in increasing and decreasing order, regardless of the relative position of the index axis. Two alternatives are illustrated below: ```{r alluvia plot w/ backfront guidance} for (i in 1:4) print(lode_backfront(4, i)) ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class), lode.guidance = "backfront") + stat_stratum() + stat_alluvium(geom = "text", aes(label = subject), lode.guidance = "backfront") ``` The difference between `"backfront"` guidance and `"zigzag"` guidance can be seen in the order of the lodes of the `"Y"` stratum at axis `3`: Whereas `"zigzag"` minimized the crossings between axes `3` and `4`, locating the distinctive class-`"one"` case above the others, `"backfront"` minimized the crossings between axes `2` and `3` (axis `2` being immediately before axis `3`), locating this case below the others. ```{r alluvia plot w/ backward guidance} for (i in 1:4) print(lode_backward(4, i)) ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class), lode.guidance = "backward") + stat_stratum() + stat_alluvium(geom = "text", aes(label = subject), lode.guidance = "backward") ``` The effect of `"backward"` guidance is to keep the right part of the plot as tidy as possible while allowing the left part to become as messy as necessary. (`"forward"` has the opposite effect.) ### Aesthetic binding It often makes sense to bundle together the cases and cohorts that fall into common groups used to assign differentiation aesthetics: most commonly `fill`, but also `alpha`, which controls the opacity of the `fill` colors, and `colour`, `linetype`, and `size`, which control the borders of the alluvia, flows, and lodes. The `aes.bind` parameter defaults to `"none"`, in which case aesthetics play no role in the order of the lodes. Setting the parameter to `"flows"` prioritizes any such aesthetics _after_ the strata of any other axes but _before_ the alluvia of the index axis (effectively ordering the flows at each axis by aesthetic), while setting it to `"alluvia"` prioritizes aesthetics _before_ the strata of any other axes (effectively ordering the alluvia). In the toy example, the stronger option results in the lodes within each stratum being sorted first by class: ```{r alluvia plot w/ strong aesthetic binding} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class, label = subject), aes.bind = "alluvia") + stat_stratum() + stat_alluvium(geom = "text", aes(fill = class, label = subject), aes.bind = "alluvia") ``` The more flexible option groups the lodes by class only after they've been ordered according to the strata at the remaining axes: ```{r alluvia plot w/ weak aesthetic binding} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class, label = subject), aes.bind = "flows") + stat_stratum() + stat_alluvium(geom = "text", aes(fill = class, label = subject), aes.bind = "flows") ``` **Warning:** In addition to parameters like `reverse`, _when aesthetic variables are prioritized at all, overlaid alluvial layers must include the same aesthetics in the same order_. (This can produce warnings when the aesthetics are not recognized by the geom.) Try removing `fill = class` from the text geom above to see the risk posed by neglecting this check. Rather than ordering lodes _within_, the `flow` stat separately orders the flows _into_ and _out from_, each stratum. (This precludes a corresponding `"alluvia"` option for `aes.bind`.) By default, the flows are ordered with respect first to the orders of the strata at the present axis and second to those at the adjacent axis. Setting `aes.bind` to the non-default option `"flows"` tells `stat_flow()` to prioritize flow aesthetics after the strata of the index axis but before the strata of the adjacent axis: ```{r flows plots w/ aesthetic binding} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_flow(aes(fill = class, label = subject), aes.bind = "flows") + stat_stratum() + stat_flow(geom = "text", aes(fill = class, label = subject, hjust = after_stat(flow) == "to"), aes.bind = "flows") ``` Note: The `aes.flow` parameter tells `geom_flow()` how flows should inherit differentiation aesthetics from adjacent axes---`"forward"` or `"backward"`. It does _not_ influence their positions. ### Manual lode ordering Finally, one may wish to put the lodes at each axis in a predefined order, subject to their being located in the correct strata. This can be done by passing a data column to the `order` aesthetic. For the toy example, we can pass a vector that puts the cases in the order of their IDs in the data at every axis: ```{r alluvia plot w/ manual lode ordering} lode_ord <- rep(seq(5), times = 4) ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class, order = lode_ord)) + stat_stratum() + stat_alluvium(geom = "text", aes(fill = class, order = lode_ord, label = subject)) ``` ```{r flows plot w/ manual lode ordering} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_flow(aes(fill = class, order = lode_ord)) + stat_stratum() + stat_flow(geom = "text", aes(fill = class, order = lode_ord, label = subject, hjust = after_stat(flow) == "to")) ``` Within each stratum at each axis, the cases are now in order from top to bottom. ## Negative strata In response to an elegant real-world use case, {ggalluvial} can now handle negative observations in the same way as `geom_bar()`: by grouping these observations into negative strata and stacking these strata in the negative `y` direction (i.e. in the opposite direction of the positive strata). This new functionality complicates the above discussion in two ways: 1. _Positioning strata:_ The negative strata could be reverse-ordered with respect to the positive strata, as in `geom_bar()`, or ordered in the same way (vertically, without regard for sign). 2. _Positioning lodes within strata:_ Two strata may correspond to the same stratum variable at an axis (one positive and one negative), which under-determines the ordering of lodes within strata. The first issue is binary: Once `decreasing` and `reverse` are chosen, there are only two options for the negative strata. The choice is made by setting the new `absolute` parameter to either `TRUE` (the default), which yields a mirror-image ordering, or `FALSE`, which adopts the same vertical ordering. This setting also influences the ordering of lodes within strata at the same nexus as `reverse`, namely at the level of the alluvium variable. The second issue is then handled by creating a `deposit` variable with unique values corresponding to each _signed_ stratum variable value, in the order prescribed by `decreasing`, `reverse`, and `absolute`. The `deposit` variable is then used in place of `stratum` for all of the lode-ordering tasks above. As a point of reference, here is a bar plot of the toy data, with a randomized sign variable used to indicate negative-valued observations: ```{r bar plot with negative observations} set.seed(78) toy$sign <- sample(c(-1, 1), nrow(toy), replace = TRUE) print(toy) ggplot(toy, aes(x = collection, y = sign)) + geom_bar(aes(fill = class), stat = "identity") ``` The default behavior, illustrated here with flows, is for the positive strata to proceed downward and the negative strata to proceed upward, in both cases from larger absolute values to zero: ```{r flows plot w/ negative strata} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject, y = sign)) + geom_flow(aes(fill = class)) + geom_stratum() + geom_text(stat = "stratum", aes(label = category)) ``` To instead have the strata proceed downward at each axis, and the lodes downward within each stratum, set `absolute = FALSE` (now plotting alluvia): ```{r alluvia plot w/ negative strata} ggplot(toy, aes(x = collection, stratum = category, alluvium = subject, y = sign)) + geom_alluvium(aes(fill = class), absolute = FALSE) + geom_stratum(absolute = FALSE) + geom_text(stat = "alluvium", aes(label = subject), absolute = FALSE) ``` Note again that the labels are consistent with the alluvia and flows, despite the omission of the `fill` aesthetic from the text geom, because the aesthetic variables are not prioritized in the ordering of the lodes. ## More examples More examples of all of the functionality showcased here can be found in the documentation for the `stat_*()` functions, [browsable on the package website](http://corybrunson.github.io/ggalluvial/reference/index.html). ## Appendix ```{r session info} sessioninfo::session_info() ``` ggalluvial/inst/doc/order-rectangles.html0000644000176200001440000216506215146567320020276 0ustar liggesusers The Order of the Rectangles

The Order of the Rectangles

Jason Cory Brunson

2026-02-22

How the strata and lodes at each axis are ordered, and how to control their order, is a complicated but essential part of {ggalluvial}’s functionality. This vignette explains the motivations behind the implementation and explores the functionality in greater detail than the examples.

Setup

knitr::opts_chunk$set(fig.width = 6, fig.height = 3, fig.align = "center")
library(ggalluvial)

All of the functionality discussed in this vignette is exported by {ggalluvial}. We’ll also need a toy data set to play with. I conjured the data frame toy to be nearly as small as possible while complex enough to illustrate the positional controls:

# toy data set
set.seed(0)
toy <- data.frame(
  subject = rep(LETTERS[1:5], times = 4),
  collection = rep(1:4, each  = 5),
  category = rep(
    sample(c("X", "Y"), 16, replace = TRUE),
    rep(c(1, 2, 1, 1), times = 4)
  ),
  class = c("one", "one", "one", "two", "two")
)
print(toy)
##    subject collection category class
## 1        A          1        Y   one
## 2        B          1        X   one
## 3        C          1        X   one
## 4        D          1        Y   two
## 5        E          1        X   two
## 6        A          2        X   one
## 7        B          2        Y   one
## 8        C          2        Y   one
## 9        D          2        X   two
## 10       E          2        X   two
## 11       A          3        X   one
## 12       B          3        Y   one
## 13       C          3        Y   one
## 14       D          3        Y   two
## 15       E          3        X   two
## 16       A          4        X   one
## 17       B          4        X   one
## 18       C          4        X   one
## 19       D          4        X   two
## 20       E          4        X   two

The subjects are classified into categories at each collection point but are also members of fixed classes. Here’s how {ggalluvial} visualizes these data under default settings:

ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) +
  geom_alluvium(aes(fill = class)) +
  geom_stratum()

Motivations

The amount of control the stat layers stat_alluvial() and stat_flow() exert over the positional aesthetics of graphical objects (grobs) is unusual, by the standards of {ggplot2} and many of its extensions. In the layered grammar of graphics framework, the role of a statistical transformation is usually to summarize the original data, for example by binning (stat_bin()) or by calculating quantiles (stat_qq()). These transformed data are then sent to geom layers for positioning. The positions of grobs may be adjusted after the statistical transformation, for example when points are jittered (geom_jitter()), but the numerical data communicated by the plot are still the product of the stat.

In {ggalluvial}, the stat layers exert slightly more control. For one thing, the transformation is more sophisticated than a single value or a fixed-length vector, such as a mean, standard deviation, or five-number summary. Instead, the values of y (which default to 1) within each collection are, after reordering, transformed using cumsum() and some additional arithmetic to obtain coordinates for the centers y and lower and upper limits ymin and ymax of the strata representing the categories. Additionally, the reordering of lodes within each collection relies on a hierarchy of sorting variables, based on the strata at nearby axes as well as the present one and, optionally, on the values of differentiation aesthetics like fill. How this hierarchy is invoked depends on the choices of several plotting parameters (decreasing, reverse, and absolute). Thus, the results of the statistical transformations are not as intrinsically meaningful as others and are subject to much more intervention by the user. Only once the transformations have produced these coordinates do the geom layers use them to position the rectangles and splines that constitute the plot.

There are two key reasons for this division of labor:

  1. The coordinates returned by some stat layers can be coupled with multiple geom layers. For example, all four geoms can couple with the alluvium stat. Moreover, as showcased in the examples, the stats can also meaningfully couple with exogenous geoms like text, pointrange, and errorbar. (In principle, the geoms could also couple with exogenous stats, but i haven’t done this or seen it done in the wild.)
  2. Different parameters control the calculations of the coordinates (e.g. aes.bind and cement.alluvia) and the rendering of the graphical elements (width, knot.pos, and aes.flow), and it makes intuitive sense to handle these separately. For example, the heights of the strata and lodes convey information about the underlying data, whereas their widths are arbitrary.

(If the data are provided in alluvia format, then Stat*$setup_data() converts them to lodes format in preparation for the main transformation. This can be done manually using the exported conversion functions, and this vignette will assume the data are already in lodes format.)

Positioning strata

Each stat layer demarcates one stack for each data collection point and one rectangle within each stack for each (non-empty) category.1 In {ggalluvial} terms, the collection points are axes and the rectangles are strata or lodes.

To generate a sequence of stacked bar plots with no connecting flows, only the aesthetics x (standard) and stratum (custom) are required:

# collection point and category variables only
data <- structure(toy[, 2:3], names = c("x", "stratum"))
# required fields for stat transformations
data$y <- 1
data$PANEL <- 1
# stratum transformation
StatStratum$compute_panel(data)
##   x stratum   y n count deposit prop ymin ymax
## 2 1       Y 1.0 2     2       1  0.4    0    2
## 1 1       X 3.5 3     3       2  0.6    2    5
## 4 2       Y 1.0 2     2       3  0.4    0    2
## 3 2       X 3.5 3     3       4  0.6    2    5
## 6 3       Y 1.5 3     3       5  0.6    0    3
## 5 3       X 4.0 2     2       6  0.4    3    5
## 7 4       X 2.5 5     5       7  1.0    0    5

Comparing this output to toy, notice first that the data have been aggregated: Each distinct combination of x and stratum occupies only one row. x encodes the axes and is subject to layers specific to this positional aesthetic, e.g. scale_x_*() transformations. ymin and ymax are the lower and upper bounds of the rectangles, and y is their vertical centers. Each stacked rectangle begins where the one below it ends, and their heights are the numbers of subjects (or the totals of their y values, if y is passed a numerical variable) that take the corresponding category value at the corresponding collection point.

Here’s the plot this strata-only transformation yields:

ggplot(toy, aes(x = collection, stratum = category)) +
  stat_stratum() +
  stat_stratum(geom = "text", aes(label = category))

In this vignette, i’ll use the stat_*() functions to add layers, so that the parameters that control their behavior are accessible via tab-completion.

Reversing the strata

Within each axis, stratum defaults to reverse order so that the bars proceed in the original order from top to bottom. This can be overridden by setting reverse = FALSE in stat_stratum():

# stratum transformation with strata in original order
StatStratum$compute_panel(data, reverse = FALSE)
##   x stratum   y n count deposit prop ymin ymax
## 1 1       X 1.5 3     3       1  0.6    0    3
## 2 1       Y 4.0 2     2       2  0.4    3    5
## 3 2       X 1.5 3     3       3  0.6    0    3
## 4 2       Y 4.0 2     2       4  0.4    3    5
## 5 3       X 1.0 2     2       5  0.4    0    2
## 6 3       Y 3.5 3     3       6  0.6    2    5
## 7 4       X 2.5 5     5       7  1.0    0    5
ggplot(toy, aes(x = collection, stratum = category)) +
  stat_stratum(reverse = FALSE) +
  stat_stratum(geom = "text", aes(label = category), reverse = FALSE)

Warning: The caveat to this is that, if reverse is declared in any layer, then it must be declared in every layer, lest the layers be misaligned. This includes any alluvium, flow, and lode layers, since their graphical elements are organized within the bounds of the strata.

Sorting the strata by size

When the strata are defined by a character or factor variable, they default to the order of the variable (lexicographic in the former case). This can be overridden by the decreasing parameter, which defaults to NA but can be set to TRUE or FALSE to arrange the strata in decreasing or increasing order in the y direction:

# stratum transformation with strata in original order
StatStratum$compute_panel(data, reverse = FALSE)
##   x stratum   y n count deposit prop ymin ymax
## 1 1       X 1.5 3     3       1  0.6    0    3
## 2 1       Y 4.0 2     2       2  0.4    3    5
## 3 2       X 1.5 3     3       3  0.6    0    3
## 4 2       Y 4.0 2     2       4  0.4    3    5
## 5 3       X 1.0 2     2       5  0.4    0    2
## 6 3       Y 3.5 3     3       6  0.6    2    5
## 7 4       X 2.5 5     5       7  1.0    0    5
ggplot(toy, aes(x = collection, stratum = category)) +
  stat_stratum(decreasing = TRUE) +
  stat_stratum(geom = "text", aes(label = category), decreasing = TRUE)

Warning: The same caveat applies to decreasing as to reverse: Make sure that all layers using alluvial stats are passed the same values! Henceforth, we’ll use the default (reverse and categorical) ordering of the strata themselves.

Positioning lodes within strata

Alluvia and flows

In the strata-only plot, each subject is represented once at each axis. Alluvia are x-splines that connect these multiple representations of the same subjects across the axes. In order to avoid having these splines overlap at the axes, the alluvium stat must stack the alluvial cohorts—subsets of subjects who have a common profile across all axes—within each stratum. These smaller cohort-specific rectangles are the lodes. This calculation requires the additional custom alluvium aesthetic, which identifies common subjects across the axes:

# collection point, category, and subject variables
data <- structure(toy[, 1:3], names = c("alluvium", "x", "stratum"))
# required fields for stat transformations
data$y <- 1
data$PANEL <- 1
# alluvium transformation
StatAlluvium$compute_panel(data)
##    x alluvium stratum   y PANEL lode n count deposit prop ymin ymax group
## 1  1        A       Y 1.5     1    A 1     1       1  0.2    1    2     1
## 2  1        B       X 3.5     1    B 1     1       2  0.2    3    4     2
## 3  1        C       X 2.5     1    C 1     1       2  0.2    2    3     3
## 4  1        D       Y 0.5     1    D 1     1       1  0.2    0    1     4
## 5  1        E       X 4.5     1    E 1     1       2  0.2    4    5     5
## 6  2        A       X 3.5     1    A 1     1       4  0.2    3    4     1
## 7  2        B       Y 1.5     1    B 1     1       3  0.2    1    2     2
## 8  2        C       Y 0.5     1    C 1     1       3  0.2    0    1     3
## 9  2        D       X 2.5     1    D 1     1       4  0.2    2    3     4
## 10 2        E       X 4.5     1    E 1     1       4  0.2    4    5     5
## 11 3        A       X 3.5     1    A 1     1       6  0.2    3    4     1
## 12 3        B       Y 1.5     1    B 1     1       5  0.2    1    2     2
## 13 3        C       Y 0.5     1    C 1     1       5  0.2    0    1     3
## 14 3        D       Y 2.5     1    D 1     1       5  0.2    2    3     4
## 15 3        E       X 4.5     1    E 1     1       6  0.2    4    5     5
## 16 4        A       X 3.5     1    A 1     1       7  0.2    3    4     1
## 17 4        B       X 1.5     1    B 1     1       7  0.2    1    2     2
## 18 4        C       X 0.5     1    C 1     1       7  0.2    0    1     3
## 19 4        D       X 2.5     1    D 1     1       7  0.2    2    3     4
## 20 4        E       X 4.5     1    E 1     1       7  0.2    4    5     5

The transformed data now contain one row per cohort—instead of per category—per collection point. The vertical positional aesthetics describe the lodes rather than the strata, and the group variable encodes the alluvia (a convenience for the geom layer, and the reason that {ggalluvial} stat layers ignore variables passed to group).

Here’s how this transformation translates into the alluvial plot that began the vignette, labeling the subject of each alluvium at each intersection with a stratum:

ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) +
  stat_alluvium(aes(fill = class)) +
  stat_stratum(alpha = .25) +
  stat_alluvium(geom = "text", aes(label = subject))

The flow stat differs from the alluvium stat by allowing the orders of the lodes within strata to differ from one side of an axis to the other. Put differently, the flow stat allows mixing at the axes, rather than requiring that each case or cohort is follows a continuous trajectory from one end of the plot to the other. As a result, flow plots are often much less cluttered, the trade-off being that cases or cohorts cannot be tracked through them.

# flow transformation
StatFlow$compute_panel(data)
##    alluvium x stratum deposit flow   y n count lode group prop ymin ymax
## 3         2 1       Y       1 from 1.0 2     2    A     2  0.4    0    2
## 1         1 1       X       2 from 3.0 2     2    B     1  0.4    2    4
## 5         3 1       X       2 from 4.5 1     1    E     3  0.2    4    5
## 2         1 2       Y       3   to 1.0 2     2    B     1  0.2    0    2
## 4         2 2       X       4   to 3.0 2     2    A     2  0.2    2    4
## 6         3 2       X       4   to 4.5 1     1    E     3  0.1    4    5
## 7         4 2       Y       3 from 1.0 2     2    B     4  0.2    0    2
## 9         5 2       X       4 from 2.5 1     1    D     5  0.1    2    3
## 11        6 2       X       4 from 4.0 2     2    A     6  0.2    3    5
## 8         4 3       Y       5   to 1.0 2     2    B     4  0.2    0    2
## 10        5 3       Y       5   to 2.5 1     1    D     5  0.1    2    3
## 12        6 3       X       6   to 4.0 2     2    A     6  0.2    3    5
## 13        7 3       Y       5 from 1.5 3     3    B     7  0.3    0    3
## 15        8 3       X       6 from 4.0 2     2    A     8  0.2    3    5
## 14        7 4       X       7   to 1.5 3     3    B     7  0.6    0    3
## 16        8 4       X       7   to 4.0 2     2    A     8  0.4    3    5

The flow stat transformation yields one row per cohort per side per flow. Each intermediate axis appears twice in the data, once for the incoming flow and once for the outgoing flow. (The starting and ending axes only have rows for outgoing and incoming flows, respectively.) Here is the flow version of the preceding alluvial plot, labeling each side of each flow with the corresponding subject:

ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) +
  stat_stratum() +
  stat_flow(aes(fill = class)) +
  stat_flow(geom = "text",
            aes(label = subject, hjust = after_stat(flow) == "to"))

The computed variable flow indicates whether each row of the compute_panel() output corresponds to a flow to or from its axis; the values are used to nudge the labels toward their respective flows (to avoid overlap). Mismatches between adjacent labels indicate where lodes are ordered differently on either side of a stratum.

Lode guidance

As the number of strata at each axis grows, heterogeneous cases or cohorts can produce highly complex alluvia and very messy plots. {ggalluvial} mitigates this by strategically arranging the lodes—the intersections of the alluvia with the strata—so as to reduce their crossings between adjacent axes. This strategy is executed locally: At each axis (call it the index axis), the order of the lodes is guided by several totally or partially ordered variables. In order of priority:

  1. the strata at the index axis
  2. the strata at the other axes to which the index axis is linked by alluvia or flows—namely, all other axes in the case of an alluvium, or a single adjacent axis in the case of a flow
  3. the alluvia themselves, i.e. the variable passed to alluvium

In the alluvium case, the prioritization of the remaining axes is determined by a lode guidance function. A lode guidance function can be passed to the lode.guidance parameter, which defaults to "zigzag". This function puts the nearest (adjacent) axes first, then zigzags outward from there, initially (the “zig”) in the direction of the closer extreme:

for (i in 1:4) print(lode_zigzag(4, i))
## [1] 1 2 3 4
## [1] 2 1 3 4
## [1] 3 4 2 1
## [1] 4 3 2 1

Several alternative lode_*() functions are available:

  • "zagzig" behaves like "zigzag" except initially “zags” toward the farther extreme.
  • "frontback" and "backfront" behave like "zigzag" but extend completely in one outward direction from the index axis before the other.
  • "forward" and "backward" put the remaining axes in increasing and decreasing order, regardless of the relative position of the index axis.

Two alternatives are illustrated below:

for (i in 1:4) print(lode_backfront(4, i))
## [1] 1 2 3 4
## [1] 2 1 3 4
## [1] 3 2 1 4
## [1] 4 3 2 1
ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) +
  stat_alluvium(aes(fill = class), lode.guidance = "backfront") +
  stat_stratum() +
  stat_alluvium(geom = "text", aes(label = subject),
                lode.guidance = "backfront")

The difference between "backfront" guidance and "zigzag" guidance can be seen in the order of the lodes of the "Y" stratum at axis 3: Whereas "zigzag" minimized the crossings between axes 3 and 4, locating the distinctive class-"one" case above the others, "backfront" minimized the crossings between axes 2 and 3 (axis 2 being immediately before axis 3), locating this case below the others.

for (i in 1:4) print(lode_backward(4, i))
## [1] 1 4 3 2
## [1] 2 4 3 1
## [1] 3 4 2 1
## [1] 4 3 2 1
ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) +
  stat_alluvium(aes(fill = class), lode.guidance = "backward") +
  stat_stratum() +
  stat_alluvium(geom = "text", aes(label = subject),
                lode.guidance = "backward")

The effect of "backward" guidance is to keep the right part of the plot as tidy as possible while allowing the left part to become as messy as necessary. ("forward" has the opposite effect.)

Aesthetic binding

It often makes sense to bundle together the cases and cohorts that fall into common groups used to assign differentiation aesthetics: most commonly fill, but also alpha, which controls the opacity of the fill colors, and colour, linetype, and size, which control the borders of the alluvia, flows, and lodes.

The aes.bind parameter defaults to "none", in which case aesthetics play no role in the order of the lodes. Setting the parameter to "flows" prioritizes any such aesthetics after the strata of any other axes but before the alluvia of the index axis (effectively ordering the flows at each axis by aesthetic), while setting it to "alluvia" prioritizes aesthetics before the strata of any other axes (effectively ordering the alluvia). In the toy example, the stronger option results in the lodes within each stratum being sorted first by class:

ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) +
  stat_alluvium(aes(fill = class, label = subject), aes.bind = "alluvia") +
  stat_stratum() +
  stat_alluvium(geom = "text", aes(fill = class, label = subject),
                aes.bind = "alluvia")
## Warning in stat_alluvium(aes(fill = class, label = subject), aes.bind =
## "alluvia"): Ignoring unknown aesthetics: label
## Warning in stat_alluvium(geom = "text", aes(fill = class, label = subject), :
## Ignoring unknown aesthetics: fill

The more flexible option groups the lodes by class only after they’ve been ordered according to the strata at the remaining axes:

ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) +
  stat_alluvium(aes(fill = class, label = subject), aes.bind = "flows") +
  stat_stratum() +
  stat_alluvium(geom = "text", aes(fill = class, label = subject),
                aes.bind = "flows")
## Warning in stat_alluvium(aes(fill = class, label = subject), aes.bind =
## "flows"): Ignoring unknown aesthetics: label
## Warning in stat_alluvium(geom = "text", aes(fill = class, label = subject), :
## Ignoring unknown aesthetics: fill

Warning: In addition to parameters like reverse, when aesthetic variables are prioritized at all, overlaid alluvial layers must include the same aesthetics in the same order. (This can produce warnings when the aesthetics are not recognized by the geom.) Try removing fill = class from the text geom above to see the risk posed by neglecting this check.

Rather than ordering lodes within, the flow stat separately orders the flows into and out from, each stratum. (This precludes a corresponding "alluvia" option for aes.bind.) By default, the flows are ordered with respect first to the orders of the strata at the present axis and second to those at the adjacent axis. Setting aes.bind to the non-default option "flows" tells stat_flow() to prioritize flow aesthetics after the strata of the index axis but before the strata of the adjacent axis:

ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) +
  stat_flow(aes(fill = class, label = subject), aes.bind = "flows") +
  stat_stratum() +
  stat_flow(geom = "text",
            aes(fill = class, label = subject,
                hjust = after_stat(flow) == "to"),
            aes.bind = "flows")
## Warning in stat_flow(aes(fill = class, label = subject), aes.bind = "flows"):
## Ignoring unknown aesthetics: label
## Warning in stat_flow(geom = "text", aes(fill = class, label = subject, hjust =
## after_stat(flow) == : Ignoring unknown aesthetics: fill

Note: The aes.flow parameter tells geom_flow() how flows should inherit differentiation aesthetics from adjacent axes—"forward" or "backward". It does not influence their positions.

Manual lode ordering

Finally, one may wish to put the lodes at each axis in a predefined order, subject to their being located in the correct strata. This can be done by passing a data column to the order aesthetic. For the toy example, we can pass a vector that puts the cases in the order of their IDs in the data at every axis:

lode_ord <- rep(seq(5), times = 4)
ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) +
  stat_alluvium(aes(fill = class, order = lode_ord)) +
  stat_stratum() +
  stat_alluvium(geom = "text",
                aes(fill = class, order = lode_ord, label = subject))
## Warning in stat_alluvium(aes(fill = class, order = lode_ord)): Ignoring unknown
## aesthetics: order
## Warning in stat_alluvium(geom = "text", aes(fill = class, order = lode_ord, :
## Ignoring unknown aesthetics: fill and order

ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) +
  stat_flow(aes(fill = class, order = lode_ord)) +
  stat_stratum() +
  stat_flow(geom = "text",
            aes(fill = class, order = lode_ord, label = subject,
                hjust = after_stat(flow) == "to"))
## Warning in stat_flow(geom = "text", aes(fill = class, order = lode_ord, :
## Ignoring unknown aesthetics: fill

Within each stratum at each axis, the cases are now in order from top to bottom.

Negative strata

In response to an elegant real-world use case, {ggalluvial} can now handle negative observations in the same way as geom_bar(): by grouping these observations into negative strata and stacking these strata in the negative y direction (i.e. in the opposite direction of the positive strata). This new functionality complicates the above discussion in two ways:

  1. Positioning strata: The negative strata could be reverse-ordered with respect to the positive strata, as in geom_bar(), or ordered in the same way (vertically, without regard for sign).
  2. Positioning lodes within strata: Two strata may correspond to the same stratum variable at an axis (one positive and one negative), which under-determines the ordering of lodes within strata.

The first issue is binary: Once decreasing and reverse are chosen, there are only two options for the negative strata. The choice is made by setting the new absolute parameter to either TRUE (the default), which yields a mirror-image ordering, or FALSE, which adopts the same vertical ordering. This setting also influences the ordering of lodes within strata at the same nexus as reverse, namely at the level of the alluvium variable. The second issue is then handled by creating a deposit variable with unique values corresponding to each signed stratum variable value, in the order prescribed by decreasing, reverse, and absolute. The deposit variable is then used in place of stratum for all of the lode-ordering tasks above.

As a point of reference, here is a bar plot of the toy data, with a randomized sign variable used to indicate negative-valued observations:

set.seed(78)
toy$sign <- sample(c(-1, 1), nrow(toy), replace = TRUE)
print(toy)
##    subject collection category class sign
## 1        A          1        Y   one   -1
## 2        B          1        X   one    1
## 3        C          1        X   one    1
## 4        D          1        Y   two   -1
## 5        E          1        X   two    1
## 6        A          2        X   one    1
## 7        B          2        Y   one    1
## 8        C          2        Y   one    1
## 9        D          2        X   two   -1
## 10       E          2        X   two   -1
## 11       A          3        X   one    1
## 12       B          3        Y   one   -1
## 13       C          3        Y   one   -1
## 14       D          3        Y   two    1
## 15       E          3        X   two    1
## 16       A          4        X   one    1
## 17       B          4        X   one    1
## 18       C          4        X   one   -1
## 19       D          4        X   two   -1
## 20       E          4        X   two    1
ggplot(toy, aes(x = collection, y = sign)) +
  geom_bar(aes(fill = class), stat = "identity")

The default behavior, illustrated here with flows, is for the positive strata to proceed downward and the negative strata to proceed upward, in both cases from larger absolute values to zero:

ggplot(toy, aes(x = collection, stratum = category, alluvium = subject,
                y = sign)) +
  geom_flow(aes(fill = class)) +
  geom_stratum() +
  geom_text(stat = "stratum", aes(label = category))

To instead have the strata proceed downward at each axis, and the lodes downward within each stratum, set absolute = FALSE (now plotting alluvia):

ggplot(toy, aes(x = collection, stratum = category, alluvium = subject,
                y = sign)) +
  geom_alluvium(aes(fill = class), absolute = FALSE) +
  geom_stratum(absolute = FALSE) +
  geom_text(stat = "alluvium", aes(label = subject), absolute = FALSE)

Note again that the labels are consistent with the alluvia and flows, despite the omission of the fill aesthetic from the text geom, because the aesthetic variables are not prioritized in the ordering of the lodes.

More examples

More examples of all of the functionality showcased here can be found in the documentation for the stat_*() functions, browsable on the package website.

Appendix

sessioninfo::session_info()
## ─ Session info ───────────────────────────────────────────────────────────────
##  setting  value
##  version  R version 4.5.2 (2025-10-31)
##  os       macOS Tahoe 26.2
##  system   aarch64, darwin20
##  ui       X11
##  language (EN)
##  collate  C
##  ctype    en_US.UTF-8
##  tz       America/New_York
##  date     2026-02-22
##  pandoc   2.19 @ /opt/homebrew/bin/ (via rmarkdown)
##  quarto   1.8.25 @ /usr/local/bin/quarto
## 
## ─ Packages ───────────────────────────────────────────────────────────────────
##  package      * version date (UTC) lib source
##  bslib          0.9.0   2025-01-30 [3] CRAN (R 4.5.0)
##  cachem         1.1.0   2024-05-16 [3] CRAN (R 4.5.0)
##  cli            3.6.5   2025-04-23 [3] CRAN (R 4.5.0)
##  digest         0.6.39  2025-11-19 [3] CRAN (R 4.5.2)
##  dplyr          1.1.4   2023-11-17 [3] CRAN (R 4.5.0)
##  evaluate       1.0.5   2025-08-27 [3] CRAN (R 4.5.0)
##  farver         2.1.2   2024-05-13 [3] CRAN (R 4.5.0)
##  fastmap        1.2.0   2024-05-15 [3] CRAN (R 4.5.0)
##  generics       0.1.4   2025-05-09 [3] CRAN (R 4.5.0)
##  ggalluvial   * 0.12.6  2026-02-22 [1] local
##  ggfittext      0.10.3  2025-12-13 [3] CRAN (R 4.5.2)
##  ggplot2      * 4.0.2   2026-02-03 [3] CRAN (R 4.5.2)
##  ggrepel        0.9.6   2024-09-07 [3] CRAN (R 4.5.0)
##  glue           1.8.0   2024-09-30 [3] CRAN (R 4.5.0)
##  gtable         0.3.6   2024-10-25 [3] CRAN (R 4.5.0)
##  htmltools      0.5.9   2025-12-04 [3] CRAN (R 4.5.2)
##  jquerylib      0.1.4   2021-04-26 [3] CRAN (R 4.5.0)
##  jsonlite       2.0.0   2025-03-27 [3] CRAN (R 4.5.0)
##  knitr          1.51    2025-12-20 [3] CRAN (R 4.5.2)
##  labeling       0.4.3   2023-08-29 [3] CRAN (R 4.5.0)
##  lifecycle      1.0.5   2026-01-08 [3] CRAN (R 4.5.2)
##  magrittr       2.0.4   2025-09-12 [3] CRAN (R 4.5.0)
##  otel           0.2.0   2025-08-29 [3] CRAN (R 4.5.0)
##  pillar         1.11.1  2025-09-17 [3] CRAN (R 4.5.0)
##  pkgconfig      2.0.3   2019-09-22 [3] CRAN (R 4.5.0)
##  purrr          1.2.1   2026-01-09 [3] CRAN (R 4.5.2)
##  R6             2.6.1   2025-02-15 [3] CRAN (R 4.5.0)
##  RColorBrewer   1.1-3   2022-04-03 [3] CRAN (R 4.5.0)
##  Rcpp           1.1.1   2026-01-10 [3] CRAN (R 4.5.2)
##  rlang          1.1.7   2026-01-09 [3] CRAN (R 4.5.2)
##  rmarkdown      2.30    2025-09-28 [3] CRAN (R 4.5.0)
##  S7             0.2.1   2025-11-14 [3] CRAN (R 4.5.2)
##  sass           0.4.10  2025-04-11 [3] CRAN (R 4.5.0)
##  scales         1.4.0   2025-04-24 [3] CRAN (R 4.5.0)
##  sessioninfo    1.2.3   2025-02-05 [3] CRAN (R 4.5.0)
##  stringi        1.8.7   2025-03-27 [3] CRAN (R 4.5.0)
##  tibble         3.3.1   2026-01-11 [3] CRAN (R 4.5.2)
##  tidyr          1.3.2   2025-12-19 [3] CRAN (R 4.5.2)
##  tidyselect     1.2.1   2024-03-11 [3] CRAN (R 4.5.0)
##  vctrs          0.7.1   2026-01-23 [3] CRAN (R 4.5.2)
##  withr          3.0.2   2024-10-28 [3] CRAN (R 4.5.0)
##  xfun           0.56    2026-01-18 [3] CRAN (R 4.5.2)
##  yaml           2.3.12  2025-12-10 [3] CRAN (R 4.5.2)
## 
##  [1] /private/var/folders/4p/3cy0qmp15x9216qsqhh84kzm0000gn/T/RtmpqAXS9Z/Rinste3c54c7b608a
##  [2] /private/var/folders/4p/3cy0qmp15x9216qsqhh84kzm0000gn/T/RtmpLJJlUG/temp_libpathe3a419d138
##  [3] /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/library
##  * ── Packages attached to the search path.
## 
## ──────────────────────────────────────────────────────────────────────────────

  1. The one exception, discussed below, is for stratum variables that take both positive and negative values.↩︎

ggalluvial/inst/doc/labels.html0000644000176200001440000154605115146567315016304 0ustar liggesusers Labeling small strata

Labeling small strata

Jason Cory Brunson

2026-02-22

Setup

This brief vignette uses the vaccinations dataset included in {ggalluvial}. As in the technical introduction, the order of the levels is reversed to be more intuitive. Objects from other {ggplot2} extensions are accessed via :: and :::.

knitr::opts_chunk$set(fig.width = 6, fig.height = 4, fig.align = "center")
library(ggalluvial)
data(vaccinations)
vaccinations <- transform(vaccinations,
                          response = factor(response, rev(levels(response))))

Problem

The issue on the table: Strata are most helpful when they’re overlaid with text labels. Yet the strata often vary in height, and the labels in length, to such a degree that fitting the text inside the strata at a uniform size renders them illegible. In principle, the user could treat size as a variable aesthetic and manually fit text to strata, but this is cumbersome, and doesn’t help anyway in cases where large text is needed.

To illustrate the problem, check out the plot below. It’s by no means an egregious case, but it’ll do. (For a more practical example, see this question on StackOverflow, which prompted this vignette.)

ggplot(vaccinations,
       aes(x = survey, stratum = response, alluvium = subject, y = freq,
           fill = response, label = response)) +
  scale_x_discrete(expand = c(.1, 0)) +
  geom_flow(width = 1/4) +
  geom_stratum(alpha = .5, width = 1/4) +
  geom_text(stat = "stratum", size = 4) +
  theme(legend.position = "none") +
  ggtitle("vaccination survey responses", "labeled using `geom_text()`")

Fix

One option is to simply omit those labels that don’t fit within their strata. In response to an issue, v0.9.2 includes parameters in stat_stratum() to exclude strata outside a specified height range; while few would use this to omit the rectangles themselves, it can be used in tandem with geom_text() to shirk this problem, at least when the labels are concise:

ggplot(vaccinations,
       aes(x = survey, stratum = response, alluvium = subject, y = freq,
           fill = response, label = response)) +
  scale_x_discrete(expand = c(.1, 0)) +
  geom_flow(width = 1/4) +
  geom_stratum(alpha = .5, width = 1/4) +
  geom_text(stat = "stratum", size = 4, min.y = 100) +
  theme(legend.position = "none") +
  ggtitle(
    "vaccination survey responses",
    "labeled using `geom_text()` with `min.y = 100`"
  )

This is a useful fix for some cases. Still, if the goal is a publication-ready graphic, then it reaffirms the need for more adaptable and elegant solutions. Fortunately, two wonderful packages deliver with, shall we say, flowing colors.

Solutions

Two {ggplot2} extensions are well-suited to this problem: {ggrepel} and {ggfittext}. They provide new geom layers that use the output of existing stat layers to situate text: ggrepel::geom_text_repel() takes the same aesthetics as ggplot2::geom_text(), namely x, y, and label. In contrast, ggfittext::geom_fit_text() only specifically requires label but also needs enough information to determine the rectangle that will contain the text. This can be encoded as xmin and xmax or as x and width for the horizontal direction, and as ymin and ymax or as y and height for the vertical direction. Conveniently, ggalluvial::stat_stratum() produces more than enough information for both geoms, including x, xmin, xmax, and their vertical counterparts.

All this can be gleaned from the ggproto objects that construct the layers:

print(ggrepel::GeomTextRepel$required_aes)
## [1] "x"     "y"     "label"
print(ggfittext:::GeomFitText$required_aes)
## [1] "label"
print(ggfittext:::GeomFitText$setup_data)
## <ggproto method>
##   <Wrapper function>
##     function (...) 
## setup_data(...)
## 
##   <Inner function (f)>
##     function (data, params) 
## {
##     if (!(!is.null(data$xmin) & !is.null(data$xmax) | !is.null(data$x))) {
##         cli::cli_abort("geom_fit_text needs either 'xmin' and 'xmax', or 'x'")
##     }
##     if (!(!is.null(data$ymin) & !is.null(data$ymax) | !is.null(data$y))) {
##         cli::cli_abort("geom_fit_text needs either 'ymin' and 'ymax', or 'y'")
##     }
##     if ((!is.null(params$width)) & (!inherits(params$width, "unit"))) {
##         data$xmin <- data$x - params$width/2
##         data$xmax <- data$x + params$width/2
##     }
##     if ((!is.null(params$height)) & (!inherits(params$height, 
##         "unit"))) {
##         data$ymin <- data$y - params$height/2
##         data$ymax <- data$y + params$height/2
##     }
##     if (is.null(params$width) & is.null(data$xmin)) {
##         data$width <- ggplot2::resolution(data$x, FALSE) * 0.9
##         data$xmin <- data$x - data$width/2
##         data$xmax <- data$x + data$width/2
##         data$width <- NULL
##     }
##     if (is.null(params$height) & is.null(data$ymin)) {
##         data$height <- ggplot2::resolution(data$y, FALSE) * 0.9
##         data$ymin <- data$y - data$height/2
##         data$ymax <- data$y + data$height/2
##         data$height <- NULL
##     }
##     if (!is.null(params$formatter)) {
##         if (!is.function(params$formatter)) {
##             cli::cli_abort("`formatter` must be a function")
##         }
##         formatted_labels <- vapply(data$label, params$formatter, 
##             character(1), USE.NAMES = FALSE)
##         if ((!length(formatted_labels) == length(data$label)) | 
##             (!is.character(formatted_labels))) {
##             cli::cli_abort("`formatter` must produce a character vector of same length as input")
##         }
##         data$label <- formatted_labels
##     }
##     data$flip <- params$flip
##     data
## }
print(StatStratum$compute_panel)
## <ggproto method>
##   <Wrapper function>
##     function (...) 
## compute_panel(..., self = self)
## 
##   <Inner function (f)>
##     function (self, data, scales, decreasing = NULL, reverse = NULL, 
##     absolute = NULL, discern = FALSE, distill = "first", negate.strata = NULL, 
##     infer.label = FALSE, label.strata = NULL, min.y = NULL, max.y = NULL, 
##     min.height = NULL, max.height = NULL) 
## {
##     if (is.null(decreasing)) 
##         decreasing <- ggalluvial_opt("decreasing")
##     if (is.null(reverse)) 
##         reverse <- ggalluvial_opt("reverse")
##     if (is.null(absolute)) 
##         absolute <- ggalluvial_opt("absolute")
##     if (!is.null(label.strata)) {
##         defunct_parameter("label.strata", msg = "use `aes(label = after_stat(stratum))`.")
##         infer.label <- label.strata
##     }
##     if (infer.label) {
##         deprecate_parameter("infer.label", msg = "Use `aes(label = after_stat(stratum))`.")
##         if (is.null(data$label)) {
##             data$label <- data$stratum
##         }
##         else {
##             warning("Aesthetic `label` is specified, ", "so parameter `infer.label` will be ignored.")
##         }
##     }
##     diff_aes <- intersect(c(.color_diff_aesthetics, .text_aesthetics), 
##         names(data))
##     data$yneg <- data$y < 0
##     data$lode <- data$alluvium
##     distill <- distill_fun(distill)
##     weight <- data$weight
##     data$weight <- NULL
##     if (is.null(weight)) 
##         weight <- 1
##     data$n <- weight
##     data$count <- data$y * weight
##     by_vars <- c("x", "yneg", "stratum")
##     only_vars <- c(diff_aes)
##     sum_vars <- c("y", "n", "count")
##     if (!is.null(data$lode)) {
##         agg_lode <- stats::aggregate(data[, "lode", drop = FALSE], 
##             data[, by_vars], distill)
##     }
##     if (length(only_vars) > 0) {
##         agg_only <- stats::aggregate(data[, only_vars, drop = FALSE], 
##             data[, by_vars], only)
##     }
##     data <- stats::aggregate(data[, sum_vars], data[, by_vars], 
##         sum)
##     if (!is.null(data$lode)) {
##         data <- merge(data, agg_lode)
##     }
##     if (length(only_vars) > 0) {
##         data <- merge(data, agg_only)
##     }
##     data <- subset(data, y != 0)
##     data <- deposit_data(data, decreasing, reverse, absolute)
##     x_sums <- tapply(abs(data$count), data$x, sum, na.rm = TRUE)
##     data$prop <- data$count/x_sums[match(as.character(data$x), 
##         names(x_sums))]
##     data <- data[with(data, order(deposit)), , drop = FALSE]
##     data$ycum <- NA
##     for (xx in unique(data$x)) {
##         for (yn in c(FALSE, TRUE)) {
##             ww <- which(data$x == xx & data$yneg == yn)
##             data$ycum[ww] <- cumulate(data$y[ww])
##         }
##     }
##     data$ymin <- data$ycum - abs(data$y)/2
##     data$ymax <- data$ycum + abs(data$y)/2
##     data$y <- data$ycum
##     data$yneg <- NULL
##     data$ycum <- NULL
##     if (!is.null(min.height)) {
##         deprecate_parameter("min.height", "min.y")
##         min.y <- min.height
##     }
##     if (!is.null(max.height)) {
##         deprecate_parameter("max.height", "max.y")
##         max.y <- max.height
##     }
##     if (!is.null(min.y)) 
##         data <- subset(data, ymax - ymin >= min.y)
##     if (!is.null(max.y)) 
##         data <- subset(data, ymax - ymin <= max.y)
##     data
## }

I reached the specific solutions through trial and error. They may not be the best tricks for most cases, but they demonstrate what these packages can do. For many more examples, see the respective package vignettes: for {ggrepel}, and for {ggfittext}.

Solution 1: {ggrepel}

{ggrepel} is most often (in my experience) used to repel text away from symbols in a scatterplot, in whatever directions prevent them from overlapping the symbols and each other. In this case, however, it makes much more sense to align them vertically a fixed horizontal distance (nudge_x) away from the strata and repel them vertically from each other (direction = "y") just enough to print them without overlap. It takes an extra bit of effort to render text only for the strata at the first (or at the last) axis, but the result is worth it.

ggplot(vaccinations,
       aes(x = survey, stratum = response, alluvium = subject, y = freq,
           fill = response)) +
  scale_x_discrete(expand = c(.4, 0)) +
  geom_flow(width = 1/4) +
  geom_stratum(alpha = .5, width = 1/4) +
  scale_linetype_manual(values = c("blank", "solid")) +
  ggrepel::geom_text_repel(
    aes(label = ifelse(as.numeric(survey) == 1, as.character(response), NA)),
    stat = "stratum", size = 4, direction = "y", nudge_x = -.5
  ) +
  ggrepel::geom_text_repel(
    aes(label = ifelse(as.numeric(survey) == 3, as.character(response), NA)),
    stat = "stratum", size = 4, direction = "y", nudge_x = .5
  ) +
  theme(legend.position = "none") +
  ggtitle("vaccination survey responses", "labeled using `geom_text_repel()`")
## Warning: Removed 8 rows containing missing values or values outside the scale range
## (`geom_text_repel()`).
## Removed 8 rows containing missing values or values outside the scale range
## (`geom_text_repel()`).

Solution 2: {ggfittext}

{ggfittext} is simplicity itself: The strata are just rectangles, so no more parameter specifications are necessary to fit the text into them. One key parameter is min.size, which defaults to 4 and controls how small the text is allowed to get without being omitted.

ggplot(vaccinations,
       aes(x = survey, stratum = response, alluvium = subject, y = freq,
           fill = response, label = response)) +
  scale_x_discrete(expand = c(.1, 0)) +
  geom_flow(width = 1/4) +
  geom_stratum(alpha = .5, width = 1/4) +
  ggfittext::geom_fit_text(stat = "stratum", width = 1/4, min.size = 3) +
  theme(legend.position = "none") +
  ggtitle("vaccination survey responses", "labeled using `geom_fit_text()`")

Note that this solution requires {ggfittext} v0.6.0.

Appendix

sessioninfo::session_info()
## ─ Session info ───────────────────────────────────────────────────────────────
##  setting  value
##  version  R version 4.5.2 (2025-10-31)
##  os       macOS Tahoe 26.2
##  system   aarch64, darwin20
##  ui       X11
##  language (EN)
##  collate  C
##  ctype    en_US.UTF-8
##  tz       America/New_York
##  date     2026-02-22
##  pandoc   2.19 @ /opt/homebrew/bin/ (via rmarkdown)
##  quarto   1.8.25 @ /usr/local/bin/quarto
## 
## ─ Packages ───────────────────────────────────────────────────────────────────
##  package      * version date (UTC) lib source
##  bslib          0.9.0   2025-01-30 [3] CRAN (R 4.5.0)
##  cachem         1.1.0   2024-05-16 [3] CRAN (R 4.5.0)
##  cli            3.6.5   2025-04-23 [3] CRAN (R 4.5.0)
##  digest         0.6.39  2025-11-19 [3] CRAN (R 4.5.2)
##  dplyr          1.1.4   2023-11-17 [3] CRAN (R 4.5.0)
##  evaluate       1.0.5   2025-08-27 [3] CRAN (R 4.5.0)
##  farver         2.1.2   2024-05-13 [3] CRAN (R 4.5.0)
##  fastmap        1.2.0   2024-05-15 [3] CRAN (R 4.5.0)
##  generics       0.1.4   2025-05-09 [3] CRAN (R 4.5.0)
##  ggalluvial   * 0.12.6  2026-02-22 [1] local
##  ggfittext      0.10.3  2025-12-13 [3] CRAN (R 4.5.2)
##  ggplot2      * 4.0.2   2026-02-03 [3] CRAN (R 4.5.2)
##  ggrepel        0.9.6   2024-09-07 [3] CRAN (R 4.5.0)
##  glue           1.8.0   2024-09-30 [3] CRAN (R 4.5.0)
##  gtable         0.3.6   2024-10-25 [3] CRAN (R 4.5.0)
##  htmltools      0.5.9   2025-12-04 [3] CRAN (R 4.5.2)
##  jquerylib      0.1.4   2021-04-26 [3] CRAN (R 4.5.0)
##  jsonlite       2.0.0   2025-03-27 [3] CRAN (R 4.5.0)
##  knitr          1.51    2025-12-20 [3] CRAN (R 4.5.2)
##  labeling       0.4.3   2023-08-29 [3] CRAN (R 4.5.0)
##  lifecycle      1.0.5   2026-01-08 [3] CRAN (R 4.5.2)
##  magrittr       2.0.4   2025-09-12 [3] CRAN (R 4.5.0)
##  otel           0.2.0   2025-08-29 [3] CRAN (R 4.5.0)
##  pillar         1.11.1  2025-09-17 [3] CRAN (R 4.5.0)
##  pkgconfig      2.0.3   2019-09-22 [3] CRAN (R 4.5.0)
##  purrr          1.2.1   2026-01-09 [3] CRAN (R 4.5.2)
##  R6             2.6.1   2025-02-15 [3] CRAN (R 4.5.0)
##  RColorBrewer   1.1-3   2022-04-03 [3] CRAN (R 4.5.0)
##  Rcpp           1.1.1   2026-01-10 [3] CRAN (R 4.5.2)
##  rlang          1.1.7   2026-01-09 [3] CRAN (R 4.5.2)
##  rmarkdown      2.30    2025-09-28 [3] CRAN (R 4.5.0)
##  S7             0.2.1   2025-11-14 [3] CRAN (R 4.5.2)
##  sass           0.4.10  2025-04-11 [3] CRAN (R 4.5.0)
##  scales         1.4.0   2025-04-24 [3] CRAN (R 4.5.0)
##  sessioninfo    1.2.3   2025-02-05 [3] CRAN (R 4.5.0)
##  stringi        1.8.7   2025-03-27 [3] CRAN (R 4.5.0)
##  tibble         3.3.1   2026-01-11 [3] CRAN (R 4.5.2)
##  tidyr          1.3.2   2025-12-19 [3] CRAN (R 4.5.2)
##  tidyselect     1.2.1   2024-03-11 [3] CRAN (R 4.5.0)
##  vctrs          0.7.1   2026-01-23 [3] CRAN (R 4.5.2)
##  withr          3.0.2   2024-10-28 [3] CRAN (R 4.5.0)
##  xfun           0.56    2026-01-18 [3] CRAN (R 4.5.2)
##  yaml           2.3.12  2025-12-10 [3] CRAN (R 4.5.2)
## 
##  [1] /private/var/folders/4p/3cy0qmp15x9216qsqhh84kzm0000gn/T/RtmpqAXS9Z/Rinste3c54c7b608a
##  [2] /private/var/folders/4p/3cy0qmp15x9216qsqhh84kzm0000gn/T/RtmpLJJlUG/temp_libpathe3a419d138
##  [3] /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/library
##  * ── Packages attached to the search path.
## 
## ──────────────────────────────────────────────────────────────────────────────
ggalluvial/inst/doc/labels.R0000644000176200001440000000573715146567315015541 0ustar liggesusers## ----setup-------------------------------------------------------------------- knitr::opts_chunk$set(fig.width = 6, fig.height = 4, fig.align = "center") library(ggalluvial) data(vaccinations) vaccinations <- transform(vaccinations, response = factor(response, rev(levels(response)))) ## ----raw---------------------------------------------------------------------- ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + scale_x_discrete(expand = c(.1, 0)) + geom_flow(width = 1/4) + geom_stratum(alpha = .5, width = 1/4) + geom_text(stat = "stratum", size = 4) + theme(legend.position = "none") + ggtitle("vaccination survey responses", "labeled using `geom_text()`") ## ----omit--------------------------------------------------------------------- ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + scale_x_discrete(expand = c(.1, 0)) + geom_flow(width = 1/4) + geom_stratum(alpha = .5, width = 1/4) + geom_text(stat = "stratum", size = 4, min.y = 100) + theme(legend.position = "none") + ggtitle( "vaccination survey responses", "labeled using `geom_text()` with `min.y = 100`" ) ## ----aesthetics--------------------------------------------------------------- print(ggrepel::GeomTextRepel$required_aes) print(ggfittext:::GeomFitText$required_aes) print(ggfittext:::GeomFitText$setup_data) print(StatStratum$compute_panel) ## ----ggrepel------------------------------------------------------------------ ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + scale_x_discrete(expand = c(.4, 0)) + geom_flow(width = 1/4) + geom_stratum(alpha = .5, width = 1/4) + scale_linetype_manual(values = c("blank", "solid")) + ggrepel::geom_text_repel( aes(label = ifelse(as.numeric(survey) == 1, as.character(response), NA)), stat = "stratum", size = 4, direction = "y", nudge_x = -.5 ) + ggrepel::geom_text_repel( aes(label = ifelse(as.numeric(survey) == 3, as.character(response), NA)), stat = "stratum", size = 4, direction = "y", nudge_x = .5 ) + theme(legend.position = "none") + ggtitle("vaccination survey responses", "labeled using `geom_text_repel()`") ## ----ggfittext---------------------------------------------------------------- ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + scale_x_discrete(expand = c(.1, 0)) + geom_flow(width = 1/4) + geom_stratum(alpha = .5, width = 1/4) + ggfittext::geom_fit_text(stat = "stratum", width = 1/4, min.size = 3) + theme(legend.position = "none") + ggtitle("vaccination survey responses", "labeled using `geom_fit_text()`") ## ----session info------------------------------------------------------------- sessioninfo::session_info() ggalluvial/inst/doc/shiny.R0000644000176200001440000001767415146567321015431 0ustar liggesusers## ----setup, echo = FALSE, message = FALSE, warning = FALSE-------------------- knitr::opts_chunk$set(fig.width = 6, fig.height = 3, fig.align = "center") library(ggalluvial) pdf(NULL) ## ----run wide app locally, eval = FALSE--------------------------------------- # shiny::shinyAppDir(system.file("examples/ex-shiny-wide-data", package="ggalluvial")) ## ----pseudocode, eval = FALSE------------------------------------------------- # # '<(1) Load data.>' # # '<(2) Create "ggplot" object for alluvial plot and build it.>' # # '<(3) Extract data from built plot object used to create alluvium polygons.>' # # for (polygon in polygons) { # '<(4) Use polygon splines to generate coordinates of alluvium boundaries.>' # } # # '<(5) Define range of coordinates in grid units and plot units.>' # # for (polygon in polygons) { # '<(6) Convert coordinates from grid units to plot units.>' # } # # ui <- fluidPage( # '<(7) Output plot with hovering enabled.>' # # '<(8) Output tooltip.>' # ) # # # server <- function(input, output, session) { # # output$alluvial_plot <- renderPlot({ # '<(9) Render the plot.>' # }) # # output$tooltip <- renderText({ # if ('<(10) mouse cursor is within the plot panel>') { # if ('<(11) mouse cursor is within a stratum box>') { # '<(11b) Render stratum tooltip.>' # } else { # if ('<(12) mouse cursor is within an alluvium polygon>') { # '<(12b) Render alluvium tooltip.>' # } # } # } # }) # # } ## ----load dataset, eval = FALSE----------------------------------------------- # data(UCBAdmissions) # ucb_admissions <- as.data.frame(UCBAdmissions) ## ----set options, eval = FALSE------------------------------------------------ # # Offset, in pixels, for location of tooltip relative to mouse cursor, # # in both x and y direction. # offset <- 5 # # Width of node boxes # node_width <- 1/4 # # Width of alluvia # alluvium_width <- 1/3 ## ----draw and build plot, eval = FALSE---------------------------------------- # # Draw plot. # p <- ggplot(ucb_admissions, # aes(y = Freq, axis1 = Gender, axis2 = Dept)) + # geom_alluvium(aes(fill = Admit), knot.pos = 1/4, width = alluvium_width) + # geom_stratum(width = node_width, reverse = TRUE, fill = 'black', color = 'grey') + # geom_label(aes(label = after_stat(stratum)), # stat = "stratum", # reverse = TRUE, # size = rel(2)) + # theme_bw() + # scale_fill_brewer(type = "qual", palette = "Set1") + # scale_x_discrete(limits = c("Gender", "Dept"), expand = c(.05, .05)) + # scale_y_continuous(expand = c(0, 0)) + # ggtitle("UC Berkeley admissions and rejections", "by sex and department") + # theme(plot.title = element_text(size = rel(1)), # plot.subtitle = element_text(size = rel(1)), # legend.position = 'bottom') # # # Build the plot. # pbuilt <- ggplot_build(p) ## ----get xsplines and draw curves, eval = FALSE------------------------------- # # Add width parameter, and then convert built plot data to xsplines # data_draw <- transform(pbuilt$data[[1]], width = alluvium_width) # groups_to_draw <- split(data_draw, data_draw$group) # group_xsplines <- lapply(groups_to_draw, # data_to_alluvium) # # # Convert xspline coordinates to grid object. # xspline_coords <- lapply( # group_xsplines, # function(coords) grid::xsplineGrob(x = coords$x, # y = coords$y, # shape = coords$shape, # open = FALSE) # ) # # # Use grid::xsplinePoints to draw the curve for each polygon # xspline_points <- lapply(xspline_coords, grid::xsplinePoints) ## ----get coordinate ranges, eval = FALSE-------------------------------------- # # Define the x and y axis limits in grid coordinates (old) and plot # # coordinates (new) # xrange_old <- range(unlist(lapply( # xspline_points, # function(pts) as.numeric(pts$x) # ))) # yrange_old <- range(unlist(lapply( # xspline_points, # function(pts) as.numeric(pts$y) # ))) # xrange_new <- c(1 - alluvium_width/2, max(pbuilt$data[[1]]$x) + alluvium_width/2) # yrange_new <- c(0, sum(pbuilt$data[[2]]$count[pbuilt$data[[2]]$x == 1])) ## ----transform coordinates, eval = FALSE-------------------------------------- # # Define function to convert grid graphics coordinates to data coordinates # new_range_transform <- function(x_old, range_old, range_new) { # (x_old - range_old[1])/(range_old[2] - range_old[1]) * # (range_new[2] - range_new[1]) + range_new[1] # } # # # Using the x and y limits, convert the grid coordinates into plot coordinates. # polygon_coords <- lapply(xspline_points, function(pts) { # x_trans <- new_range_transform(x_old = as.numeric(pts$x), # range_old = xrange_old, # range_new = xrange_new) # y_trans <- new_range_transform(x_old = as.numeric(pts$y), # range_old = yrange_old, # range_new = yrange_new) # list(x = x_trans, y = y_trans) # }) ## ----ui, eval = FALSE--------------------------------------------------------- # ui <- fluidPage( # fluidRow(tags$div( # style = "position: relative;", # plotOutput("alluvial_plot", height = "650px", # hover = hoverOpts(id = "plot_hover") # ), # htmlOutput("tooltip"))) # ) ## ----renderPlot, eval = FALSE------------------------------------------------- # output$alluvial_plot <- renderPlot(p, res = 200) ## ----eval = FALSE------------------------------------------------------------- # output$tooltip <- renderText( # if(!is.null(input$plot_hover)) { ... } # ... # ) ## ----eval = FALSE------------------------------------------------------------- # hover <- input$plot_hover # x_coord <- round(hover$x) # # if(abs(hover$x - x_coord) < (node_width / 2)) { ... } else { ... } ## ----eval = FALSE------------------------------------------------------------- # node_row <- # pbuilt$data[[2]]$x == x_coord & hover$y > pbuilt$data[[2]]$ymin & hover$y < pbuilt$data[[2]]$ymax ## ----eval = FALSE------------------------------------------------------------- # node_label <- pbuilt$data[[2]]$stratum[node_row] # node_n <- pbuilt$data[[2]]$count[node_row] ## ----render strata tooltip, eval = FALSE-------------------------------------- # renderTags( # tags$div( # node_label, tags$br(), # "n =", node_n, # style = paste0( # "position: absolute; ", # "top: ", hover$coords_css$y + offset, "px; ", # "left: ", hover$coords_css$x + offset, "px; ", # "background: gray; ", # "padding: 3px; ", # "color: white; " # ) # ) # )$html ## ----test within polygon, eval = FALSE---------------------------------------- # hover_within_flow <- sapply( # polygon_coords, # function(pol) point.in.polygon(point.x = hover$x, # point.y = hover$y, # pol.x = pol$x, # pol.y = pol$y) # ) ## ----eval = FALSE------------------------------------------------------------- # if (any(hover_within_flow)) { ... } ## ----info for alluvia tooltip, eval = FALSE----------------------------------- # coord_id <- rev(which(hover_within_flow == 1))[1] # flow_label <- paste(groups_to_draw[[coord_id]]$stratum, collapse = ' -> ') # flow_n <- groups_to_draw[[coord_id]]$count[1] ## ----render alluvia tooltip, eval = FALSE------------------------------------- # renderTags( # tags$div( # flow_label, tags$br(), # "n =", flow_n, # style = paste0( # "position: absolute; ", # "top: ", hover$coords_css$y + offset, "px; ", # "left: ", hover$coords_css$x + offset, "px; ", # "background: gray; ", # "padding: 3px; ", # "color: white; " # ) # ) # )$html ## ----run long app locally, eval = FALSE--------------------------------------- # shiny::shinyAppDir(system.file("examples/ex-shiny-long-data", package="ggalluvial")) ggalluvial/inst/doc/shiny.html0000644000176200001440000015755715146567321016201 0ustar liggesusers Tooltips for ggalluvial plots in Shiny apps

Tooltips for ggalluvial plots in Shiny apps

Quentin D. Read

2026-02-22

Problem

In an interactive visualization, it is visually cleaner and better for interpretation if labels and other information appear as “tooltips” when the user hovers over or clicks on elements of the plot, rather than displaying all the labels on the plot at one time. However, the {ggalluvial} package does not natively include this functionality. It is possible to enable this using functions from several other packages. This vignette illustrates how to create Shiny apps that display an alluvial plot with tooltips that appear when the user hovers over two different plot elements: strata created with geom_stratum() and alluvia created with geom_alluvium(). An example is provided for wide-format alluvial data (the UCBAdmissions dataset) and long-format alluvial data (the vaccinations dataset).

The tooltips that appear when the user hovers over elements of the plot show a text label and the count in each group. If the user hovers or clicks somewhere inside a ggplot panel, Shiny automatically returns information about the location of the mouse cursor in plot coordinates. That means the main work we have to do is to extract or manually recalculate the coordinates of the different plot elements. With that information, we can determine which plot element the cursor is hovering over and display the appropriate information in the tooltip or other output method.

Note: The app demonstrated here depends on the packages {htmltools} and {sp}, in addition of course to {ggalluvial} and {shiny}. Please be aware that all of these packages will need to be installed on the server where your Shiny app is running.

Hovering over and clicking on strata

Enabling hovering over and clicking on strata is straightforward because of their rectangular shape. We only need the minimum and maximum x and y coordinates for each of the rectangles. The rectangles are evenly spaced along the x-axis, centered on positive integers beginning with 1. The width is set in geom_stratum() so, for example, we know that the x-coordinates of the first stratum are c(1 - width/2, 1 + width/2). The y-coordinates can be determined from the number of rows in the input data multiplied by their weights.

Hovering over and clicking on alluvia

Hovering over and clicking on alluvia are more difficult because the shapes of the alluvia are more complex. The default shape of the polygons includes an xspline curve drawn using the {grid} package. We need to manually reconstruct the coordinates of the polygons, then use sp::pointInPolygon() to detect which, if any, polygons the cursor is over.

App with wide-format alluvial data

The app is embedded below, followed by a walkthrough of the source code.

If you aren’t connected to the internet, or if you loaded this vignette using vignette('shiny', package = 'ggalluvial') rather than browseVignettes(package = 'ggalluvial'), the app will not display in the window above. You can view the app locally by running this line of code in your console:

shiny::shinyAppDir(system.file("examples/ex-shiny-wide-data", package="ggalluvial"))

Structure of the example app

Here, we will go over each section of the code in detail. The full source code is included in the package’s examples directory.

The app first (1) loads the data and (2) builds the plot. Then, (3) information is extracted from the built plot object to (4) manually recalculate the coordinates of the polygons that make up the plot. Internally, {ggalluvial} uses the {grid} package to draw the polygons, so the next steps are (5) to define the minima and maxima of the x and y axes in {grid} units and the units that appear on the plot’s coordinate system, and (6) to convert the polygon coordinates from {grid} units plot units. Next, the user interface is defined, including output of (7) the plot image and (8) the tooltip. The final block of code is the server function, which first (9) renders the plot. Finally, the tooltip is defined. This includes (10) logic to determine whether the mouse cursor is inside the plot panel, then (11) whether it is hovering over a stratum, (12) an alluvium, or neither, based on the mouse coordinates provided by Shiny. If the mouse is hovering over a plot element, the app finds appropriate information and prints it in a small “tooltip” box next to the mouse cursor (11b and 12b).

This is the structure of the app in pseudocode.

'<(1) Load data.>'

'<(2) Create "ggplot" object for alluvial plot and build it.>'

'<(3) Extract data from built plot object used to create alluvium polygons.>'

for (polygon in polygons) {
     '<(4) Use polygon splines to generate coordinates of alluvium boundaries.>'
}

'<(5) Define range of coordinates in grid units and plot units.>'

for (polygon in polygons) {    
     '<(6) Convert coordinates from grid units to plot units.>'
}

ui <- fluidPage(
     '<(7) Output plot with hovering enabled.>'
     
     '<(8) Output tooltip.>'
)


server <- function(input, output, session) {
  
  output$alluvial_plot <- renderPlot({
    '<(9) Render the plot.>'
  })
  
  output$tooltip <- renderText({
    if ('<(10) mouse cursor is within the plot panel>') {
      if ('<(11) mouse cursor is within a stratum box>') {
        '<(11b) Render stratum tooltip.>'
      } else {
        if ('<(12) mouse cursor is within an alluvium polygon>') {
          '<(12b) Render alluvium tooltip.>'
        }
      }
    }
  })
  
}

Loading data

The UC-Berkeley admissions dataset, UCBAdmissions, is used in this example. After loading the necessary packages, the first thing we do in the app is load the data and coerce from array to data frame.

data(UCBAdmissions)
ucb_admissions <- as.data.frame(UCBAdmissions)

Next we set offset, the distance from cursor to tooltip, in pixels, in both x and y directions. We also set node_width and alluvium_width here, which are used as arguments to geom_stratum() and geom_alluvium() below, and again later to determine whether the mouse cursor is hovering over a stratum/alluvium.

# Offset, in pixels, for location of tooltip relative to mouse cursor,
# in both x and y direction.
offset <- 5
# Width of node boxes
node_width <- 1/4
# Width of alluvia
alluvium_width <- 1/3

Drawing the plot and extracting coordinates

Next, we create the ggplot object for the alluvial plot, then we call the ggplot_build() function to build the plot without displaying it.

# Draw plot.
p <- ggplot(ucb_admissions,
            aes(y = Freq, axis1 = Gender, axis2 = Dept)) + 
  geom_alluvium(aes(fill = Admit), knot.pos = 1/4, width = alluvium_width) + 
  geom_stratum(width = node_width, reverse = TRUE, fill = 'black', color = 'grey') + 
  geom_label(aes(label = after_stat(stratum)), 
             stat = "stratum", 
             reverse = TRUE, 
             size = rel(2)) + 
  theme_bw() +
  scale_fill_brewer(type = "qual", palette = "Set1") +
  scale_x_discrete(limits = c("Gender", "Dept"), expand = c(.05, .05)) +
  scale_y_continuous(expand = c(0, 0)) +
  ggtitle("UC Berkeley admissions and rejections", "by sex and department") +
  theme(plot.title = element_text(size = rel(1)),
        plot.subtitle = element_text(size = rel(1)),
        legend.position = 'bottom')

# Build the plot. 
pbuilt <- ggplot_build(p)

Now for the hard part: reverse-engineering the coordinates of the alluvia polygons. This makes use of pbuilt$data[[1]], a data frame with the individual elements of the alluvial plot. We add an additional column for width using the value we set above, then split the data frame by group (groups correspond to the individual alluvium polygons). We apply the function data_to_alluvium() to each element of the list to get the coordinates of the “skeleton” of the x-spline curve. Then, we pass these coordinates to the function grid::xsplineGrob() to fill in the smooth spline curves and convert them into a {grid} object. We pass the resulting object to grid::xsplinePoints(), which converts back into numeric vectors. At this point we now have the coordinates of the alluvium polygons. The object xspline_points is a list with length equal to the number of alluvium polygons in the plot. Each element of the list is a list with elements x and y, which are numeric vectors.

# Add width parameter, and then convert built plot data to xsplines
data_draw <- transform(pbuilt$data[[1]], width = alluvium_width)
groups_to_draw <- split(data_draw, data_draw$group)
group_xsplines <- lapply(groups_to_draw,
                         data_to_alluvium) 

# Convert xspline coordinates to grid object.
xspline_coords <- lapply(
  group_xsplines,
  function(coords) grid::xsplineGrob(x = coords$x, 
                                     y = coords$y, 
                                     shape = coords$shape, 
                                     open = FALSE)
)

# Use grid::xsplinePoints to draw the curve for each polygon
xspline_points <- lapply(xspline_coords, grid::xsplinePoints)

The coordinates we have are in {grid} plotting units but we need to convert them into the same units as the axes on the plot. We do this by determining the range of the x and y-axes in {grid} units (xrange_old and yrange_old). Then we fix the range of the x axis as 1 to the number of strata, adjusted by half the alluvium width on each side. Next we fix the range of the y-axis to the sum of the counts across all alluvia at one node.

# Define the x and y axis limits in grid coordinates (old) and plot
# coordinates (new)
xrange_old <- range(unlist(lapply(
  xspline_points,
  function(pts) as.numeric(pts$x)
)))
yrange_old <- range(unlist(lapply(
  xspline_points,
  function(pts) as.numeric(pts$y)
)))
xrange_new <- c(1 - alluvium_width/2, max(pbuilt$data[[1]]$x) + alluvium_width/2) 
yrange_new <- c(0, sum(pbuilt$data[[2]]$count[pbuilt$data[[2]]$x == 1]))

We define a function new_range_transform() inline and apply it to each set of coordinates. This returns another list, polygon_coords, with the same structure as xspline_points. Now we have the coordinates of the polygons in plot units!

# Define function to convert grid graphics coordinates to data coordinates
new_range_transform <- function(x_old, range_old, range_new) {
  (x_old - range_old[1])/(range_old[2] - range_old[1]) *
    (range_new[2] - range_new[1]) + range_new[1]
}

# Using the x and y limits, convert the grid coordinates into plot coordinates.
polygon_coords <- lapply(xspline_points, function(pts) {
  x_trans <- new_range_transform(x_old = as.numeric(pts$x), 
                                 range_old = xrange_old, 
                                 range_new = xrange_new)
  y_trans <- new_range_transform(x_old = as.numeric(pts$y), 
                                 range_old = yrange_old, 
                                 range_new = yrange_new)
  list(x = x_trans, y = y_trans)
})

User interface

The app includes a minimal user interface with two output elements.

ui <- fluidPage(
  fluidRow(tags$div(
    style = "position: relative;",
    plotOutput("alluvial_plot", height = "650px", 
               hover = hoverOpts(id = "plot_hover")
               ),
    htmlOutput("tooltip")))
)

The elements are:

  • a plotOutput with the argument hover defined, to enable behavior determined by the cursor’s plot coordinates whenever the user hovers over the plot.
  • an htmlOutput for the tooltip that appears next to the cursor on hover.

The elements are wrapped in a fluidRow() and a div() tag.

Note: This vignette only illustrates how to display output when the user hovers over an element. If you want to display output when the user clicks on an element, the corresponding argument to plotOutput() is click = clickOpts(id = "plot_click"). This will return the location of the mouse cursor in plot coordinates when the user clicks somewhere within the plot panel.

Also Note: In the example presented here, all of the plot drawing and coordinate extracting code is outside the server() function, because the plot itself does not change with user input. However if you are building an app where the plot changes in response to user input, for example a menu of options of which variables to display, the plot drawing code has to be inside the renderPlot() expression. This means that the coordinates may need to be recalculated each time the user input changes as well. In that case, you may need to use the global assignment operator <<- so that the coordinates are accessible outside the renderPlot() expression.

Server function

In the server function, we first call renderPlot() to draw the plot in the app window.

output$alluvial_plot <- renderPlot(p, res = 200)

Next, we define the tooltip with a renderText() expression. Within that expression, we first extract the cursor’s plot coordinates from the user input. We determine whether the cursor is hovering over a stratum and if so, display the appropriate tooltip.

screenshot of tooltip on stratum

If the mouse cursor is not hovering over a stratum, we determine whether it is hovering over an alluvium polygon and if so, display different information in the tooltip.

screenshot of tooltip on alluvium

If the mouse cursor is hovering over an empty region of the plot, renderText() returns nothing and no tooltip appears.

screenshot of cursor over empty region

Let’s take a deeper dive into the logic used to determine the text that appears in the tooltip.

First, we check whether the cursor is inside the plot panel. If it is not, the element plot_hover of the input will be NULL. In that case renderText() will return nothing and no tooltip will appear.

output$tooltip <- renderText(
  if(!is.null(input$plot_hover)) { ... }
  ...
)

Hovering over a stratum

Next, we check whether the cursor is over a stratum. We round the x-coordinate of the mouse cursor in data units to the nearest integer, then determine whether the x-coordinate is within node_width/2 of that integer. If so, the mouse cursor is horizontally within the box. Here the if-else statement includes behavior to display the tooltip for a stratum if true, and an alluvium if false.

hover <- input$plot_hover
x_coord <- round(hover$x)
    
if(abs(hover$x - x_coord) < (node_width / 2)) { ... } else { ... }

If the condition is true, we need to find the index of the row of the input data that goes with the stratum the cursor is on. The data frame pbuilt$data[[2]] includes columns x, ymin, and ymax that define the x-coordinate of the center of the stratum, and the minimum and maximum y-coordinates of the stratum. We find the row index of that data frame where x is equal to the rounded x-coordinate of the cursor, and the y-coordinate of the cursor falls between ymin and ymax.

node_row <- 
  pbuilt$data[[2]]$x == x_coord & hover$y > pbuilt$data[[2]]$ymin & hover$y < pbuilt$data[[2]]$ymax

To find the information to display in the tooltip, we get the name of the stratum as well as its width from the data in pbuilt.

node_label <- pbuilt$data[[2]]$stratum[node_row]
node_n <- pbuilt$data[[2]]$count[node_row]

Finally, we render a tooltip using the div tag. We provide the text to display as arguments to htmltools::renderTags(). We also paste CSS style information together and pass it to the style argument. Note that the tooltip positioning is provided in CSS coordinates (pixels), not data coordinates. This does not require any additional effort on our part because plot_hover also includes an element called coords_css, which contains the mouse cursor location in pixel units.

renderTags(
  tags$div(
    node_label, tags$br(),
    "n =", node_n,
    style = paste0(
      "position: absolute; ",
      "top: ", hover$coords_css$y + offset, "px; ",
      "left: ", hover$coords_css$x + offset, "px; ",
      "background: gray; ",
      "padding: 3px; ",
      "color: white; "
    )
  )
)$html

Hovering over an alluvium

If the cursor is not over a stratum, the next nested if-statement checks whether it is over an alluvium. This is done using the function sp::point.in.polygon() applied across each of the polygons for which we defined the coordinates inside the renderPlot() expression.

hover_within_flow <- sapply(
  polygon_coords,
  function(pol) point.in.polygon(point.x = hover$x, 
                                 point.y = hover$y, 
                                 pol.x = pol$x, 
                                 pol.y = pol$y)
)

If at least one polygon is beneath the mouse cursor, we locate the corresponding row in the input data and extract information to display in the tooltip. (If the condition is not met, that means the cursor is hovering over an empty area of the plot, so no tooltip appears.)

if (any(hover_within_flow)) { ... }

In the situation where there are more than one polygon overlapping, we get the information for the polygon that is plotted last by calling rev() on the logical vector returned by point.in.polygon(). This means that the tooltip will display information from the alluvium that appears “on top” in the plot. In this example, we display the names of the nodes that the alluvium connects, with arrows between them, and the width of the alluvium.

coord_id <- rev(which(hover_within_flow == 1))[1]
flow_label <- paste(groups_to_draw[[coord_id]]$stratum, collapse = ' -> ')
flow_n <- groups_to_draw[[coord_id]]$count[1]

We render a tooltip using identical syntax to the one above.

renderTags(
  tags$div(
    flow_label, tags$br(),
    "n =", flow_n,
    style = paste0(
      "position: absolute; ",
      "top: ", hover$coords_css$y + offset, "px; ",
      "left: ", hover$coords_css$x + offset, "px; ",
      "background: gray; ",
      "padding: 3px; ",
      "color: white; "
    )
  )
)$html

App with long-format alluvial data

The vaccinations dataset is used for long-format alluvial data. The app is embedded at the bottom of this document, but we don’t need to walk through the source code because it’s almost identical to the code above. The output of ggplot_build() that is used to find the polygon coordinates and information for the tooltips has a consistent structure regardless of the initial format of the input data. Therefore, the calculation of polygon coordinates, user interface, and server functions of the two apps are identical. The only difference is in the initial creation of the ggplot() object. Refer back to the primary vignette for several example plots made both with long and with wide data.

The app is embedded below.

Again, if the app doesn’t display in the window above for whatever reason, you can view it locally by running this line of code in your console:

shiny::shinyAppDir(system.file("examples/ex-shiny-long-data", package="ggalluvial"))

Conclusion

This vignette demonstrates how to enable tooltips for {ggalluvial} plots in Shiny apps. This is one of many possible ways to do that. It may not be the optimal way — other solutions are certainly possible!

The full source code for both of these Shiny apps is included with the {ggalluvial} package in the ‘examples’ subdirectory where the package is installed: the source files are ggalluvial/examples/ex-shiny-wide-data/app.R and ggalluvial/examples/ex-shiny-long-data/app.R.

ggalluvial/inst/doc/order-rectangles.R0000644000176200001440000001514115146567320017521 0ustar liggesusers## ----setup-------------------------------------------------------------------- knitr::opts_chunk$set(fig.width = 6, fig.height = 3, fig.align = "center") library(ggalluvial) ## ----data--------------------------------------------------------------------- # toy data set set.seed(0) toy <- data.frame( subject = rep(LETTERS[1:5], times = 4), collection = rep(1:4, each = 5), category = rep( sample(c("X", "Y"), 16, replace = TRUE), rep(c(1, 2, 1, 1), times = 4) ), class = c("one", "one", "one", "two", "two") ) print(toy) ## ----plot--------------------------------------------------------------------- ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + geom_alluvium(aes(fill = class)) + geom_stratum() ## ----strata------------------------------------------------------------------- # collection point and category variables only data <- structure(toy[, 2:3], names = c("x", "stratum")) # required fields for stat transformations data$y <- 1 data$PANEL <- 1 # stratum transformation StatStratum$compute_panel(data) ## ----strata plot-------------------------------------------------------------- ggplot(toy, aes(x = collection, stratum = category)) + stat_stratum() + stat_stratum(geom = "text", aes(label = category)) ## ----strata reverse----------------------------------------------------------- # stratum transformation with strata in original order StatStratum$compute_panel(data, reverse = FALSE) ggplot(toy, aes(x = collection, stratum = category)) + stat_stratum(reverse = FALSE) + stat_stratum(geom = "text", aes(label = category), reverse = FALSE) ## ----strata decreasing-------------------------------------------------------- # stratum transformation with strata in original order StatStratum$compute_panel(data, reverse = FALSE) ggplot(toy, aes(x = collection, stratum = category)) + stat_stratum(decreasing = TRUE) + stat_stratum(geom = "text", aes(label = category), decreasing = TRUE) ## ----alluvia------------------------------------------------------------------ # collection point, category, and subject variables data <- structure(toy[, 1:3], names = c("alluvium", "x", "stratum")) # required fields for stat transformations data$y <- 1 data$PANEL <- 1 # alluvium transformation StatAlluvium$compute_panel(data) ## ----alluvia plot------------------------------------------------------------- ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class)) + stat_stratum(alpha = .25) + stat_alluvium(geom = "text", aes(label = subject)) ## ----flows-------------------------------------------------------------------- # flow transformation StatFlow$compute_panel(data) ## ----flows plot--------------------------------------------------------------- ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_stratum() + stat_flow(aes(fill = class)) + stat_flow(geom = "text", aes(label = subject, hjust = after_stat(flow) == "to")) ## ----lode zigzag-------------------------------------------------------------- for (i in 1:4) print(lode_zigzag(4, i)) ## ----alluvia plot w/ backfront guidance--------------------------------------- for (i in 1:4) print(lode_backfront(4, i)) ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class), lode.guidance = "backfront") + stat_stratum() + stat_alluvium(geom = "text", aes(label = subject), lode.guidance = "backfront") ## ----alluvia plot w/ backward guidance---------------------------------------- for (i in 1:4) print(lode_backward(4, i)) ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class), lode.guidance = "backward") + stat_stratum() + stat_alluvium(geom = "text", aes(label = subject), lode.guidance = "backward") ## ----alluvia plot w/ strong aesthetic binding--------------------------------- ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class, label = subject), aes.bind = "alluvia") + stat_stratum() + stat_alluvium(geom = "text", aes(fill = class, label = subject), aes.bind = "alluvia") ## ----alluvia plot w/ weak aesthetic binding----------------------------------- ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class, label = subject), aes.bind = "flows") + stat_stratum() + stat_alluvium(geom = "text", aes(fill = class, label = subject), aes.bind = "flows") ## ----flows plots w/ aesthetic binding----------------------------------------- ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_flow(aes(fill = class, label = subject), aes.bind = "flows") + stat_stratum() + stat_flow(geom = "text", aes(fill = class, label = subject, hjust = after_stat(flow) == "to"), aes.bind = "flows") ## ----alluvia plot w/ manual lode ordering------------------------------------- lode_ord <- rep(seq(5), times = 4) ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_alluvium(aes(fill = class, order = lode_ord)) + stat_stratum() + stat_alluvium(geom = "text", aes(fill = class, order = lode_ord, label = subject)) ## ----flows plot w/ manual lode ordering--------------------------------------- ggplot(toy, aes(x = collection, stratum = category, alluvium = subject)) + stat_flow(aes(fill = class, order = lode_ord)) + stat_stratum() + stat_flow(geom = "text", aes(fill = class, order = lode_ord, label = subject, hjust = after_stat(flow) == "to")) ## ----bar plot with negative observations-------------------------------------- set.seed(78) toy$sign <- sample(c(-1, 1), nrow(toy), replace = TRUE) print(toy) ggplot(toy, aes(x = collection, y = sign)) + geom_bar(aes(fill = class), stat = "identity") ## ----flows plot w/ negative strata-------------------------------------------- ggplot(toy, aes(x = collection, stratum = category, alluvium = subject, y = sign)) + geom_flow(aes(fill = class)) + geom_stratum() + geom_text(stat = "stratum", aes(label = category)) ## ----alluvia plot w/ negative strata------------------------------------------ ggplot(toy, aes(x = collection, stratum = category, alluvium = subject, y = sign)) + geom_alluvium(aes(fill = class), absolute = FALSE) + geom_stratum(absolute = FALSE) + geom_text(stat = "alluvium", aes(label = subject), absolute = FALSE) ## ----session info------------------------------------------------------------- sessioninfo::session_info() ggalluvial/README.md0000644000176200001440000001666415146461454013707 0ustar liggesusers # ggalluvial [![Travis](https://api.travis-ci.com/corybrunson/ggalluvial.svg?branch=main)](https://app.travis-ci.com/corybrunson/ggalluvial) [![CRAN](http://www.r-pkg.org/badges/version/ggalluvial)](https://cran.r-project.org/package=ggalluvial) [![downloads](https://cranlogs.r-pkg.org/badges/ggalluvial)](https://cran.r-project.org/package=ggalluvial) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3836748.svg)](https://doi.org/10.5281/zenodo.3836747) [![JOSS](https://joss.theoj.org/papers/10.21105/joss.02017/status.svg)](https://doi.org/10.21105/joss.02017) This is a [{ggplot2} extension](https://exts.ggplot2.tidyverse.org/) for alluvial plots. ## Design 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}](https://github.com/mbojan/alluvial) package, but the {ggplot2} framework induced several conspicuous differences: - {alluvial} understands a variety of inputs (vectors, lists, data frames), whereas {ggalluvial} requires a single data frame; - {alluvial} uses each variable of these inputs as a dimension of the data, whereas {ggalluvial} requires the user to specify the dimensions, either as separate aesthetics or as [key-value pairs](https://tidyr.tidyverse.org/); - {alluvial} produces both the *alluvia*, which link cohorts across multiple dimensions, and (what are here called) the *strata*, which partition the data along each dimension, in a single function; whereas {ggalluvial} relies on separate layers (stats and geoms) to produce strata, alluvia, and alluvial segments called *lodes* and *flows*. Additionally, {ggalluvial} arranges these layers vertically without gaps, so that the secondary plotting axis indicates the cumulative values of the strata at each dimension. ## Installation The latest stable release can be installed from CRAN: ``` r install.packages("ggalluvial") ``` The [`cran` branch](https://github.com/corybrunson/ggalluvial/tree/cran) will contain the version most recently submitted to [CRAN](https://cran.r-project.org/package=ggalluvial). It is duplicated in the `master` branch, from which source the [website](https://corybrunson.github.io/ggalluvial/) is built. The development version can be installed from the (default) `main` branch on GitHub: ``` r 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](https://github.com/corybrunson/ggalluvial/tree/optimization) contains a development version with experimental functions to reduce the number or area of alluvial overlaps (see issue [\#6](https://github.com/corybrunson/ggalluvial/issues/6)). Install it as follows: ``` r 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. ## Usage ### Example Here is how to generate an alluvial plot representation of the multi-dimensional categorical dataset of passengers on the Titanic: ``` r titanic_wide <- data.frame(Titanic) head(titanic_wide) #> Class Sex Age Survived Freq #> 1 1st Male Child No 0 #> 2 2nd Male Child No 0 #> 3 3rd Male Child No 35 #> 4 Crew Male Child No 0 #> 5 1st Female Child No 0 #> 6 2nd Female Child No 0 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") ``` ![](man/figures/README-unnamed-chunk-6-1.png) The data is in “wide” format, but {ggalluvial} also recognizes data in “long” format and can convert between the two: ``` r titanic_long <- to_lodes_form(data.frame(Titanic), key = "Demographic", axes = 1:3) head(titanic_long) #> Survived Freq alluvium Demographic stratum #> 1 No 0 1 Class 1st #> 2 No 0 2 Class 2nd #> 3 No 35 3 Class 3rd #> 4 No 0 4 Class Crew #> 5 No 0 5 Class 1st #> 6 No 0 6 Class 2nd 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") ``` ![](man/figures/README-unnamed-chunk-7-1.png) ### Documentation For detailed discussion of the data formats recognized by {ggalluvial} and several examples that illustrate its flexibility and limitations, read the technical vignette: ``` r vignette(topic = "ggalluvial", package = "ggalluvial") ``` Several additional vignettes offer detailed solutions to specific needs: - “Labeling small strata” (`"labels"`) for how to elegantly label strata of a wide range of heights in an alluvial plot; - “The Order of the Rectangles” (`"order-rectangles"`) for how to control the positioning of strata and lodes in an alluvial plot; and - “Tooltips for ggalluvial plots in Shiny apps” (`"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 - any layer (`stat_*` or `geom_*`), - the conversion functions (`to_*_form`), and - the data sets installed with the package (`vaccinations` and `majors`). ### Short form 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](https://jtr13.github.io/cc21fall2/index.html): - an [introduction](https://jtr13.github.io/cc21fall2/ggalluvial-cheatsheet.html) by Meggie Wen (Chapter 33) - a [cheat sheet](https://cheatography.com/seleven/cheat-sheets/ggalluvial/) by Qingyi Zhang (Chapter 14) ## Acknowledgments ### Resources Development of this package benefitted from the use of equipment and the support of colleagues at [UConn Health](https://health.uconn.edu/) and at [UF Health](https://ufhealth.org/). ### Contribute 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](https://github.com/corybrunson/ggalluvial/blob/main/CONTRIBUTING.md) file for guidance, and please respect the [Code of Conduct](https://github.com/corybrunson/ggalluvial/blob/main/CODE_OF_CONDUCT.md). ### Cite 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")`. ggalluvial/build/0000755000176200001440000000000015146567321013512 5ustar liggesusersggalluvial/build/vignette.rds0000644000176200001440000000047115146567321016053 0ustar liggesusersRMo0 mavX .kFCU q@(4Uqg=[FHҏH II))MY )Ε <pL \jWRo֪rJMh',:R jK&G$C ѧm`+8^O n9f Ƿ'>skmIwuI2}JW3@0J}t ~L¯7kvRSs/v}_`wbwo/ /eggalluvial/build/partial.rdb0000644000176200001440000000007515146567306015644 0ustar liggesusersb```b`aeb`b1 H020piּb C"F$7ggalluvial/man/0000755000176200001440000000000015146420370013156 5ustar liggesusersggalluvial/man/geom_lode.Rd0000644000176200001440000001104615146420370015401 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/geom-lode.r \name{geom_lode} \alias{geom_lode} \title{Lodes at intersections of alluvia and strata} \usage{ geom_lode( mapping = NULL, data = NULL, stat = "alluvium", position = "identity", width = 1/3, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ... ) } \arguments{ \item{mapping}{Set of aesthetic mappings created by \code{\link[ggplot2:aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level of the plot. You must supply \code{mapping} if there is no plot mapping.} \item{data}{The data to be displayed in this layer. There are three options: If \code{NULL}, the default, the data is inherited from the plot data as specified in the call to \code{\link[ggplot2:ggplot]{ggplot()}}. A \code{data.frame}, or other object, will override the plot data. All objects will be fortified to produce a data frame. See \code{\link[ggplot2:fortify]{fortify()}} for which variables will be created. A \code{function} will be called with a single argument, the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} \item{stat}{The statistical transformation to use on the data; override the default.} \item{position}{Position adjustment, either as a string naming the adjustment (e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a position adjustment function. Use the latter if you need to change the settings of the adjustment.} \item{width}{Numeric; the width of each stratum, as a proportion of the distance between axes. Defaults to 1/3.} \item{na.rm}{Logical: if \code{FALSE}, the default, \code{NA} lodes are not included; if \code{TRUE}, \code{NA} lodes constitute a separate category, plotted in grey (regardless of the color scheme).} \item{show.legend}{logical. Should this layer be included in the legends? \code{NA}, the default, includes if any aesthetics are mapped. \code{FALSE} never includes, and \code{TRUE} always includes. It can also be a named logical vector to finely select the aesthetics to display.} \item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[ggplot2:borders]{borders()}}.} \item{...}{Additional arguments passed to \code{\link[ggplot2:layer]{ggplot2::layer()}}.} } \description{ \code{geom_alluvium} receives a dataset of the horizontal (\code{x}) and vertical (\code{y}, \code{ymin}, \code{ymax}) positions of the \strong{lodes} of an alluvial plot, the intersections of the alluvia with the strata. It plots rectangles for these lodes of a provided \code{width}. } \section{Aesthetics}{ \code{geom_alluvium}, \code{geom_flow}, \code{geom_lode}, and \code{geom_stratum} understand the following aesthetics (required aesthetics are in bold): \itemize{ \item \strong{\code{x}} \item \strong{\code{y}} \item \strong{\code{ymin}} \item \strong{\code{ymax}} \item \code{alpha} \item \code{colour} \item \code{fill} \item \code{linetype} \item \code{size} \item \code{group} } \code{group} is used internally; arguments are ignored. Alluvium, flow, and lode geoms default to \code{alpha = 0.5}. Learn more about setting these aesthetics in \code{vignette("ggplot2-specs", package = "ggplot2")}. } \section{Defunct parameters}{ The previously defunct parameters \code{axis_width} and \code{ribbon_bend} have been discontinued. Use \code{width} and \code{knot.pos} instead. } \examples{ # one axis ggplot(as.data.frame(Titanic), aes(y = Freq, axis = Class)) + geom_lode(aes(fill = Class, alpha = Survived)) + scale_x_discrete(limits = c("Class")) + scale_alpha_manual(values = c(.25, .75)) gg <- ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, fill = Survived)) # alluvia and lodes gg + geom_alluvium() + geom_lode() # lodes as strata gg + geom_alluvium() + geom_stratum(stat = "alluvium") } \seealso{ \code{\link[ggplot2:layer]{ggplot2::layer()}} for additional arguments and \code{\link[=stat_alluvium]{stat_alluvium()}} and \code{\link[=stat_stratum]{stat_stratum()}} for the corresponding stats. Other alluvial geom layers: \code{\link{geom_alluvium}()}, \code{\link{geom_flow}()}, \code{\link{geom_stratum}()} } \concept{alluvial geom layers} ggalluvial/man/majors.Rd0000644000176200001440000000114514112432105014730 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/data.r \name{majors} \alias{majors} \title{Students' declared majors across several semesters} \format{ A data frame with 80 rows and 3 variables: \describe{ \item{\code{student}}{student identifier} \item{\code{semester}}{character tag for odd-numbered semesters} \item{\code{curriculum}}{declared major program} } } \description{ This data set follows the major curricula of 10 students across 8 academic semesters. Missing values indicate undeclared majors. The data were kindly contributed by Dario Bonaretti. } \keyword{datasets} ggalluvial/man/vaccinations.Rd0000644000176200001440000000232414112432105016116 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/data.r \docType{data} \name{vaccinations} \alias{vaccinations} \title{Influenza vaccination survey responses} \format{ A data frame with 117 rows and 5 variables: \describe{ \item{\code{freq}}{number of respondents represented in each row} \item{\code{subject}}{identifier linking respondents across surveys} \item{\code{survey}}{survey designation from the ALP website} \item{\code{start_date}}{start date of survey} \item{\code{end_date}}{end date of survey} \item{\code{response}}{discretized probability of vaccinating for influenza} } } \source{ \url{https://alpdata.rand.org/} } \usage{ vaccinations } \description{ This data set is aggregated from three RAND American Life Panel (ALP) surveys that asked respondents their probability of vaccinating for influenza. Their responses were discretized to "Never" (0\%), "Always" (100\%), or "Sometimes" (any other value). After merging, missing responses were coded as "Missing" and respondents were grouped and counted by all three coded responses. The pre-processed data were kindly contributed by Raffaele Vardavas, and the complete surveys are freely available at the ALP website. } \keyword{datasets} ggalluvial/man/stat_flow.Rd0000644000176200001440000003002115146420370015443 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/stat-flow.r \name{stat_flow} \alias{stat_flow} \title{Flow positions} \usage{ stat_flow( mapping = NULL, data = NULL, geom = "flow", position = "identity", decreasing = NULL, reverse = NULL, absolute = NULL, discern = FALSE, negate.strata = NULL, aes.bind = NULL, infer.label = FALSE, min.y = NULL, max.y = NULL, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ... ) } \arguments{ \item{mapping}{Set of aesthetic mappings created by \code{\link[ggplot2:aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level of the plot. You must supply \code{mapping} if there is no plot mapping.} \item{data}{The data to be displayed in this layer. There are three options: If \code{NULL}, the default, the data is inherited from the plot data as specified in the call to \code{\link[ggplot2:ggplot]{ggplot()}}. A \code{data.frame}, or other object, will override the plot data. All objects will be fortified to produce a data frame. See \code{\link[ggplot2:fortify]{fortify()}} for which variables will be created. A \code{function} will be called with a single argument, the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} \item{geom}{The geometric object to use display the data; override the default.} \item{position}{Position adjustment, either as a string naming the adjustment (e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a position adjustment function. Use the latter if you need to change the settings of the adjustment.} \item{decreasing}{Logical; whether to arrange the strata at each axis in the order of the variable values (\code{NA}, the default), in ascending order of totals (largest on top, \code{FALSE}), or in descending order of totals (largest on bottom, \code{TRUE}).} \item{reverse}{Logical; if \code{decreasing} is \code{NA}, whether to arrange the strata at each axis in the reverse order of the variable values, so that they match the order of the values in the legend. Ignored if \code{decreasing} is not \code{NA}. Defaults to \code{TRUE}.} \item{absolute}{Logical; if some cases or strata are negative, whether to arrange them (respecting \code{decreasing} and \code{reverse}) using negative or absolute values of \code{y}.} \item{discern}{Passed to \code{\link[=to_lodes_form]{to_lodes_form()}} if \code{data} is in alluvia format.} \item{negate.strata}{A vector of values of the \code{stratum} aesthetic to be treated as negative (will ignore missing values with a warning).} \item{aes.bind}{At what grouping level, if any, to prioritize differentiation aesthetics when ordering the lodes within each stratum. Defaults to \code{"none"} (no aesthetic binding) with intermediate option \code{"flows"} to bind aesthetics after stratifying by axes linked to the index axis (the one adjacent axis in \code{stat_flow()}; all remaining axes in \code{stat_alluvium()}) and strongest option \code{"alluvia"} to bind aesthetics after stratifying by the index axis but before stratifying by linked axes (only available for \code{stat_alluvium()}). Stratification by any axis is done with respect to the strata at that axis, after separating positive and negative strata, consistent with the values of \code{decreasing}, \code{reverse}, and \code{absolute}. Thus, if \code{"none"}, then lode orderings will not depend on aesthetic variables. All aesthetic variables are used, in the order in which they are specified in \code{aes()}.} \item{infer.label}{Logical; whether to assign the \code{stratum} or \code{alluvium} variable to the \code{label} aesthetic. Defaults to \code{FALSE}, and requires that no \code{label} aesthetic is assigned. This parameter is intended for use only with data in alluva form, which are converted to lode form before the statistical transformation. Deprecated; use \code{\link[ggplot2:aes_eval]{ggplot2::after_stat()}} instead.} \item{min.y, max.y}{Numeric; bounds on the heights of the strata to be rendered. Use these bounds to exclude strata outside a certain range, for example when labeling strata using \code{\link[ggplot2:geom_text]{ggplot2::geom_text()}}.} \item{na.rm}{Logical: if \code{FALSE}, the default, \code{NA} lodes are not included; if \code{TRUE}, \code{NA} lodes constitute a separate category, plotted in grey (regardless of the color scheme).} \item{show.legend}{logical. Should this layer be included in the legends? \code{NA}, the default, includes if any aesthetics are mapped. \code{FALSE} never includes, and \code{TRUE} always includes. It can also be a named logical vector to finely select the aesthetics to display.} \item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[ggplot2:borders]{borders()}}.} \item{...}{Additional arguments passed to \code{\link[ggplot2:layer]{ggplot2::layer()}}.} } \description{ Given a dataset with alluvial structure, \code{stat_flow} calculates the centroids (\code{x} and \code{y}) and heights (\code{ymin} and \code{ymax}) of the flows between each pair of adjacent axes. } \section{Aesthetics}{ \code{stat_alluvium}, \code{stat_flow}, and \code{stat_stratum} require one of two sets of aesthetics: \itemize{ \item \strong{\code{x}} and at least one of \strong{\code{alluvium}} and \strong{\code{stratum}} \item any number of \strong{\verb{axis[0-9]*}} (\code{axis1}, \code{axis2}, etc.) } Use \code{x}, \code{alluvium}, and/or \code{stratum} for data in lodes format and \verb{axis[0-9]*} for data in alluvia format (see \code{\link{alluvial-data}}). Arguments to parameters inconsistent with the format will be ignored. Additionally, each \verb{stat_*()} accepts the following optional aesthetics: \itemize{ \item \code{y} \item \code{weight} \item \code{order} \item \code{group} \item \code{label} } \code{y} controls the heights of the alluvia, and may be aggregated across equivalent observations. \code{weight} applies to the computed variables (see that section below) but does not affect the positional aesthetics. \code{order}, recognized by \code{stat_alluvium()} and \code{stat_flow()}, is used to arrange the lodes within each stratum. It tolerates duplicates and takes precedence over the differentiation aesthetics (when \code{aes.bind} is not \code{"none"}) and lode guidance with respect to the remaining axes. (It replaces the deprecated parameter \code{lode.ordering}.) \code{group} is used internally; arguments are ignored. \code{label} is used to label the strata or lodes and must take a unique value across the observations within each stratum or lode. These and any other aesthetics are aggregated as follows: Numeric aesthetics, including \code{y}, are summed. Character and factor aesthetics, including \code{label}, are assigned to strata or lodes provided they take unique values across the observations within each (and are otherwise assigned \code{NA}). } \section{Computed variables}{ These can be used with \code{\link[ggplot2:aes_eval]{ggplot2::after_stat()}} to \href{https://ggplot2.tidyverse.org/reference/aes_eval.html}{control aesthetic evaluation}. \describe{ \item{\code{n}}{number of cases in lode} \item{\code{count}}{cumulative weight of lode} \item{\code{prop}}{weighted proportion of lode} \item{\code{stratum}}{value of variable used to define strata} \item{\code{deposit}}{order in which (signed) strata are deposited} \item{\code{lode}}{lode label distilled from alluvia (\code{stat_alluvium()} and \code{stat_flow()} only)} \item{\code{flow}}{direction of flow \code{"to"} or \code{"from"} from its axis (\code{stat_flow()} only)} } The numerical variables \code{n}, \code{count}, and \code{prop} are calculated after the data are grouped by \code{x} and weighted by \code{weight} (in addition to \code{y}). The integer variable \code{deposit} is used internally to sort the data before calculating heights. The character variable \code{lode} is obtained from \code{alluvium} according to \code{distill}. } \section{Package options}{ \code{stat_stratum}, \code{stat_alluvium}, and \code{stat_flow} order strata and lodes according to the values of several parameters, which must be held fixed across every layer in an alluvial plot. These package-specific options set global values for these parameters that will be defaulted to when not manually set: \itemize{ \item \code{ggalluvial.decreasing} (each \verb{stat_*}): defaults to \code{NA}. \item \code{ggalluvial.reverse} (each \verb{stat_*}): defaults to \code{TRUE}. \item \code{ggalluvial.absolute} (each \verb{stat_*}): defaults to \code{TRUE}. \item \code{ggalluvial.cement.alluvia} (\code{stat_alluvium}): defaults to \code{FALSE}. \item \code{ggalluvial.lode.guidance} (\code{stat_alluvium}): defaults to \code{"zigzag"}. \item \code{ggalluvial.aes.bind} (\code{stat_alluvium} and \code{stat_flow}): defaults to \code{"none"}. } See \code{\link[base:options]{base::options()}} for how to use options. } \section{Defunct parameters}{ The previously defunct parameters \code{weight} and \code{aggregate.wts} have been discontinued. Use \code{y} and \code{cement.alluvia} instead. } \examples{ # illustrate positioning ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, color = Survived)) + stat_stratum(geom = "errorbar") + geom_line(stat = "flow") + stat_flow(geom = "pointrange") + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + scale_x_discrete(limits = c("Class", "Sex", "Age")) # alluvium--flow comparison data(vaccinations) gg <- ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response)) + geom_stratum(alpha = .5) + geom_text(aes(label = response), stat = "stratum") # rightward alluvial aesthetics for vaccine survey data gg + geom_flow(stat = "alluvium", lode.guidance = "forward") # memoryless flows for vaccine survey data gg + geom_flow() # size filter examples gg <- ggplot(vaccinations, aes(y = freq, x = survey, stratum = response, alluvium = subject, fill = response, label = response)) + stat_stratum(alpha = .5) + geom_text(stat = "stratum") # omit small flows gg + geom_flow(min.y = 50) # omit large flows gg + geom_flow(max.y = 100) # negate missing entries ggplot(vaccinations, aes(y = freq, x = survey, stratum = response, alluvium = subject, fill = response, label = response, alpha = response != "Missing")) + stat_stratum(negate.strata = "Missing") + geom_flow(negate.strata = "Missing") + geom_text(stat = "stratum", alpha = 1, negate.strata = "Missing") + scale_alpha_discrete(range = c(.2, .6)) + guides(alpha = "none") \donttest{ # aesthetics that vary betwween and within strata data(vaccinations) vaccinations$subgroup <- LETTERS[1:2][rbinom( n = length(unique(vaccinations$subject)), size = 1, prob = .5 ) + 1][vaccinations$subject] ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, fill = response, label = response)) + geom_flow(aes(alpha = subgroup)) + scale_alpha_discrete(range = c(1/3, 2/3)) + geom_stratum(alpha = .5) + geom_text(stat = "stratum") # can even set aesthetics that vary both ways ggplot(vaccinations, aes(x = survey, stratum = response, alluvium = subject, y = freq, label = response)) + geom_flow(aes(fill = interaction(response, subgroup)), aes.bind = "flows") + scale_alpha_discrete(range = c(1/3, 2/3)) + geom_stratum(alpha = .5) + geom_text(stat = "stratum") } } \seealso{ \code{\link[ggplot2:layer]{ggplot2::layer()}} for additional arguments and \code{\link[=geom_alluvium]{geom_alluvium()}} and \code{\link[=geom_flow]{geom_flow()}} for the corresponding geoms. Other alluvial stat layers: \code{\link{stat_alluvium}()}, \code{\link{stat_stratum}()} } \concept{alluvial stat layers} ggalluvial/man/lode-guidance-functions.Rd0000644000176200001440000000410214166562215020156 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/lode-guidance-functions.r \name{lode-guidance-functions} \alias{lode-guidance-functions} \alias{lode_zigzag} \alias{lode_zagzig} \alias{lode_forward} \alias{lode_rightward} \alias{lode_backward} \alias{lode_leftward} \alias{lode_frontback} \alias{lode_rightleft} \alias{lode_backfront} \alias{lode_leftright} \title{Lode guidance functions} \usage{ lode_zigzag(n, i) lode_zagzig(n, i) lode_forward(n, i) lode_rightward(n, i) lode_backward(n, i) lode_leftward(n, i) lode_frontback(n, i) lode_rightleft(n, i) lode_backfront(n, i) lode_leftright(n, i) } \arguments{ \item{n}{Numeric, a positive integer} \item{i}{Numeric, a positive integer at most \code{n}} } \description{ These functions control the order of lodes within strata in an alluvial diagram. They are invoked by \code{\link[=stat_alluvium]{stat_alluvium()}} and can be passed to the \code{lode.guidance} parameter. } \details{ Each function orders the numbers 1 through \code{n}, starting at index \code{i}. The choice of function made in \code{\link[=stat_alluvium]{stat_alluvium()}} determines the order in which the other axes contribute to the sorting of lodes within each index axis. After starting at \code{i}, the functions order the remaining axes as follows: \itemize{ \item \code{zigzag}: Zigzag outward from \code{i}, starting in the outward direction \item \code{zigzag}: Zigzag outward from \code{i}, starting in the inward direction \item \code{forward}: Increasing order (alias \code{rightward}) \item \code{backward}: Decreasing order (alias \code{leftward}) \item \code{frontback}: Proceed forward from \code{i} to \code{n}, then backward to 1 (alias \code{rightleft}) \item \code{backfront}: Proceed backward from \code{i} to 1, then forward to \code{n} (alias \code{leftright}) } An extended discussion of how strata and lodes are arranged in alluvial plots, including the effects of different lode guidance functions, can be found in the vignette "The Order of the Rectangles" via \code{vignette("order-rectangles", package = "ggalluvial")}. } ggalluvial/man/stat_alluvium.Rd0000644000176200001440000003721015146420370016341 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/stat-alluvium.r \name{stat_alluvium} \alias{stat_alluvium} \title{Alluvial positions} \usage{ stat_alluvium( mapping = NULL, data = NULL, geom = "alluvium", position = "identity", decreasing = NULL, reverse = NULL, absolute = NULL, discern = FALSE, negate.strata = NULL, aggregate.y = NULL, cement.alluvia = NULL, lode.guidance = NULL, lode.ordering = NULL, aes.bind = NULL, infer.label = FALSE, min.y = NULL, max.y = NULL, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ... ) } \arguments{ \item{mapping}{Set of aesthetic mappings created by \code{\link[ggplot2:aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level of the plot. You must supply \code{mapping} if there is no plot mapping.} \item{data}{The data to be displayed in this layer. There are three options: If \code{NULL}, the default, the data is inherited from the plot data as specified in the call to \code{\link[ggplot2:ggplot]{ggplot()}}. A \code{data.frame}, or other object, will override the plot data. All objects will be fortified to produce a data frame. See \code{\link[ggplot2:fortify]{fortify()}} for which variables will be created. A \code{function} will be called with a single argument, the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} \item{geom}{The geometric object to use display the data; override the default.} \item{position}{Position adjustment, either as a string naming the adjustment (e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a position adjustment function. Use the latter if you need to change the settings of the adjustment.} \item{decreasing}{Logical; whether to arrange the strata at each axis in the order of the variable values (\code{NA}, the default), in ascending order of totals (largest on top, \code{FALSE}), or in descending order of totals (largest on bottom, \code{TRUE}).} \item{reverse}{Logical; if \code{decreasing} is \code{NA}, whether to arrange the strata at each axis in the reverse order of the variable values, so that they match the order of the values in the legend. Ignored if \code{decreasing} is not \code{NA}. Defaults to \code{TRUE}.} \item{absolute}{Logical; if some cases or strata are negative, whether to arrange them (respecting \code{decreasing} and \code{reverse}) using negative or absolute values of \code{y}.} \item{discern}{Passed to \code{\link[=to_lodes_form]{to_lodes_form()}} if \code{data} is in alluvia format.} \item{negate.strata}{A vector of values of the \code{stratum} aesthetic to be treated as negative (will ignore missing values with a warning).} \item{aggregate.y}{Deprecated alias for \code{cement.alluvia}.} \item{cement.alluvia}{Logical value indicating whether to aggregate \code{y} values over equivalent alluvia before computing lode and flow positions.} \item{lode.guidance}{The function to prioritize the axis variables for ordering the lodes within each stratum, or else a character string identifying the function. Character options are "zigzag", "frontback", "backfront", "forward", and "backward" (see \code{\link{lode-guidance-functions}}).} \item{lode.ordering}{\strong{Deprecated in favor of the \code{order} aesthetic.} A list (of length the number of axes) of integer vectors (each of length the number of rows of \code{data}) or NULL entries (indicating no imposed ordering), or else a numeric matrix of corresponding dimensions, giving the preferred ordering of alluvia at each axis. This will be used to order the lodes within each stratum by sorting the lodes first by stratum, then by the provided vectors, and lastly by remaining factors (if the vectors contain duplicate entries and therefore do not completely determine the lode orderings).} \item{aes.bind}{At what grouping level, if any, to prioritize differentiation aesthetics when ordering the lodes within each stratum. Defaults to \code{"none"} (no aesthetic binding) with intermediate option \code{"flows"} to bind aesthetics after stratifying by axes linked to the index axis (the one adjacent axis in \code{stat_flow()}; all remaining axes in \code{stat_alluvium()}) and strongest option \code{"alluvia"} to bind aesthetics after stratifying by the index axis but before stratifying by linked axes (only available for \code{stat_alluvium()}). Stratification by any axis is done with respect to the strata at that axis, after separating positive and negative strata, consistent with the values of \code{decreasing}, \code{reverse}, and \code{absolute}. Thus, if \code{"none"}, then lode orderings will not depend on aesthetic variables. All aesthetic variables are used, in the order in which they are specified in \code{aes()}.} \item{infer.label}{Logical; whether to assign the \code{stratum} or \code{alluvium} variable to the \code{label} aesthetic. Defaults to \code{FALSE}, and requires that no \code{label} aesthetic is assigned. This parameter is intended for use only with data in alluva form, which are converted to lode form before the statistical transformation. Deprecated; use \code{\link[ggplot2:aes_eval]{ggplot2::after_stat()}} instead.} \item{min.y, max.y}{Numeric; bounds on the heights of the strata to be rendered. Use these bounds to exclude strata outside a certain range, for example when labeling strata using \code{\link[ggplot2:geom_text]{ggplot2::geom_text()}}.} \item{na.rm}{Logical: if \code{FALSE}, the default, \code{NA} lodes are not included; if \code{TRUE}, \code{NA} lodes constitute a separate category, plotted in grey (regardless of the color scheme).} \item{show.legend}{logical. Should this layer be included in the legends? \code{NA}, the default, includes if any aesthetics are mapped. \code{FALSE} never includes, and \code{TRUE} always includes. It can also be a named logical vector to finely select the aesthetics to display.} \item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[ggplot2:borders]{borders()}}.} \item{...}{Additional arguments passed to \code{\link[ggplot2:layer]{ggplot2::layer()}}.} } \description{ Given a dataset with alluvial structure, \code{stat_alluvium} calculates the centroids (\code{x} and \code{y}) and heights (\code{ymin} and \code{ymax}) of the lodes, the intersections of the alluvia with the strata. It leverages the \code{group} aesthetic for plotting purposes (for now). } \section{Aesthetics}{ \code{stat_alluvium}, \code{stat_flow}, and \code{stat_stratum} require one of two sets of aesthetics: \itemize{ \item \strong{\code{x}} and at least one of \strong{\code{alluvium}} and \strong{\code{stratum}} \item any number of \strong{\verb{axis[0-9]*}} (\code{axis1}, \code{axis2}, etc.) } Use \code{x}, \code{alluvium}, and/or \code{stratum} for data in lodes format and \verb{axis[0-9]*} for data in alluvia format (see \code{\link{alluvial-data}}). Arguments to parameters inconsistent with the format will be ignored. Additionally, each \verb{stat_*()} accepts the following optional aesthetics: \itemize{ \item \code{y} \item \code{weight} \item \code{order} \item \code{group} \item \code{label} } \code{y} controls the heights of the alluvia, and may be aggregated across equivalent observations. \code{weight} applies to the computed variables (see that section below) but does not affect the positional aesthetics. \code{order}, recognized by \code{stat_alluvium()} and \code{stat_flow()}, is used to arrange the lodes within each stratum. It tolerates duplicates and takes precedence over the differentiation aesthetics (when \code{aes.bind} is not \code{"none"}) and lode guidance with respect to the remaining axes. (It replaces the deprecated parameter \code{lode.ordering}.) \code{group} is used internally; arguments are ignored. \code{label} is used to label the strata or lodes and must take a unique value across the observations within each stratum or lode. These and any other aesthetics are aggregated as follows: Numeric aesthetics, including \code{y}, are summed. Character and factor aesthetics, including \code{label}, are assigned to strata or lodes provided they take unique values across the observations within each (and are otherwise assigned \code{NA}). } \section{Computed variables}{ These can be used with \code{\link[ggplot2:aes_eval]{ggplot2::after_stat()}} to \href{https://ggplot2.tidyverse.org/reference/aes_eval.html}{control aesthetic evaluation}. \describe{ \item{\code{n}}{number of cases in lode} \item{\code{count}}{cumulative weight of lode} \item{\code{prop}}{weighted proportion of lode} \item{\code{stratum}}{value of variable used to define strata} \item{\code{deposit}}{order in which (signed) strata are deposited} \item{\code{lode}}{lode label distilled from alluvia (\code{stat_alluvium()} and \code{stat_flow()} only)} \item{\code{flow}}{direction of flow \code{"to"} or \code{"from"} from its axis (\code{stat_flow()} only)} } The numerical variables \code{n}, \code{count}, and \code{prop} are calculated after the data are grouped by \code{x} and weighted by \code{weight} (in addition to \code{y}). The integer variable \code{deposit} is used internally to sort the data before calculating heights. The character variable \code{lode} is obtained from \code{alluvium} according to \code{distill}. } \section{Package options}{ \code{stat_stratum}, \code{stat_alluvium}, and \code{stat_flow} order strata and lodes according to the values of several parameters, which must be held fixed across every layer in an alluvial plot. These package-specific options set global values for these parameters that will be defaulted to when not manually set: \itemize{ \item \code{ggalluvial.decreasing} (each \verb{stat_*}): defaults to \code{NA}. \item \code{ggalluvial.reverse} (each \verb{stat_*}): defaults to \code{TRUE}. \item \code{ggalluvial.absolute} (each \verb{stat_*}): defaults to \code{TRUE}. \item \code{ggalluvial.cement.alluvia} (\code{stat_alluvium}): defaults to \code{FALSE}. \item \code{ggalluvial.lode.guidance} (\code{stat_alluvium}): defaults to \code{"zigzag"}. \item \code{ggalluvial.aes.bind} (\code{stat_alluvium} and \code{stat_flow}): defaults to \code{"none"}. } See \code{\link[base:options]{base::options()}} for how to use options. } \section{Defunct parameters}{ The previously defunct parameters \code{weight} and \code{aggregate.wts} have been discontinued. Use \code{y} and \code{cement.alluvia} instead. } \examples{ # illustrate positioning ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, color = Survived)) + stat_stratum(geom = "errorbar") + geom_line(stat = "alluvium") + stat_alluvium(geom = "pointrange") + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + scale_x_discrete(limits = c("Class", "Sex", "Age")) # lode ordering examples gg <- ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age)) + geom_stratum() + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + scale_x_discrete(limits = c("Class", "Sex", "Age")) # use of lode controls gg + geom_flow(aes(fill = Survived, alpha = Sex), stat = "alluvium", lode.guidance = "forward") # prioritize aesthetic binding gg + geom_flow(aes(fill = Survived, alpha = Sex), stat = "alluvium", aes.bind = "alluvia", lode.guidance = "forward") # use of custom lode order gg + geom_flow(aes(fill = Survived, alpha = Sex, order = sample(x = 32)), stat = "alluvium") # use of custom luide guidance function lode_custom <- function(n, i) { stopifnot(n == 3) switch( i, `1` = 1:3, `2` = c(2, 3, 1), `3` = 3:1 ) } gg + geom_flow(aes(fill = Survived, alpha = Sex), stat = "alluvium", aes.bind = "flow", lode.guidance = lode_custom) # omit missing elements & reverse the `y` axis ggplot(ggalluvial::majors, aes(x = semester, stratum = curriculum, alluvium = student, y = 1)) + geom_alluvium(fill = "darkgrey", na.rm = TRUE) + geom_stratum(aes(fill = curriculum), color = NA, na.rm = TRUE) + theme_bw() + scale_y_reverse() \donttest{ # alluvium cementation examples gg <- ggplot(ggalluvial::majors, aes(x = semester, stratum = curriculum, alluvium = student, fill = curriculum)) + geom_stratum() # diagram with outlined alluvia and labels gg + geom_flow(stat = "alluvium", color = "black") + geom_text(aes(label = after_stat(lode)), stat = "alluvium") # cemented diagram with default distillation (first most common alluvium) gg + geom_flow(stat = "alluvium", color = "black", cement.alluvia = TRUE) + geom_text(aes(label = after_stat(lode)), stat = "alluvium", cement.alluvia = TRUE) # cemented diagram with custom label distillation gg + geom_flow(stat = "alluvium", color = "black", cement.alluvia = TRUE) + geom_text(aes(label = after_stat(lode)), stat = "alluvium", cement.alluvia = TRUE, distill = function(x) paste(x, collapse = "; ")) } \donttest{ data(babynames, package = "babynames") # a discontiguous alluvium bn <- subset(babynames, prop >= .01 & sex == "F" & year > 1962 & year < 1968) ggplot(data = bn, aes(x = year, alluvium = name, y = prop)) + geom_alluvium(aes(fill = name, color = name == "Tammy"), decreasing = TRUE, show.legend = FALSE) + scale_color_manual(values = c("#00000000", "#000000")) # expanded to include missing values bn2 <- merge(bn, expand.grid(year = unique(bn$year), name = unique(bn$name)), all = TRUE) ggplot(data = bn2, aes(x = year, alluvium = name, y = prop)) + geom_alluvium(aes(fill = name, color = name == "Tammy"), decreasing = TRUE, show.legend = FALSE) + scale_color_manual(values = c("#00000000", "#000000")) # with missing values filled in with zeros bn2$prop[is.na(bn2$prop)] <- 0 ggplot(data = bn2, aes(x = year, alluvium = name, y = prop)) + geom_alluvium(aes(fill = name, color = name == "Tammy"), decreasing = TRUE, show.legend = FALSE) + scale_color_manual(values = c("#00000000", "#000000")) } # use negative y values to encode deaths versus survivals titanic <- as.data.frame(Titanic) titanic <- transform(titanic, Lives = Freq * (-1) ^ (Survived == "No")) ggplot(subset(titanic, Class != "Crew"), aes(axis1 = Class, axis2 = Sex, axis3 = Age, y = Lives)) + geom_alluvium(aes(alpha = Survived, fill = Class), absolute = FALSE) + geom_stratum(absolute = FALSE) + geom_text(stat = "stratum", aes(label = after_stat(stratum)), absolute = FALSE) + scale_x_discrete(limits = c("Class", "Sex", "Age"), expand = c(.1, .05)) + scale_alpha_discrete(range = c(.25, .75), guide = "none") # faceting with common alluvia ggplot(titanic, aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age)) + facet_wrap(~ Survived) + geom_alluvium() + geom_stratum() + geom_text(stat = "stratum", aes(label = after_stat(stratum))) ggplot(transform(alluvial::Refugees, id = 1), aes(y = refugees, x = year, alluvium = id)) + facet_wrap(~ country) + geom_alluvium(alpha = .75, color = "darkgrey") + scale_x_continuous(breaks = seq(2004, 2012, 4)) } \seealso{ \code{\link[ggplot2:layer]{ggplot2::layer()}} for additional arguments and \code{\link[=geom_alluvium]{geom_alluvium()}}, \code{\link[=geom_lode]{geom_lode()}}, and \code{\link[=geom_flow]{geom_flow()}} for the corresponding geoms. Other alluvial stat layers: \code{\link{stat_flow}()}, \code{\link{stat_stratum}()} } \concept{alluvial stat layers} ggalluvial/man/geom_stratum.Rd0000644000176200001440000001102115146420370016146 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/geom-stratum.r \name{geom_stratum} \alias{geom_stratum} \title{Strata at axes} \usage{ geom_stratum( mapping = NULL, data = NULL, stat = "stratum", position = "identity", show.legend = NA, inherit.aes = TRUE, width = 1/3, na.rm = FALSE, ... ) } \arguments{ \item{mapping}{Set of aesthetic mappings created by \code{\link[ggplot2:aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level of the plot. You must supply \code{mapping} if there is no plot mapping.} \item{data}{The data to be displayed in this layer. There are three options: If \code{NULL}, the default, the data is inherited from the plot data as specified in the call to \code{\link[ggplot2:ggplot]{ggplot()}}. A \code{data.frame}, or other object, will override the plot data. All objects will be fortified to produce a data frame. See \code{\link[ggplot2:fortify]{fortify()}} for which variables will be created. A \code{function} will be called with a single argument, the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} \item{stat}{The statistical transformation to use on the data; override the default.} \item{position}{Position adjustment, either as a string naming the adjustment (e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a position adjustment function. Use the latter if you need to change the settings of the adjustment.} \item{show.legend}{logical. Should this layer be included in the legends? \code{NA}, the default, includes if any aesthetics are mapped. \code{FALSE} never includes, and \code{TRUE} always includes. It can also be a named logical vector to finely select the aesthetics to display.} \item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[ggplot2:borders]{borders()}}.} \item{width}{Numeric; the width of each stratum, as a proportion of the distance between axes. Defaults to 1/3.} \item{na.rm}{Logical: if \code{FALSE}, the default, \code{NA} lodes are not included; if \code{TRUE}, \code{NA} lodes constitute a separate category, plotted in grey (regardless of the color scheme).} \item{...}{Additional arguments passed to \code{\link[ggplot2:layer]{ggplot2::layer()}}.} } \description{ \code{geom_stratum} receives a dataset of the horizontal (\code{x}) and vertical (\code{y}, \code{ymin}, \code{ymax}) positions of the strata of an alluvial plot. It plots rectangles for these strata of a provided \code{width}. } \section{Aesthetics}{ \code{geom_alluvium}, \code{geom_flow}, \code{geom_lode}, and \code{geom_stratum} understand the following aesthetics (required aesthetics are in bold): \itemize{ \item \strong{\code{x}} \item \strong{\code{y}} \item \strong{\code{ymin}} \item \strong{\code{ymax}} \item \code{alpha} \item \code{colour} \item \code{fill} \item \code{linetype} \item \code{size} \item \code{group} } \code{group} is used internally; arguments are ignored. Alluvium, flow, and lode geoms default to \code{alpha = 0.5}. Learn more about setting these aesthetics in \code{vignette("ggplot2-specs", package = "ggplot2")}. } \section{Defunct parameters}{ The previously defunct parameters \code{axis_width} and \code{ribbon_bend} have been discontinued. Use \code{width} and \code{knot.pos} instead. } \examples{ # full axis width ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, axis4 = Survived)) + geom_stratum(width = 1) + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + scale_x_discrete(limits = c("Class", "Sex", "Age", "Survived")) # use of facets ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex)) + geom_flow(aes(fill = Survived)) + geom_stratum() + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + scale_x_discrete(limits = c("Class", "Sex")) + facet_wrap(~ Age, scales = "free_y") } \seealso{ \code{\link[ggplot2:layer]{ggplot2::layer()}} for additional arguments and \code{\link[=stat_stratum]{stat_stratum()}} for the corresponding stat. Other alluvial geom layers: \code{\link{geom_alluvium}()}, \code{\link{geom_flow}()}, \code{\link{geom_lode}()} } \concept{alluvial geom layers} ggalluvial/man/ggalluvial-package.Rd0000644000176200001440000000303514341153260017163 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/ggalluvial-package.r \docType{package} \name{ggalluvial-package} \alias{ggalluvial} \alias{ggalluvial-package} \title{ggalluvial: Alluvial Plots in 'ggplot2'} \description{ Alluvial plots use variable-width ribbons and stacked bar plots to represent multi-dimensional or repeated-measures data with categorical or ordinal variables; see Riehmann, Hanfler, and Froehlich (2005) \doi{10.1109/INFVIS.2005.1532152} and Rosvall and Bergstrom (2010) \doi{10.1371/journal.pone.0008694}. Alluvial plots are statistical graphics in the sense of Wilkinson (2006) \doi{10.1007/0-387-28695-0}; they share elements with Sankey diagrams and parallel sets plots but are uniquely determined from the data and a small set of parameters. This package extends Wickham's (2010) \doi{10.1198/jcgs.2009.07098} layered grammar of graphics to generate alluvial plots from tidy data. } \section{Acknowledgments}{ Many users identified problems and suggested improvements via email and the GitHub issue tracker. Development benefitted from the use of equipment and the support of colleagues at \href{https://health.uconn.edu/}{UConn Health} and at \href{https://ufhealth.org/}{UF Health}. } \seealso{ Useful links: \itemize{ \item \url{http://corybrunson.github.io/ggalluvial/} \item Report bugs at \url{https://github.com/corybrunson/ggalluvial/issues} } } \author{ \strong{Maintainer}: Jason Cory Brunson \email{cornelioid@gmail.com} Authors: \itemize{ \item Quentin D. Read } } \keyword{internal} ggalluvial/man/ggalluvial-ggproto.Rd0000644000176200001440000000255515000311045017245 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/geom-alluvium.r, R/geom-flow.r, R/geom-lode.r, % R/geom-stratum.r, R/ggproto.r, R/stat-alluvium.r, R/stat-flow.r, % R/stat-stratum.r \docType{data} \name{GeomAlluvium} \alias{GeomAlluvium} \alias{GeomFlow} \alias{GeomLode} \alias{GeomStratum} \alias{ggalluvial-ggproto} \alias{StatAlluvium} \alias{StatFlow} \alias{StatStratum} \title{Base ggproto classes for ggalluvial} \format{ An object of class \code{GeomAlluvium} (inherits from \code{Geom}, \code{ggproto}, \code{gg}) of length 8. An object of class \code{GeomFlow} (inherits from \code{Geom}, \code{ggproto}, \code{gg}) of length 8. An object of class \code{GeomLode} (inherits from \code{Geom}, \code{ggproto}, \code{gg}) of length 6. An object of class \code{GeomStratum} (inherits from \code{GeomRect}, \code{Geom}, \code{ggproto}, \code{gg}) of length 6. An object of class \code{StatAlluvium} (inherits from \code{Stat}, \code{ggproto}, \code{gg}) of length 6. An object of class \code{StatFlow} (inherits from \code{Stat}, \code{ggproto}, \code{gg}) of length 7. An object of class \code{StatStratum} (inherits from \code{Stat}, \code{ggproto}, \code{gg}) of length 5. } \description{ Base ggproto classes for ggalluvial } \seealso{ \code{\link[ggplot2:ggplot2-ggproto]{ggplot2::ggplot2-ggproto}} } \keyword{datasets} \keyword{internal} ggalluvial/man/geom_alluvium.Rd0000644000176200001440000002562515146420370016324 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/geom-alluvium.r \name{geom_alluvium} \alias{geom_alluvium} \alias{data_to_alluvium} \title{Alluvia across strata} \usage{ 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, outline.type = "both", na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ... ) data_to_alluvium( data, knot.prop = TRUE, curve_type = "spline", curve_range = NULL, segments = NULL ) } \arguments{ \item{mapping}{Set of aesthetic mappings created by \code{\link[ggplot2:aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level of the plot. You must supply \code{mapping} if there is no plot mapping.} \item{data}{The data to be displayed in this layer. There are three options: If \code{NULL}, the default, the data is inherited from the plot data as specified in the call to \code{\link[ggplot2:ggplot]{ggplot()}}. A \code{data.frame}, or other object, will override the plot data. All objects will be fortified to produce a data frame. See \code{\link[ggplot2:fortify]{fortify()}} for which variables will be created. A \code{function} will be called with a single argument, the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} \item{stat}{The statistical transformation to use on the data; override the default.} \item{position}{Position adjustment, either as a string naming the adjustment (e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a position adjustment function. Use the latter if you need to change the settings of the adjustment.} \item{width}{Numeric; the width of each stratum, as a proportion of the distance between axes. Defaults to 1/3.} \item{knot.pos}{The horizontal distance of x-spline knots from each stratum (\code{width/2} from its axis), either (if \code{knot.prop = TRUE}, the default) as a proportion of the length of the x-spline, i.e. of the gap between adjacent strata, or (if \code{knot.prop = FALSE}) on the scale of the \code{x} direction.} \item{knot.prop}{Logical; whether to interpret \code{knot.pos} as a proportion of the length of each flow (the default), rather than on the \code{x} scale.} \item{curve_type}{Character; the type of curve used to produce flows. Defaults to \code{"xspline"} and can be alternatively set to one of \code{"linear"}, \code{"cubic"}, \code{"quintic"}, \code{"sine"}, \code{"arctangent"}, and \code{"sigmoid"}. \code{"xspline"} produces approximation splines using 4 points per curve; the alternatives produce interpolation splines between points along the graphs of functions of the associated type. See the \strong{Curves} section.} \item{curve_range}{For alternative \code{curve_type}s based on asymptotic functions, the value along the asymptote at which to truncate the function to obtain the shape that will be scaled to fit between strata. See the \strong{Curves} section.} \item{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.} \item{outline.type}{Type of outline of each alluvium; one of \code{"both"}, \code{"lower"}, \code{"upper"}, and \code{"full"}.} \item{na.rm}{Logical: if \code{FALSE}, the default, \code{NA} lodes are not included; if \code{TRUE}, \code{NA} lodes constitute a separate category, plotted in grey (regardless of the color scheme).} \item{show.legend}{logical. Should this layer be included in the legends? \code{NA}, the default, includes if any aesthetics are mapped. \code{FALSE} never includes, and \code{TRUE} always includes. It can also be a named logical vector to finely select the aesthetics to display.} \item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[ggplot2:borders]{borders()}}.} \item{...}{Additional arguments passed to \code{\link[ggplot2:layer]{ggplot2::layer()}}.} } \description{ \code{geom_alluvium} receives a dataset of the horizontal (\code{x}) and vertical (\code{y}, \code{ymin}, \code{ymax}) positions of the \strong{lodes} of an alluvial plot, the intersections of the alluvia with the strata. It plots both the lodes themselves, using \code{\link[=geom_lode]{geom_lode()}}, and the flows between them, using \code{\link[=geom_flow]{geom_flow()}}. } \details{ The helper function \code{data_to_alluvium()} takes internal \strong{ggplot2} data (mapped aesthetics) and curve parameters for a single alluvium as input and returns a data frame of \code{x}, \code{y}, and \code{shape} used by \code{\link[grid:grid.xspline]{grid::xsplineGrob()}} to render the alluvium. } \section{Aesthetics}{ \code{geom_alluvium}, \code{geom_flow}, \code{geom_lode}, and \code{geom_stratum} understand the following aesthetics (required aesthetics are in bold): \itemize{ \item \strong{\code{x}} \item \strong{\code{y}} \item \strong{\code{ymin}} \item \strong{\code{ymax}} \item \code{alpha} \item \code{colour} \item \code{fill} \item \code{linetype} \item \code{size} \item \code{group} } \code{group} is used internally; arguments are ignored. Alluvium, flow, and lode geoms default to \code{alpha = 0.5}. Learn more about setting these aesthetics in \code{vignette("ggplot2-specs", package = "ggplot2")}. } \section{Curves}{ By default, \code{geom_alluvium()} and \code{geom_flow()} render flows between lodes as filled regions between parallel x-splines. These graphical elements, generated using \code{\link[grid:grid.xspline]{grid::xsplineGrob()}}, are parameterized by the relative location of the knot (\code{knot.pos}). They are quick to render and clear to read, but users may prefer plots that use differently-shaped ribbons. A variety of such options are documented at, e.g., \href{https://easings.net/}{this easing functions cheat sheet} and \href{https://www.dataplusscience.com/Sigmoid.html}{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 \eqn{[0,1]} to itself, and each is rescaled so that its endpoints meet the corresponding lodes. They are rendered piecewise-linearly, by default using \code{segments = 48}. Summon each curve type by passing one of the following strings to \code{curve_type}: \itemize{ \item \code{"linear"}: \eqn{f(x)=x}, the unique degree-1 polynomial that takes 0 to 0 and 1 to 1 \item \code{"cubic"}: \eqn{f(x)=3x^{2}-2x^{3}}{f(x)=3x^2-2x^3}, the unique degree-3 polynomial that also is flat at both endpoints \item \code{"quintic"}: \eqn{f(x)=10x^{3}-15x^{4}+6x^{5}}{f(x)=10x^3-15x^4+6x^5}, the unique degree-5 polynomial that also has zero curvature at both endpoints \item \code{"sine"}: the unique sinusoidal function that is flat at both endpoints \item \code{"arctangent"}: the inverse tangent function, scaled and re-centered to the unit interval from the interval centered at zero with radius \code{curve_range} \item \code{"sigmoid"}: the sigmoid function, scaled and re-centered to the unit interval from the interval centered at zero with radius \code{curve_range} } Only the (default) \code{"xspline"} option uses the \verb{knot.*} parameters, while only the alternative curves use the \code{segments} parameter, and only \code{"arctangent"} and \code{"sigmoid"} use the \code{curve_range} parameter. (Both are ignored if not needed.) Larger values of \code{curve_range} result in greater compression and steeper slopes. The \code{NULL} default will be changed to \code{2+sqrt(3)} for \code{"arctangent"} and to \code{6} for \code{"sigmoid"}. These package-specific options set global values for \code{curve_type}, \code{curve_range}, and \code{segments} that will be defaulted to when not manually set: \itemize{ \item \code{ggalluvial.curve_type}: defaults to \code{"xspline"}. \item \code{ggalluvial.curve_range}: defaults to \code{NA}, which triggers the curve-specific default values. \item \code{ggalluvial.segments}: defaults to \code{48L}. } See \code{\link[base:options]{base::options()}} for how to use options. } \section{Defunct parameters}{ The previously defunct parameters \code{axis_width} and \code{ribbon_bend} have been discontinued. Use \code{width} and \code{knot.pos} instead. } \examples{ # 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 (sigmoid 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) \donttest{ # 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) # coarsely-segmented 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) # custom-ranged 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) } } \seealso{ \code{\link[ggplot2:layer]{ggplot2::layer()}} for additional arguments and \code{\link[=stat_alluvium]{stat_alluvium()}} and \code{\link[=stat_flow]{stat_flow()}} for the corresponding stats. Other alluvial geom layers: \code{\link{geom_flow}()}, \code{\link{geom_lode}()}, \code{\link{geom_stratum}()} } \concept{alluvial geom layers} ggalluvial/man/ggalluvial-deprecated.Rd0000644000176200001440000000124614112432105017664 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/devel.r \name{ggalluvial-deprecated} \alias{ggalluvial-deprecated} \alias{is_alluvial} \alias{is_alluvial_lodes} \alias{is_alluvial_alluvia} \alias{to_lodes} \alias{to_alluvia} \title{Deprecated functions} \usage{ is_alluvial(data, ..., silent = FALSE) is_alluvial_lodes(...) is_alluvial_alluvia(...) to_lodes(...) to_alluvia(...) } \description{ These functions are deprecated in the current version and may be removed in a future version. } \details{ Use \verb{is_*_form} instead of \code{is_alluvial} and \verb{is_alluvial_*}. Use \verb{to_*_form} instead of \verb{to_*}. } \keyword{internal} ggalluvial/man/self-adjoin.Rd0000644000176200001440000000521014166562215015644 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/self-adjoin.r \name{self-adjoin} \alias{self-adjoin} \alias{self_adjoin} \title{Adjoin a dataset to itself} \usage{ self_adjoin( data, key, by = NULL, link = NULL, keep.x = NULL, keep.y = NULL, suffix = c(".x", ".y") ) } \arguments{ \item{data}{A data frame in lodes form (repeated measures data; see \code{\link{alluvial-data}}).} \item{key}{Column of \code{data} indicating sequential collection; handled as in \code{\link[tidyr:spread]{tidyr::spread()}}.} \item{by}{Character vector of variables to self-adjoin by; passed to \code{\link[dplyr:mutate-joins]{dplyr::mutate-joins}} functions.} \item{link}{Character vector of variables to adjoin. Will be replaced by pairs of variables suffixed by \code{suffix}.} \item{keep.x, keep.y}{Character vector of variables to associate with the first (respectively, second) copy of \code{data} after adjoining. These variables can overlap with each other but cannot overlap with \code{by} or \code{link}.} \item{suffix}{Suffixes to add to the adjoined \code{link} variables; passed to \code{\link[dplyr:mutate-joins]{dplyr::mutate-joins}} functions.} } \description{ This function binds a dataset to itself along adjacent pairs of a \code{key} variable. It is invoked by \code{\link[=geom_flow]{geom_flow()}} to convert data in lodes form to something similar to alluvia form. } \details{ \code{self_adjoin} invokes \code{\link[dplyr:mutate-joins]{dplyr::mutate-joins}} functions in order to convert a dataset with measures along a discrete \code{key} variable into a dataset consisting of column bindings of these measures (by any \code{by} variables) along adjacent values of \code{key}. } \examples{ # self-adjoin `majors` data data(majors) major_changes <- self_adjoin(majors, key = semester, by = "student", link = c("semester", "curriculum")) major_changes$change <- major_changes$curriculum.x == major_changes$curriculum.y head(major_changes) # self-adjoin `vaccinations` data data(vaccinations) vaccination_steps <- self_adjoin(vaccinations, key = survey, by = "subject", link = c("survey", "response"), keep.x = c("freq")) head(vaccination_steps) vaccination_steps <- self_adjoin(vaccinations, key = survey, by = "subject", link = c("survey", "response"), keep.x = c("freq"), keep.y = c("start_date", "end_date")) head(vaccination_steps) } \seealso{ Other alluvial data manipulation: \code{\link{alluvial-data}} } \concept{alluvial data manipulation} ggalluvial/man/stat_stratum.Rd0000644000176200001440000003026615146420370016206 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/stat-stratum.r \name{stat_stratum} \alias{stat_stratum} \title{Stratum positions} \usage{ stat_stratum( mapping = NULL, data = NULL, geom = "stratum", position = "identity", decreasing = NULL, reverse = NULL, absolute = NULL, discern = FALSE, distill = "first", negate.strata = NULL, infer.label = FALSE, label.strata = NULL, min.y = NULL, max.y = NULL, min.height = NULL, max.height = NULL, na.rm = FALSE, show.legend = NA, inherit.aes = TRUE, ... ) } \arguments{ \item{mapping}{Set of aesthetic mappings created by \code{\link[ggplot2:aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level of the plot. You must supply \code{mapping} if there is no plot mapping.} \item{data}{The data to be displayed in this layer. There are three options: If \code{NULL}, the default, the data is inherited from the plot data as specified in the call to \code{\link[ggplot2:ggplot]{ggplot()}}. A \code{data.frame}, or other object, will override the plot data. All objects will be fortified to produce a data frame. See \code{\link[ggplot2:fortify]{fortify()}} for which variables will be created. A \code{function} will be called with a single argument, the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} \item{geom}{The geometric object to use display the data; override the default.} \item{position}{Position adjustment, either as a string naming the adjustment (e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a position adjustment function. Use the latter if you need to change the settings of the adjustment.} \item{decreasing}{Logical; whether to arrange the strata at each axis in the order of the variable values (\code{NA}, the default), in ascending order of totals (largest on top, \code{FALSE}), or in descending order of totals (largest on bottom, \code{TRUE}).} \item{reverse}{Logical; if \code{decreasing} is \code{NA}, whether to arrange the strata at each axis in the reverse order of the variable values, so that they match the order of the values in the legend. Ignored if \code{decreasing} is not \code{NA}. Defaults to \code{TRUE}.} \item{absolute}{Logical; if some cases or strata are negative, whether to arrange them (respecting \code{decreasing} and \code{reverse}) using negative or absolute values of \code{y}.} \item{discern}{Passed to \code{\link[=to_lodes_form]{to_lodes_form()}} if \code{data} is in alluvia format.} \item{distill}{A function (or its name) to be used to distill alluvium values to a single lode label, accessible via \code{\link[ggplot2:aes_eval]{ggplot2::after_stat()}} (similar to its behavior in \code{\link[=to_alluvia_form]{to_alluvia_form()}}). It recognizes three character values: \code{"first"} (the default) and \code{"last"} \link[dplyr:nth]{as defined} in \strong{dplyr}; and \code{"most"} (which returns the first modal value).} \item{negate.strata}{A vector of values of the \code{stratum} aesthetic to be treated as negative (will ignore missing values with a warning).} \item{infer.label}{Logical; whether to assign the \code{stratum} or \code{alluvium} variable to the \code{label} aesthetic. Defaults to \code{FALSE}, and requires that no \code{label} aesthetic is assigned. This parameter is intended for use only with data in alluva form, which are converted to lode form before the statistical transformation. Deprecated; use \code{\link[ggplot2:aes_eval]{ggplot2::after_stat()}} instead.} \item{label.strata}{Defunct; alias for \code{infer.label}.} \item{min.y, max.y}{Numeric; bounds on the heights of the strata to be rendered. Use these bounds to exclude strata outside a certain range, for example when labeling strata using \code{\link[ggplot2:geom_text]{ggplot2::geom_text()}}.} \item{min.height, max.height}{Deprecated aliases for \code{min.y} and \code{max.y}.} \item{na.rm}{Logical: if \code{FALSE}, the default, \code{NA} lodes are not included; if \code{TRUE}, \code{NA} lodes constitute a separate category, plotted in grey (regardless of the color scheme).} \item{show.legend}{logical. Should this layer be included in the legends? \code{NA}, the default, includes if any aesthetics are mapped. \code{FALSE} never includes, and \code{TRUE} always includes. It can also be a named logical vector to finely select the aesthetics to display.} \item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[ggplot2:borders]{borders()}}.} \item{...}{Additional arguments passed to \code{\link[ggplot2:layer]{ggplot2::layer()}}.} } \description{ Given a dataset with alluvial structure, \code{stat_stratum} calculates the centroids (\code{x} and \code{y}) and heights (\code{ymin} and \code{ymax}) of the strata at each axis. } \section{Aesthetics}{ \code{stat_alluvium}, \code{stat_flow}, and \code{stat_stratum} require one of two sets of aesthetics: \itemize{ \item \strong{\code{x}} and at least one of \strong{\code{alluvium}} and \strong{\code{stratum}} \item any number of \strong{\verb{axis[0-9]*}} (\code{axis1}, \code{axis2}, etc.) } Use \code{x}, \code{alluvium}, and/or \code{stratum} for data in lodes format and \verb{axis[0-9]*} for data in alluvia format (see \code{\link{alluvial-data}}). Arguments to parameters inconsistent with the format will be ignored. Additionally, each \verb{stat_*()} accepts the following optional aesthetics: \itemize{ \item \code{y} \item \code{weight} \item \code{order} \item \code{group} \item \code{label} } \code{y} controls the heights of the alluvia, and may be aggregated across equivalent observations. \code{weight} applies to the computed variables (see that section below) but does not affect the positional aesthetics. \code{order}, recognized by \code{stat_alluvium()} and \code{stat_flow()}, is used to arrange the lodes within each stratum. It tolerates duplicates and takes precedence over the differentiation aesthetics (when \code{aes.bind} is not \code{"none"}) and lode guidance with respect to the remaining axes. (It replaces the deprecated parameter \code{lode.ordering}.) \code{group} is used internally; arguments are ignored. \code{label} is used to label the strata or lodes and must take a unique value across the observations within each stratum or lode. These and any other aesthetics are aggregated as follows: Numeric aesthetics, including \code{y}, are summed. Character and factor aesthetics, including \code{label}, are assigned to strata or lodes provided they take unique values across the observations within each (and are otherwise assigned \code{NA}). } \section{Computed variables}{ These can be used with \code{\link[ggplot2:aes_eval]{ggplot2::after_stat()}} to \href{https://ggplot2.tidyverse.org/reference/aes_eval.html}{control aesthetic evaluation}. \describe{ \item{\code{n}}{number of cases in lode} \item{\code{count}}{cumulative weight of lode} \item{\code{prop}}{weighted proportion of lode} \item{\code{stratum}}{value of variable used to define strata} \item{\code{deposit}}{order in which (signed) strata are deposited} \item{\code{lode}}{lode label distilled from alluvia (\code{stat_alluvium()} and \code{stat_flow()} only)} \item{\code{flow}}{direction of flow \code{"to"} or \code{"from"} from its axis (\code{stat_flow()} only)} } The numerical variables \code{n}, \code{count}, and \code{prop} are calculated after the data are grouped by \code{x} and weighted by \code{weight} (in addition to \code{y}). The integer variable \code{deposit} is used internally to sort the data before calculating heights. The character variable \code{lode} is obtained from \code{alluvium} according to \code{distill}. } \section{Package options}{ \code{stat_stratum}, \code{stat_alluvium}, and \code{stat_flow} order strata and lodes according to the values of several parameters, which must be held fixed across every layer in an alluvial plot. These package-specific options set global values for these parameters that will be defaulted to when not manually set: \itemize{ \item \code{ggalluvial.decreasing} (each \verb{stat_*}): defaults to \code{NA}. \item \code{ggalluvial.reverse} (each \verb{stat_*}): defaults to \code{TRUE}. \item \code{ggalluvial.absolute} (each \verb{stat_*}): defaults to \code{TRUE}. \item \code{ggalluvial.cement.alluvia} (\code{stat_alluvium}): defaults to \code{FALSE}. \item \code{ggalluvial.lode.guidance} (\code{stat_alluvium}): defaults to \code{"zigzag"}. \item \code{ggalluvial.aes.bind} (\code{stat_alluvium} and \code{stat_flow}): defaults to \code{"none"}. } See \code{\link[base:options]{base::options()}} for how to use options. } \section{Defunct parameters}{ The previously defunct parameters \code{weight} and \code{aggregate.wts} have been discontinued. Use \code{y} and \code{cement.alluvia} instead. } \examples{ data(vaccinations) # only `stratum` assignment is necessary to generate strata ggplot(vaccinations, aes(y = freq, x = survey, stratum = response, fill = response)) + stat_stratum(width = .5) # lode data, positioning with y labels ggplot(vaccinations, aes(y = freq, x = survey, stratum = response, alluvium = subject, label = after_stat(count))) + stat_stratum(geom = "errorbar") + geom_text(stat = "stratum") # alluvium data, positioning with stratum labels ggplot(as.data.frame(Titanic), aes(y = Freq, axis1 = Class, axis2 = Sex, axis3 = Age, axis4 = Survived)) + geom_text(stat = "stratum", aes(label = after_stat(stratum))) + stat_stratum(geom = "errorbar") + scale_x_discrete(limits = c("Class", "Sex", "Age", "Survived")) # omit labels for strata outside a y range ggplot(vaccinations, aes(y = freq, x = survey, stratum = response, fill = response, label = response)) + stat_stratum(width = .5) + geom_text(stat = "stratum", min.y = 100) # date-valued axis variables ggplot(vaccinations, aes(x = end_date, y = freq, stratum = response, alluvium = subject, fill = response)) + stat_alluvium(geom = "flow", lode.guidance = "forward", width = 30) + stat_stratum(width = 30) + labs(x = "Survey date", y = "Number of respondents") admissions <- as.data.frame(UCBAdmissions) admissions <- transform(admissions, Count = Freq * (-1) ^ (Admit == "Rejected")) # use negative y values to encode rejection versus acceptance ggplot(admissions, aes(y = Count, axis1 = Dept, axis2 = Gender)) + geom_alluvium(aes(fill = Dept), width = 1/12) + geom_stratum(width = 1/12, fill = "black", color = "grey") + geom_label(stat = "stratum", aes(label = after_stat(stratum)), min.y = 200) + scale_x_discrete(limits = c("Department", "Gender"), expand = c(.05, .05)) # computed variable 'deposit' indicates order of each signed stratum ggplot(admissions, aes(y = Count, axis1 = Dept, axis2 = Gender)) + geom_alluvium(aes(fill = Dept), width = 1/12) + geom_stratum(width = 1/12, fill = "black", color = "grey") + geom_text(stat = "stratum", aes(label = after_stat(deposit)), color = "white") + scale_x_discrete(limits = c("Department", "Gender"), expand = c(.05, .05)) # fixed-width strata with acceptance and rejection totals ggplot(admissions, aes(y = sign(Count), weight = Count, axis1 = Dept, axis2 = Gender)) + geom_alluvium(aes(fill = Dept), width = 1/8) + geom_stratum(width = 1/8, fill = "black", color = "grey") + geom_text(stat = "stratum", aes(label = paste0(stratum, ifelse(nchar(as.character(stratum)) == 1L, ": ", "\n"), after_stat(n))), color = "white", size = 3) + scale_x_discrete(limits = c("Department", "Gender"), expand = c(.05, .05)) } \seealso{ \code{\link[ggplot2:layer]{ggplot2::layer()}} for additional arguments and \code{\link[=geom_stratum]{geom_stratum()}} for the corresponding geom. Other alluvial stat layers: \code{\link{stat_alluvium}()}, \code{\link{stat_flow}()} } \concept{alluvial stat layers} ggalluvial/man/geom_flow.Rd0000644000176200001440000002727615146420370015441 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/geom-flow.r \name{geom_flow} \alias{geom_flow} \alias{positions_to_flow} \title{Flows between lodes or strata} \usage{ 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, outline.type = "both", 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 ) } \arguments{ \item{mapping}{Set of aesthetic mappings created by \code{\link[ggplot2:aes]{aes()}}. If specified and \code{inherit.aes = TRUE} (the default), it is combined with the default mapping at the top level of the plot. You must supply \code{mapping} if there is no plot mapping.} \item{data}{The data to be displayed in this layer. There are three options: If \code{NULL}, the default, the data is inherited from the plot data as specified in the call to \code{\link[ggplot2:ggplot]{ggplot()}}. A \code{data.frame}, or other object, will override the plot data. All objects will be fortified to produce a data frame. See \code{\link[ggplot2:fortify]{fortify()}} for which variables will be created. A \code{function} will be called with a single argument, the plot data. The return value must be a \code{data.frame}, and will be used as the layer data. A \code{function} can be created from a \code{formula} (e.g. \code{~ head(.x, 10)}).} \item{stat}{The statistical transformation to use on the data; override the default.} \item{position}{Position adjustment, either as a string naming the adjustment (e.g. \code{"jitter"} to use \code{position_jitter}), or the result of a call to a position adjustment function. Use the latter if you need to change the settings of the adjustment.} \item{width}{Numeric; the width of each stratum, as a proportion of the distance between axes. Defaults to 1/3.} \item{knot.pos}{The horizontal distance of x-spline knots from each stratum (\code{width/2} from its axis), either (if \code{knot.prop = TRUE}, the default) as a proportion of the length of the x-spline, i.e. of the gap between adjacent strata, or (if \code{knot.prop = FALSE}) on the scale of the \code{x} direction.} \item{knot.prop}{Logical; whether to interpret \code{knot.pos} as a proportion of the length of each flow (the default), rather than on the \code{x} scale.} \item{curve_type}{Character; the type of curve used to produce flows. Defaults to \code{"xspline"} and can be alternatively set to one of \code{"linear"}, \code{"cubic"}, \code{"quintic"}, \code{"sine"}, \code{"arctangent"}, and \code{"sigmoid"}. \code{"xspline"} produces approximation splines using 4 points per curve; the alternatives produce interpolation splines between points along the graphs of functions of the associated type. See the \strong{Curves} section.} \item{curve_range}{For alternative \code{curve_type}s based on asymptotic functions, the value along the asymptote at which to truncate the function to obtain the shape that will be scaled to fit between strata. See the \strong{Curves} section.} \item{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.} \item{outline.type}{Type of outline of each alluvium; one of \code{"both"}, \code{"lower"}, \code{"upper"}, and \code{"full"}.} \item{aes.flow}{Character; how inter-lode flows assume aesthetics from lodes. Options are "forward" and "backward".} \item{na.rm}{Logical: if \code{FALSE}, the default, \code{NA} lodes are not included; if \code{TRUE}, \code{NA} lodes constitute a separate category, plotted in grey (regardless of the color scheme).} \item{show.legend}{logical. Should this layer be included in the legends? \code{NA}, the default, includes if any aesthetics are mapped. \code{FALSE} never includes, and \code{TRUE} always includes. It can also be a named logical vector to finely select the aesthetics to display.} \item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. \code{\link[ggplot2:borders]{borders()}}.} \item{...}{Additional arguments passed to \code{\link[ggplot2:layer]{ggplot2::layer()}}.} \item{x0, x1, ymin0, ymax0, ymin1, ymax1, kp0, kp1}{Numeric corner and knot position data for the ribbon of a single flow.} } \description{ \code{geom_flow} receives a dataset of the horizontal (\code{x}) and vertical (\code{y}, \code{ymin}, \code{ymax}) positions of the \strong{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 x-splines between each such pair, using a provided knot position parameter \code{knot.pos}, and filled rectangles at either end, using a provided \code{width}. } \details{ The helper function \code{positions_to_flow()} takes the corner and knot positions and curve parameters for a single flow as input and returns a data frame of \code{x}, \code{y}, and \code{shape} used by \code{\link[grid:grid.xspline]{grid::xsplineGrob()}} to render the flow. } \section{Aesthetics}{ \code{geom_alluvium}, \code{geom_flow}, \code{geom_lode}, and \code{geom_stratum} understand the following aesthetics (required aesthetics are in bold): \itemize{ \item \strong{\code{x}} \item \strong{\code{y}} \item \strong{\code{ymin}} \item \strong{\code{ymax}} \item \code{alpha} \item \code{colour} \item \code{fill} \item \code{linetype} \item \code{size} \item \code{group} } \code{group} is used internally; arguments are ignored. Alluvium, flow, and lode geoms default to \code{alpha = 0.5}. Learn more about setting these aesthetics in \code{vignette("ggplot2-specs", package = "ggplot2")}. } \section{Curves}{ By default, \code{geom_alluvium()} and \code{geom_flow()} render flows between lodes as filled regions between parallel x-splines. These graphical elements, generated using \code{\link[grid:grid.xspline]{grid::xsplineGrob()}}, are parameterized by the relative location of the knot (\code{knot.pos}). They are quick to render and clear to read, but users may prefer plots that use differently-shaped ribbons. A variety of such options are documented at, e.g., \href{https://easings.net/}{this easing functions cheat sheet} and \href{https://www.dataplusscience.com/Sigmoid.html}{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 \eqn{[0,1]} to itself, and each is rescaled so that its endpoints meet the corresponding lodes. They are rendered piecewise-linearly, by default using \code{segments = 48}. Summon each curve type by passing one of the following strings to \code{curve_type}: \itemize{ \item \code{"linear"}: \eqn{f(x)=x}, the unique degree-1 polynomial that takes 0 to 0 and 1 to 1 \item \code{"cubic"}: \eqn{f(x)=3x^{2}-2x^{3}}{f(x)=3x^2-2x^3}, the unique degree-3 polynomial that also is flat at both endpoints \item \code{"quintic"}: \eqn{f(x)=10x^{3}-15x^{4}+6x^{5}}{f(x)=10x^3-15x^4+6x^5}, the unique degree-5 polynomial that also has zero curvature at both endpoints \item \code{"sine"}: the unique sinusoidal function that is flat at both endpoints \item \code{"arctangent"}: the inverse tangent function, scaled and re-centered to the unit interval from the interval centered at zero with radius \code{curve_range} \item \code{"sigmoid"}: the sigmoid function, scaled and re-centered to the unit interval from the interval centered at zero with radius \code{curve_range} } Only the (default) \code{"xspline"} option uses the \verb{knot.*} parameters, while only the alternative curves use the \code{segments} parameter, and only \code{"arctangent"} and \code{"sigmoid"} use the \code{curve_range} parameter. (Both are ignored if not needed.) Larger values of \code{curve_range} result in greater compression and steeper slopes. The \code{NULL} default will be changed to \code{2+sqrt(3)} for \code{"arctangent"} and to \code{6} for \code{"sigmoid"}. These package-specific options set global values for \code{curve_type}, \code{curve_range}, and \code{segments} that will be defaulted to when not manually set: \itemize{ \item \code{ggalluvial.curve_type}: defaults to \code{"xspline"}. \item \code{ggalluvial.curve_range}: defaults to \code{NA}, which triggers the curve-specific default values. \item \code{ggalluvial.segments}: defaults to \code{48L}. } See \code{\link[base:options]{base::options()}} for how to use options. } \section{Defunct parameters}{ The previously defunct parameters \code{axis_width} and \code{ribbon_bend} have been discontinued. Use \code{width} and \code{knot.pos} instead. } \examples{ # 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 quintic 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, outline.type = "full") # 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, outline.type = "upper") # hold the knot positions fixed ggplot(wph, aes(x = Year, alluvium = Region, y = Telephones)) + geom_flow(aes(fill = Region, colour = Region), width = 0, outline.type = "lower", knot.prop = FALSE) \donttest{ # 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 fixed-width 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"))) } } \seealso{ \code{\link[ggplot2:layer]{ggplot2::layer()}} for additional arguments and \code{\link[=stat_alluvium]{stat_alluvium()}} and \code{\link[=stat_flow]{stat_flow()}} for the corresponding stats. Other alluvial geom layers: \code{\link{geom_alluvium}()}, \code{\link{geom_lode}()}, \code{\link{geom_stratum}()} } \concept{alluvial geom layers} ggalluvial/man/figures/0000755000176200001440000000000015146461453014631 5ustar liggesusersggalluvial/man/figures/README-unnamed-chunk-7-1.png0000644000176200001440000020727215146461453021343 0ustar liggesusersPNG  IHDRz4iCCPkCGColorSpaceGenericRGB8U]hU>+$΃Ԧ5lRфem,lAݝi&3i)>A['!j-P(G 3k~s ,[%,-:t} }-+*&¿ gPG݅ج8"eŲ]A b ;l õWϙ2_E,(ۈ#Zsێ<5)"E6N#ӽEkۃO0}*rUt.iei #]r >cU{t7+ԙg߃xuWB_-%=^ t0uvW9 %/VBW'_tMۓP\>@y0`D i|[` hh)Tj0B#ЪhU# ~yhu fp#1I/I"0! 'Sdd:J5ǖ"sdy#R7wAgdJ7kʕn^:}nWFVst$gj-tԝr_װ_7Z ~V54V }o[G=Nd>-UlaY5V}xg[?k&>srq߀].r_r_qsGjy4k iQܟBZ-<(d=dKO a/zv7]ǰod}sn?TF'|3Nn#I?"mzv~K=گsl<b|_|4>?pߋQrib 2* (Ѧh{28oIyes8';Z9h6g>xRx'b8ՃWOϫ[xn%|^z}%x c8eXIfMM*i_@IDATx]e~]z )&BR, DT,AA@-RH!^/symݽݽo2S|37ϼK ("("Dգ("("(%z#("("D%[+SE@PE@P"("(@DPQ2E@PE@P%z("("D֦)aFJFij[W_ZW~3),,|;>+orig<=9***o>HF%O<ʝ,,7tL85=裏ʢE^/YG2yd5wh#=DUi1"0t@ r)]?./3&_v%>|~ӃC_^o͛XVVV:O 5k{ ;O?t;v-$o Yz ~uZ" ܵ#"uQ!.yh')))C,]TN>dy}^;m&\l~'\sc>}k" k.ȐOdϞ=raIrwO?7g?~|>7ʘ1cd̙|ϓ9go?U }leݺu2c 4iR|i477˼yL`S~e555 04]Vec( rJimm}Wƍ.7ݻZ\3g18looe˖Cp@Lku>M6 _JJJ̹mkk>@ Ę/C9k6l ۶mcǚ{9ٽ;$>_w>tu`R[[+\&L c{ƛZ8>KE 3,sWܱORTTdEivJ0,g>V_g}SބSt o3tHE@8p%K.hwSL^z^E 6?OL?Ӭ`dxXiiiUW]8餓,h`8UVE5>?w0XP>bԾߥG)략?2Fa f|s4>{ɒ%>ˋ`y,?ߛsZ*(@ # 1~5 .sw1?oI$8ZQނ6 -)?\Dh,h,̘v.^vևwi]z<7E3/38Âvjllaa6%Q 3g18Lh  ( ILuE@eӟ}}{:h.\vP/ }gccCrmb;Nk˖-,oh]8}_4]3qp_гad&LnEbI_p/}K5>\$w }'V,[$nf.B-/>O$`Ɯ%_oc 3$d7XB jPϏ@}&$W\q>Ouc¿A׿,X!,>ǠuO,`&al'0X,~~E V/LO[`^7$O4_$INK'qbY|9?p`~4!s"̚.}qǹ7 BmM/FjOv͵ -4~ٚFpӶ)7c]ILԘW7_կz]o~EnH<čՉ zןqv{m J[JCyQ.\h]~!׾fgk/d޻đS^xsM@MM#~Mm{-1apԩS"*vJDʏힵDŽ)!(u^k~i@y;6 c!wEq-p0V*ݹ" fGag DwuI(}`2FG~a6mf5S%as#FAq~N,GOB?FhAivWh(jdlOtl6e?wGio[e/LǂtrR@%55U?xПox9U\zc5@fhf_j̉@3-|x Ȑׅܔ,Vzl٧ e|q@`YgكvlXGa/7au~O(@!0t^{Tdp_$rw2( '_o 8F@nb0P<IBH)MH6m<$l_8L2|A9Ʀ*80ۃQY̡ΟFk55N ]?<'27lžuPI5T/[:qɁg\?k4Ԩ퀻:5~ PXjlLΒ`؉30W |aG{mpX1Ok±`&<ϡ%R^^yȤ\`It"D=ݟQ4pfD$>ΜÜx)A 5uxi&IBib)4FRWD2ݳ*9eswCęėp@@!$E;Z jMBβ<͍sݶI X$lov^wunI{g5gy3J@r6/c?ЅaH[c1B ^aj!P,V~'w|l=뭽>v 5*" +4/|J(LL#ƎZ*[cW^o Ç(^sD' giL,ēerjISD2Lm-};ܗ[ߘv7ɨePKCA!S64Y5a8c4\4ѲaIm3Z 5`.tp+;.1斥/?\DZi恤S[lZSHđtp9?KKl~$^'X Ol?{[{8:ƏVZxqͿeԶoءjnV+@ -ްFa2/#S/:wO 9"4Q1xY smz #mLz i3:D>&&|(ˎgB01u\s2۟@3iBW 2;3;00?u #e9pcYoK`o}is)8g&֌e>qX2j>7yQ ImϬ pa蕆)>jx-LE< fY-g`wuXP>#> >{טعz_g=2<z=y'nL(@:Yd!d?arBuvYt7&m },К~(ZU!5<QJB-ׁD8f{Y']tjf?t<33˃@XEOXx3hl?l?鹊"0 K:4"9ICS:.Q*@"+i~Y`E@z@ c1RSِT(!B30ҙzfgb @PkE@ t&M #uUhRg?f92I1˒[EVZytAhem"(6w"("(P!00 Z"("(^BE@PE@P"U("("E@ ^,tKPE@PE (Z"("(^BE@PE@P"9`I[[[M1W_W";|+Zen`l^y'{=LY8pG}T^x]~T>Ooy>+i?l VPE (/I>9~gg9|:I /i/~ 3'@dɒ%^/_re/A+/APE@5tŊr˂ SkΓOΝ;~j2IE/_|X>sկ~Քq%K/dƛxf'?ktRk̾B$fݜ.O?}8tIR1n}M?M\`k꒫J/^ܫ|>] h?[>fײZ^˲7|\?#<]UUe,G?,[}>c׽ӈ/FsΑ/~*x><Ӎv?>BmSO.\hvy>?8{/E'|"W^y۽."(Q $3{ Gq!2n8̔C9DRSS +䣏>2$;;ې jjL"^z!$?$9ɲA;w5J6n(4RhٝY_"v2i$9"y56 %&q#9蠃 )$^xi'>))IhBo*} +]?p!%)wJ<8p ;G+3g4m >ohMI&/+--MNLL4~9S>M$GOS.ǚB2x=B;QQcN9C~yh.׽S/ ?7{ڵ;{gSO={Te~j]V^Ғ@|~w_C*ms}]LM:׳gsN >(6l0o ,X"(@ k AH+f8@88X쳏 7^V~~m Y3 bχfӺkoh̹l`7g~Θ1BЏ}b]~;>)Z뮻1bmșvY |{M2c~ߘwmj?H>3 z-Gu- ͧc'[dՂ؂6‡qe֬Y`y@iܻǜAy H/@>h9>ulKFFj~ [ fc3~^}mLYGS@xX>zu衇ZGynA{lyfwy>'|4g>g}=ñ?i~[ܕ"(@ 0,|@jZOnLL|Om}AL;M4̎zb5zhcXjҨΖɓ' ^Okjt=GcrFؘQo ^Fc6x M%%%>Ah@/b ǂrlYˍƎh[ᤋl ǐd[i55t5,vC8RCMaX XHII1|\lM}4aT; 5رc3ċ;5ž8C/}Kr{cAWO| __FM.1RP³L("}t]!mM; (cJwyVINF2***K ?68 #_&Av:~9Ҙ,]v[IIi9ZFw_ve43}dr﷉$wj}'O73y$@78$!:裍 ӕL8+#$l,יnʳ<lj}-YYY^ޏ{u1$nNw>>5)N칟سgyƤbMHV1{. cxQ[OPE _MO.$M qK3mx!LZ|;IH(vl61c>$ bQ*++QdB_ʂs%'\4QD<ЗқZ4j)NY{+3оiӦICB9sٳVY5e駟6f0M^b!'yaqӤԢW+̀&h$Tu?: smuss?=/ur~1ϟphu`@/5ɞs1"$p 0 Ϻ"( 0,4$$$g)h4Z0ѡd$&&xAa 5xFS×-G0#EMa۩\hi7!?M0Fh׿֊Ҥ΀(F3j›дK<$$ qJ; fn ɝZ0aGг57t`{Z I D~*"(">W0a;}3Q=Mױ&ݱc!LE1J>jt~5\"(@ X?_W+*kኀ"("0`:PPE@PE`  (("("%UKUE@PE@PnE@PE@P 4PZ}yZ!bȠԂދP/iN㫫3M(C@EEp2E`( Lc---C [2Z"("(%sܵ׊"(" J@ zXPE@Pቀ9kE@PE@P %CV("(D@ w"("(C!^+VE@PE`x"txZPE@P!C p!=B755I[[[jj!. S"$%%IrrrԊOEއU<!X!U@<G"Y%##Crss#[֦8gB"tME`x &1KE@PE@P%Q3E@PE@PJ@8k/E@PE@FPhCE@PE@(㬽TE@PE j<$Q3oҥKe^%;;;"͙3GΝ#pB|AAPWWgҁE*ɓ'2=%xg-5iiiΔ`)..H]Z"M8>>z)۽;.{8/}Nu /9&[9ꬳG<ы G dnFY^Հǘ,C~(œ\}ղv2v =x@jN0: $Hݽߩd8_L'=% fmj6ew}rEh?3ϔ$hopon3<#Gyd\1w3m L]XX8r@n ,TQԕ.. RuK'd 0 J%H|pׁ(YYYqw/ٖ,$nR-$I "]ThB@ h4%vђVЧP{% W"kyq|;{;A:+@6zȤr%$|RVhsZ[$Q2%Kfɺɾ :ƺqֳ'۷m5]L(Ցv|Y \I7)E`jbvYsj>DДfX77KsƈC+<Kaj VU*+jx6$2]x>#Yh|'2aKeڴin=Fz駻97V^-/\|rS})mN'{u]Nw庡%!RQh[.T 'H(h2$SM~eGsolvj!pA#33d4\2mXkNqJמ=nVD|󟗗_~Y81clqkqg[Ə/kC@"eeer-ȕW^4í%!SRB r.rRe55 XC*n}C|P]#0Sƀh M'5n)޵e3ZFE.|_>@n*cYĖK.D 5o$ @}dxWbh -UGSKAHmrJ3;eTw@]0Gp]eNTIyz"*-=>K`e6;;`!ui]7nf&.LHR}!%V2Z5kָϣFH*@,#4GOۮ@LH.jZ$ZTݝ Qi9-QKviIR+; e')iҁz 髰|I5I2;KCЕ+wuml$6}ēl\I+5XG]/ArG9SȺ~L*ijo+W7ɧrPX@@ h,Q =Ild Q֬jQ}RLHŴs=HFha4D gѸf4EX:GR?٣7] Zdʕ5p$ žDj<p҄{jeG?g7o4#}ALҫp{p ,;j<ϟpx\)f1E пH10HDE l| 5<꒹ ^/ҝ"=Sz;fMQArA0=3 k @W ~QU{~q.f`.3w85DV"VТ".{]ʴKwuP9aԲRz.\8"ZE *PàP"<:-hN^'0󨣎2G(ϩt[oOjjjLD|Й#ЈC*C@5nAy |i=< &Ik6lm{R,3V>5)3ۼy1YoٔM$$(&(%;:2=TI9S΃?O._9cL/BS{#|S qeɝwo pz /tϬ$jDUXF@ h,]j<!(ɋ\$@>LوN(iByiy,}9UЊ[\|L1kѤI)oAT.F&ŕU:6?3]u3f _K'L;vF:i<?tbj%;7 bˤIyB+1mNNA5 SP0ID@ h֪H#@8>m!CٵmMګm /(\D! 5NxEG*Ф]oJ)5$$fʹ_ jOP'x/ϗ.ٳp_U!+ݗTG%n A'OD /"/}K'pD&@<95zH0F *0n: ewzd#{` q_&-{ oN6T=i#K҄ &iwƌp)`PWc L,LZ`-p6%5Ghh;P8D׌ݒN) Gh\;wpXx7N #,S|?}j"^s@/4fwǎOR*/:$$oL81}qj'L"s ]Q@q.E3Fj7 #0 XDOz:]r>J67G& ||>'/K9c#436D&B%gųSzrMċ雓r6 tfRvHxƷ1eA+%N9fTҠ}I0iaiB,Dzm} F\UU&ucdQH GD9k "udymi~I!{M~%㣼C&ν* HblEl԰D|>(CС?nj;o=_q[f a==#ICRd;CP`Z|D@sa4y$Hhgj@yw ^}=^t[6Eqݾ{uD3Mx肒oC>Wc7G?3q6Mg4m!t xCO?-?Tb {e2edCzK|Iٹs_j9 .,CeƍY0?P &SSdzVT^ML1aACy4C~4y.P55bUvBeк0qty.ȧA **@5>>9N"ucs3R:0. ԩSerI'ɩ*\rI%z'.L7WXL]8!jS.&( gt.u=gZvߴS>-*Z&saKZ D?~>݊ P"[(A@K1ћm9t`!T =0-[LfϞ-Gո>Lm&͓#GU!?!4i̘1ýu >GyD^x-^{=㢢܈v} H4XHL^eYQltvn͆2D4 O3P/4D#bK25/yq)TH" a{0g c&J p)ɡк~#3O]PVl]|,3GV>\۬t?,wuLW|܈HФJ\S-M] m<kC=hWׁ3,B34(,^Lh3w2) iT~ҕMwǍ=)r!r" /Pk"bN@{衇$ VC4"!͛e0]bϋ&xh;GiyxRRR"޵klٲ5D1G%S"!쳏׿'rh^g}IDyߗ;lbV"z|eVCy}($J: pM< k܀CͥdH* 1Шa 43Y,`܁h7 '(PK4!X #gjvvA‰@ (oO^LzR땗wp*j08M<f6yw}"WS=RVV&&%}8昽0kAo@AR3dwl1c$ /XPHLٽH2*($'A$=hkd^wiʳewnTC8;=IQ]^( ;,h'{G k*P.K:D5 ⒃4EЦ`2=T~oɌZIjn9 vԆ xOZTz#@>7&ʎPu뭷;?Mߨrj&u_<ǘG})$ QPDR{HY&8/~^50i&{M3?']](oSv r$)8\}lDU#)$ԠFUcjR0:2*XYb0>-rD?5}W_}u|$cC<{93*@IDAT|gϗŋ `6uM"zg1С+Yĉ9M z#s}#_I ڗL2 vmRu-&-RQ"ȬƲ> ν uYx,Dt|T1RjX.-o/Sq\E@=N@A˴dY+fpgwƎ!"{j$mV˚f1ƉlF!2zQ 2Sw uC ;PLS+̝'s$N oY@X Ri|no5!n8(ф@߶r|g!'|ui?_u~E;`{,ܙ$ \[Vɢ*)ɅGϐ 2ٱ#wQu oGʈ,@ԋ 3hj3@Jioǹfr6IXUHrZ 9 Qi5>[CMil+4hR?ś Lwrt"Jϒ@B;M01x襲r$qE#%)ΏW2י骅r_8Y&delp/]:cPLeI_TN.uȺ~]8B?8I1}:ᰦxDu϶ 7N„\.܇.kD`)݉kTb kE }6dUQE *h§-'K9̛~چAs|#K'g%0Ik,?Q@$U7 $`0km`=0_H24Ii, ؇l.v]~ȖBֆ߭݊Voe aʉ65ʎ3UE vPc-mxA\ߴIFb4+ccV&.%Ht1C?к,ݗWBs0C}j&9eg}]F ytK*Nf:Nh ,&|X5K\MԄ{HjFh\<M҄d|$`&}ES{-"%13xxɝAӂ%p^pb$K9G>xJ۷Ţ6©6_=^3dvBkhh6sGS jcz46w$[HUiZQHWX 3ݭ(aB@ hbcWxR4i;fK|9uFnOj /7V&g͵}{ߟ0 )X][,Z\X ٬Si^P$y~$ Ԩ6/Ӑdi8`e#Wg Š(CAq|~'CCJ54gĬC'Ĕ~hV;W>`3%ڼI:1iO E`0Q=.ıCBJ!Ԥ"r=T Gjh? A>=Wu"G@ |0G`^1mɀfǟ0;Uq}def6 tXf%JflԄ-jjR1g<AThQ[ ڌxZP % Ħ#;:" =ߨC>m"0,BpFѶm[a|d =ӟ@,#Su#FʉF˽Ѷ+%N4t[gy QL{dN 4@Iŀ!Naw?B$ )ilY4nx^6&}ޔ*ٟ(J@=џaS(2~a K;NQ8J &&ES"t&dJs}ZeSHْ-_QiC8A`3`~+cU'P"t/5Lil\卝.iA 3Ŵ/z"%~։fԘܛpb${a_)(%G|0{[(JFipE@ pyڴE7W(XB@lDNIjd;- oIx –0>я{ffIG02X6`AwgEm^VMo±mϣ6"Hߴ5@f$}V%q<˒%KSǩL͕MMRA%)ґ%3 FY)}}4deˤQaH0%pUPr3eȔKT3VصA`+|'3dw8*"(1 Gp7)zk‰_~G2?7ǘwJKL$ ZTr@MT9L.MKBȷy r t{t3vU4ev(kG`3Ze{qGV@kT"Us^B̞rɚnAGP:$SX!dDFFP$:#@g^t˶/g uZ] TdPQE@ h,4_a^..1Z4eUVKD3d .L7(EXEM%;W&#PPEP%;ڳ `¥І?K% GhiW_ &꽧tދ T{1b- _EB[?J@A 0 $,hCsyD۠ XUiz \8~Lt ZN"P)uulr[,E`"tv;;> N V SؚBjz ZH"ЌebB92U;P2E D( ZL| 0?vh?;hOPt]wLKoguW 3Mhv:I RE@$8F}Z"q'.y`;?439["*VEX:z_3QakZڂ i6%'I["CNcS\۝ Љ1{@'ii+>)7Ow$8, dx%$u2>H‚u*lQc0=l:%PB"7.;}Я*"( )x R.%m3#Yu.yUhCij >+KП:;KMFH Pt}- fe>΄osL,,Ln L 6 [WsI>?'Ͼ(h6APC;AT7ڄ7%H!@D\=R!3A"2nɓLF= ]vX#+Zδ$IhR@R>&P[-]P2N: 8:bR1m-rVe&&\SV.F{1L[{1p\礦:sOz$3OxBk6,hUQlM!mg!- ?Zdgn䇹pCVP^ ?=]wWN}ŠP MޕyyRaш[6zz^<0@pM60CleA*PxS_W9E@kuG/z!jÚv) iјq<"{L*œn ^$EЄ?2TT# VmX{6P#5{ĂSe2K0ҁ{ c w#ƹcH7 ,͂{K# E1$5W5grT|PewvHCN_q8$&jPG@ h6p m!x. "U&aiuW%y&IHaA/R Ba4[7@(J@>FsI7KAjOrt#H ڼG3FHsڗ GL_HR1oy5$ Lʏh1I\wCۊK%9K65 @r{WI=&[8>jBu",'cspE T  ڙ@x‹UiA]giWMa~d*`Rop94ẔЄr Y 2AP@P\vk^I^'Ԫ@kŗp6BJjH*Ԥ6܏M=twI-&ov26@Jss)?D4DJǚYR}I8,/\t"F@ h`lٲE~iIK3ΐɓ'rh~$;;>IWG/ߚ6) @@lFcqx!'~.+e'@&ib0Є>G3>N6nDNRU_$B;ŗ$$n $M$XksRنQ$аRQ%mn$}ʏD|%3ex-_>\ʧJnb{/qUQ h?8\TB/}ٲvZ'N;m@-"W^y hǼ/x~& ;d-t=di~Γ :;~zey+;GvATߞt/Sҙa"Н`ą< sg[x{=;19H3ƥyg;&tnr Hj34-pjImmm֔Li՝;#3ᬂػe1Ms, Ɗc}߃8OטJd&8m3ؗ婧[ʸqA."kL@oX.KZ>&2/ui}uxA7B 0D[:^++GJ"D0 #.Qf 50RֆfP]% ֋ h(5ΟMLbB]g-Rea?g GQ]Q:tT.UPڅg c'֖I{='>~Ym{Qs `Uz# )/O_!F`XL7~\~뭷'K?vҥpB9OF j?툒}^1c~VW^>ZX|V`Ka^lk\h-=fm9 9Kʡ*ȗGsR9k(צk>% x۹Xų$!Q8xlq }.diE%j;aI8&LMߜgTGoۣ-!N=T{L>`cذas=#ȅ^('Nn J&eW]u2ќ~#Fˠlm[ioV~L?LgaO FX7~*͛aG U@X&S`cB N=EP%31ݒgrw??/4=;'L |9rJ)))qOj- I|+_1fw}W̙ӯ͛'BMheR(`/8=kg}NҽrAc 9LN4y{FR,`s,C$?oTCGуߍ.j<$VQ zfuyE@3J@ p4?XZCɣ>*<ٳG~mww?p:HHOjjjLD ZʥHg4XIF4]2F^hh0{ +L1[uz¿ce|>'e/+g.ZZ,PE t xn1ׁCmRŽаC{|~WdQyMi eqƓ$2(ǩL/QKLűt#䒈sɡ./S.R$XʫJ64>Gan_!fYRQRi^pQFD L׎&|;DX5abKF YOw}ttmXv7(,,^S h4MJ@szs|fZR,y<6g*;A朼\y? 4䳣bs匒b1w<-v\.TXAf9,s5R S9=IኯXPT|̊SzYkTV.l*UUK;ٹ=kN8{5Wyؤ66dtJ} ｣3djA@R4gHH4]P"EE*+MhǸ  tj5ǂh؄ϺG~>/ g-f MOޮO׊@, 4K\c4R,QJ@ÃkLj xEs'թ3dVm 6D7L,+GfY M=Hl,}Je;-PZQ'g8BFA 2Z  24Z!Pz4Vl bE P|4!X |Bоsd ҁZr6m$u\Λ0likmE) .]ɨ1"Xi%@8hEm̐pVe+@#awHBs͘)kFaFv*y=9BN.i.aI;^lȧ]Lht`ߐ% {[#(?OU\tOD]<;g&gPPj@ ^{4$Faô JwH2sOLथRB阫= j+3(yxtyB+!Nٹv ՙac 24wd~V"]_^$a tDqIۋ伔$9@6!c;vISkΏ>4>.;G7I&dgɾ}fPbxR5ȭ?ІoI T*=t"}X\SFǔ6[PBА*L陞g_is{rNU" O,P _Np!9ɒٖ.8g0w~ #lg ҉@5ϸjO"tuqΤdyi0kQfM#zW22g\ḱ2 ӑzɛlYL8B_ :%݌?v>]3W{ hzI|"Є 'FS,\(#{̅O%$ 0ןcNӴD^,*6+HDkV5LIʜ]>"U@9H;Aa@@T"=aX 3YKoim2VN:eH%/4E+%8&j|@ Butx2Oo(xEU*!IUE@P >HZ\05@Cc+ w[[&#r,y)1Y RdI fѣ$>!3Doe[ [>Y-%HˮS׊@"@ 4aƱDu_@P/v&N;%D '40V3^ix0gd`x$tآ}Y LiCwx AM پAH݁0 #Y/ N͠(%Gڟ;,Cvn.L }3mR0c= ) r|q"Cӳ걀R}"1 U${!~*P=!3#Cf͚%ϏN.^XajU|}n6LG3G0Ϯ8n~H7jeuPk.W =t#'DcO"}B(`3XeǴOWt"tbwL֠';rE ( 5Z^!@8 qIphD[a߃4wKI1unxtM]SMq,ڠ#Ta{$&S5!W Tb%:r!0 /ُހdA:=iNy?@JtydF)p؞ MڄzkB.I $Tz1;KdpuIr-nfb$El@Q$6B\rr-dӥ^ 7W'G{/.E f؅gZb2U|<#19m" %//gD4h21Qؤ)q.7/M ҸsVU%3GL6fv=emf$S:@+ОHҙavxj[Qsۍٺu9H(QI>)'tf9j_GQo /-voIHMj/dd ]-ie8r'L7Exd<+9F8\inwu=DY@RSe,LC5c}t4]b20StdS|?P`eI-){1!Ԙ?W\a'xp^Ԟ=zOe_Î!&WY1\!B=\r{\4;-Gjq;U*E^Z6aDG| @ҕ*O>F'xs[h;}wiU,6KB@ c1|=[Nn&9SdUilN *+žI^gTN* _ 0###laK<2OSXՑ|CJEd?9\ zۋ|$O\j0X|\Yz50 Pq,Û ]6}-ZUH@`ɂ [&wEHHnT &:KJJU+ 0Wq[؝+ޞn WZĽW eg}$qmXXbܰ:u"*eSD`Y hOO\y$@}'gu$tm{1?ө*{z+zijb!5S MeSr$Z F^U!>q1.s vǭ#S!&k> [_>~G_vZUUU|dn֣y" 3) 0W _ *:*G#qnnzyvTOS jsߍ-4t$BUt(%M;s_ __p"0<6(" :HEsU+H4cI$2;aF~) ym@ ،(+%+&hA*)ǁK4f>7؛f"5@7<$I1Z+jnvT`FѮE6k@$d}HLE ?HeYmCchë*"̀]lL1 qdb]@ }t" P'RFj_"1([F63A({Vً3SA8G<7rmC 19$5ʅ^H?}I2)A90\K[ }bpO9y½ qaw|rw Ap) <$$I$"RkdX,u?z"(pп2FIMwS$Hug*Ȩ jvVSq }|$GtNKdOnPBQF#.{v۞ :PΘ\_ t!h354.NJȈ2@0{r7tР󗠢((#=B Ђ6~R G[|1#!Abr昣Bo` Ԝ#H5Պ`fh5z!0Gg NVЪm9 j2È5slDi6*?Rp~*^/[E@!0mEE@;A/ŋ|ئ:fx+d^t94T.4d_~AUCERDo. /C܉$$OOFz>ܞ 7̑Q6uH$|.} )юhA͠&u"`v7vH"&wpV'_ t ?rRU_JʡdYzˆ 0 n{"rIM] \Ʉ? MIM?&0K"(滧}8d#b6!Qś Y?tuA;a2mRy)3KzmDz)׊.Fl'A:V9 `t '|R$ f4D5"0|sEC0Am$ :ԆwedLa_3Uo ? %e2!(ȑ#r-Hjj|K_k---ӟT***3̴ #g9*#;F488'H,b4꠹$5pO*Rᗚ`d\~O"Ŝ Jxsc8#*H7u",% OOU!p,ͶSdQ@@7"om^Jal5bU鉶N,.MUZ./cQ$ 6\pl{O#Іmo3uQALWnB^'HD&= =*.i[W<]pqC鱚TBE HEXF6>&z%6}z@Be䫎&blobכIRRg!狥e3#KƢŴa;nMʬ|d>$),ߢ_l[s_.( @E@#) LGy)4譨x)m4ZIjAA3ЏfI>;trayWxvٿ>9PL^|Eg?+w\qݍg=.$WQE`.( Zz""FtoH!ژhmñל< ѶȞ={&~˻.ICtR3zv&sx')HX{9eUTHpܟ ]SE`%$(pJ+yf&/!umNa>pH?u\Q(6gEEErgiAI2?5!V[oUh4:9t萴˕/| җZgyF*++;δcg˞w xNB@ 'ݯ(+ ]Y[GD` }~0-SʇąҕA8`V@8:;:$^Cb< /Ws0/=;>Y fAN*A K HxW|efr5k& l׿u|CRiV[_'xd^zIJJJ߭sPxv_#tD}mqn|q,x9DŽ2㰍c{CXH3SPx4vڹHC~twSwxA6( {/7'0=y<7Q7G?Qn?˽,q x0B>n H!'b| ta܏!fr><69AATIb1G9TCM4E@XY(]Y[GT%nX+{o\>Cu30U"2>@;lDZUzҔF/ȡRQ~IJ2I&I򴷉Ip2R;'?v?#(NBBRR?C=4NPl LEpل U?9 z@R ZLRZlbб@PiѲJi:$j:׀pnΒj&}]6y".5Eg6.ygԔ2:&z!1 ir~_7wT `/~&"js%Y3%#$ãơ>V0ONu߇> Nt(+ %+xi ^IҋwΚjia 2av!q\yFp09fO@>_CM`qZN9k@IDAT99!p UѤyݘ׹SK_oa: rQ8`IIZ4Т?= /uTQan^|MLjhqӟ$/ȉ'(_| l\1/袰_*u3ט9=O&i S%y#'JLfBǎڂUX*鵵8dNT?6[8ibZavW!/Wfwxde 'ߡyCt]ϵʢ(4U w Ip3[̂_sU‰6lkrӦMŇJ sY|֍"t/?o1G?7s V?巿9ùJa *rt=rwb(~+tIb &4ٷppm(3 @O56bIah-?ʍhxJECao^Na9jLD*fnGޞ}D̘Fܭ6r%up<'>!?OMw-=J!#٣1}+-a6n1|0q#$#eI))*:?@( k0mܓO>ig7RKz_m/"\~ɓ_i ;ee9! #`噽{3Θ3*:4# x(#S6+=]J!~ (jCV4oDŽhm ;YU(h/ӽ%8υ-t̅ư 2hlU#@')7| <{U,jI PđwFc |3&I( 죏>*$ЇdFImU˜!}M_~ǚ>@ºPQ BMT1s+yH7*->\OWCiIIqZb|h22{ ("_6suNsV*zOY|,8u/$/( z\% x^VMw^ DHjCde6"۶m1$O9  \s=?;&l^K/L,h<ݞ )fO]Km(I%}8InB6 %:|sK#9$(;x(E,\ v9Z"7ˢ¥$u^ZX,.֭*k($~UlYg%%%%B=#?pk~;cV[je?HviƧ'|WyoSj4_JaYpN/|8,ozӛLÌ{'[yrI'Q_ 5hW)b.q!W mg%"zgB3&mhq H c%lF i3q>/iKRzzǼ,|w43?q}YoOO#|$ lkk3A?O}S&F@:YuNK>Q!D5k׮5}}LdjBoNaS8D}@Áa`JЏ+|?0:>3 5˯ a23zN #=r;VT)ˡēՈ&)zLc?%7G>2$%|rxa~QQBE/ϸOEPfGGYuVC/A7h!Y 5ⓟtuuY!'u,0VK2;8SNY{6ERP."4JۘBQF1O,;6|{Lq9L6Jgɝ1uO_#M;ٔDF_l,9} .=r@KR<=jLHr'/T 94!o siZUbxokDH\͝ŠE|666% 5&NnBeee@CJP1)Ԁ>&E^>s ~")w EPC3NMi"93bE,u2htgI?`j-ձԒTVL> cە|ZϥX3c,h(v3#)2[ۗj|wt) ( +:3w.L싍81(~ٳZy7yLݴ1TZLPà!T>dWQq?{j> gN0iX:21H 8=XP"4 ,q.0.M /))̤d8>ފvN4m/UȮtË.ydՂ.`6eOVh)LkSe x'#Ǚ3${ISb3 E m,UN M"Â#@?803®j2g/v2}\5J}hXj<  Bӡ/`7z{' h>*Y $ iqc蛑#9DCܻ{Fp~WQ{Q+G?(>B&G DctdUYyӡ9N˅:}<_,*W1 /͙{B-h9Dnj2A<)RӼR5놆e"נY߽sx_,a|L%AE@P@c1.|W4(ZCEjvSDZa u|Ұ^&H7ۥS,w>U"Єrܣ2Dc[.ۅ+E dzuיj6^>\R[l1(Ɗ)u>:>/_j3skMW4S P+-}+ነ4QhH+$G7<(c0'N qyI< v6E`AœE@!e:gQKN=Tˑ?яZu Clʖ ; E2H&EHDB:-0UT2:~wWˎuZ~jsE 4q ϙ'%U4}hQ"s*`nMoJͨ %$@M+Z%F>Hg0\-*X@ꔺ~h>/(@ y#CTEPp"2ݷo0>)kLWU mnzasږ""]مriuldt#S-R<@"J'kC!.T^PJ4"O~%X4"}V{w1盧s2KOV0}[5/G@!| IM8j3A4aoj7|Go6tuBFi'Ŏo!m깊"jɒ'moV 9I =,LnE`µ#f|yjޢ(K[9sM@(7o|3K)!P:W^)?%_ z-E`H<6+SYR,,r!2O3|bWx.u rU?P?Xt% 49zd,B&E`я~$<}~l|DV駟6Y앐-+?}vi?&2kl?e׋ym_Xl2/F ˋ!i Dz"~\>>ykX[A^Ibܔ{\FܟH+IG3,L.293'3ȅ^hrs#El"?O$1@֕ø2-..g}VoneINN*@4#@J(ۙ_<<۹lRB:S2R"cv!b$I] NE\TKwie]F V}|;mo{?eϞ=j%z!P2}{wK7OvZHE>ReHf:4iؖ—uel:IrfvhvBYc0Fز/!9hu1wݹ_~;lъ9] S(5 R=>2(`1!Ǔ:Uqe`F}cvY&GOӳK@  EǞfFe6RZZ:|TRR"xOOZRB"/}Z~p%(1$*@ &M|N ABAF ąg6)R2>Gr !b:e9Lhz@D"$RzvW_}<&WYO"}C"4}QI@I^GX\q~E{rʢo|CsrYb OhOOy}> u=!UqǃlmFRFLcTspI<]tg,+q>FGa}HPvx^i=)uF;<"P2LԊ8|A~ _ksɻrq`. MS/t@8Mկ~e_~ `B:thyL߻qc11F0MS~JmmI~׹[A`Fr#@BS Ru( H\-vbqͱɣ/*aDZO[,ACϒéi%) Ώi%, B{M7G?QI?hcGo}[fwA.a~FKXIZw)su|ӦMqYY{챓uA6/W_D`vҰ|Q.7)F_t_HЄ>J~fiyB,(/=Gje챿g&^}J [iI=z}e7mǂZ+9#q* Ћ= 9S}2H9AE/I[h} ~s`)pAM]2c"0U.D~~ǴDߴS jI#|SGu2jb検&gfctE n>/+6Y+w/Kabo&K\}l~:a5vaBpÆ 򌦧GwI|Xp'G"D+3͛7 8|2ZL/1XtnC}uݻK.1?Ru:s߿ߤ`Ԡ%α\{F#>%ˤB_^ơ5b.i>b·6v INl)g,9ǫEtV`I}Y?XV-MP&0ēudr{;MĠE OB8_J)2vzrUW 7 \sr˥^j(79諶xdho">L+3fTiB~ѷ~%MgkI=d5%eHMM ._(K Uख़A8ޕ О4q`W^i{%۴w]~?'fDiXq~ԠR9ߛk1E" {!DD03peXQɬk ֭[ 60(T fǘ/&9<.O ?h{ rnA -Irݾ;3]0݈l=*xyCO9M!PHk܎BA^b4_<6ʥmFpңbFK=+.F 9Ks7 ~(z18 i9q]YK -{; sBTstu Z~ l,-K-[̨{1Ůe IjkkIkBqL+Ԯ#Bw'/ςxR{K+ӵЖ&7w .5th?o5<}U{rm;oN?PoY|>U[8"xx'a(Pk*AG|{b}. l}<ߺ$40I )s;>V\r v nWLھXѹg)l^I emF/?76cx&a$}H|JO,ohaV1-CiiEb6GⓐqdMc ugh1!a} ~Q *)>X>ߡ`X+zlX~pD7mш4} vՆEA&}Ked(KcURC &bJyr4v|>]s41S#uQFB`"'4Z}n^W ǯ8vfXHe%zݻW 0{/ƶm&8;'>>rz0s2) }$HVB6ԑ' 8rob:M٘tLVvЉ#{Bs:ѯFΗz3ȶҋ+O+x};AnM[\\}V 'L;KUUU(Av/LD+psz{˒Is|2mr?HߍI!ysą1Z !(} G,iJNAMDY$jD-i@X+:WfA(d`ݭ(s2I+B;v fpRȭ,a.^{Xiy^,YRzg '\tErs{-diJ&Ks"_% 0W _f A`pxxh"IKL;emjc*|Cii]}3Սg+ό"D?tgd "d*Kj@׬PM0?-ӂBpCڋ=\YvN3M+@16lNҹ"n$gtt"Xigc2Yd k[hJkjj?r駛Ԋ[jnYS"~MʫȾ2qCc8_I|w\+Y(.^T81զ#-S*S+TCiO{}=/K?c&)Β9"oxL5L_'?lڴIjkkN0ME,u|ifUZ`Y@4=s!Bd e2/L[Dž:G'7&ʁZtV*S[ ռZP܁@;y]U@)4_y&=_,uBƍ!sx.ME 2F7Ȓ돑{dscLG)K4cU2^J0:|@g $P;⺬i+=TN0K?4 ɟ,bӜOH;j{Z;)hǞTV (v&0!UGy9,'QR#\9z1i~.+"8(]\@Di]0*c&~ܩ 0?PV"~::U6-1 u%Զcnmļ>!I EjkNcf| h:E PMwKT N&k):𢾽zMЊ4>*0c}e gZTbk[ j7 fԋ)E]:_C˟ |!*",5Ԉ"D / !ʱl't!OUrAKTw`$ $q >aŢlYҲUm\6nENKɕ9A+!}T\fxxۨ/)@t3CBFDa]"242˒j /;v/"AMM]B+EkN9@/) 못g&d@AH .<M:dXZ s>h(&# Db03ODÛ'۰PJ6&@Y b }pHt"(]b#r=f~/YYp4t0N2c@ `L J9ȡ*IYvLĊp6Ĩ"{i iVZLp:V z:NE@,hξկ\_+ӧ>)Yj1y'"ѷB{ ^Wz,Ѩm'/Q *IȆ(U8Ί81U~xx=,sG*@!4nveqfp ~!90aO0 $u ,dz(r t9Pk.+ygs6B7<>\Q=)2v6\3ǏA'OGǴcm_阺mX)nv*=BQn۶`FUR~3& SQE`9P5# I# |"8O;2sڒ`Mߎm+)RG`&=E>ì̥ 2@,"HRRBPC@ aW  bO`~.-##) 40{oE2)fv-a:&{ *AeSK OEYtr8qSԣr#UA@ h H$ ƀf;4 J+`eP$v }A3zx"̖c *H&,g]\1Ϗ8.=#CҔFP"%~˂_!jC`YRF j/9q(?C2h)SjV7 1ՃZšV~5GpLlG Br"=TE@X.Z"П?49m\fJ :oWW4o(|IY:|4h֎07 qg8m+i .A:H@gZ<68AHRwXGDJ@^iO h,ק GIJ| 9~ KaG%oOO&I-9KXE@MNҗA|IIՊ{d*CZQ`E`P)}YLM0m`XyegZh}*l1|K*m4mvxZ| #(P=<+"DJ@#fhW"S2eg eZ2 -B'V|<--6:1NY՗סb}ije9BLd]G籁oxJ FQ(E ZPwN,0s{i@`fH e[CBբg*gVw^D8֏L'a[Unx(((tLSRg˺ԁf%?^1)ц';]vW>з Cwl BL JyhliFnQd3ۯ 6SjcrN ;ef=䩺# JkZ*RxM=124"D!J@i,8jB >O-h>-{y$$Pu|"%(݌Lgs O8K , <MQ "d%tLnFjQ[o]g@-R>ut"([tfr~&&~DYka_ r "׃VlUIBVKcAj $.`|})*m>ñ>n"D6J@#hj+̣Hf҂@ف5/#}d#{[mZNn?`$+hm#]^z'ǭO;܀~vܞ5!VǫR@@ ht'e#PmAA{{`Y#KN$sMSmj S$Q6 2}ў"W‡L~Ѝ`6 Dže҈/}Drijow|gstE  =>(Q*6L0vgXmZ͙ C)@$Ͷ4ܐCF4)=A1{m_7/eIapE JP7NП >w тrԧS/;Pk S<82Nge>H7e`Lsr$ǥp\Q>",2J@`m~" (sF-(TZIVh4_@v~4#*ާᴛ;ϚSp ȇYfMd0?HFZ Xu,"(δŴwy7X͔~h c@p./HWPcNJ$N?hAI@ A$'xioEQ|gE@P" %vG?1baϗz"xd6y3Lh]T*^TSyL6nQFQ] "<T:ʪH r`PGp3ۛqô DZ!+09D4KD<"ydgQe7%e:$ $ttR HX?:8Af ϙp#-}f@lL!E ;>:bIE@X(]Yn 7-+,9]PiڥiDĻj[8[e&g9LpU<q{zwtK!THczxh(UE@aաE\]ܕ+$ْ*mo50pzx}ZЪ|CXjU$RjG/k𙋾iE PwUqmvD(1IbwjKq^JQv6AmD0"y|U6sG{KG~ H]&m@4](+ %+~hm0NQʡ>x;gdu<&} e:exXz]2S?j&I)qFE'`[ ; O3<}KuuÇĦ.e"(H3گC DoK-hJs/(8^o74D.5M6OkRSZ bl؏~4}@}u^}CEJNahG0 0wЀ =N`PGTE`8t/̤|FoN R,6ۏtfzX>ܷ_ze<'oXX@IDATr(#Mj&`8w/&`yEbڕ.K " փk|u ۇS$-fW;DNIB<9:p9 ~.'cgtLeGE(ˬE@3J@ 6̄r-K vP^o6^T$M0җs{iT ".hߺ`^\Xcq2~*ٞ,织%Z;7Cݶ iAV\m{כv @||2& fٚ[: W˖Qm>>?2zf#!cS5d~|4c f Kji"(W [+@mY%:mDֵԌ@@y' mf{ZB|z> 9MMsy28$#dz"3qf @]8<\&鍛qm H+@P.$E`Z&T_uhAk@ e0 kLJH@yhWFDN92 LJ]޼ QM+LZVA`_]ѵ@ `;#Ɍ c[К8=@+VdP"I;%e!pNu(0{ AӃ~Yu֧ &`Bh;MvOtBw~pHK`w3!W" (cZrAdA(X=x :9$ڴ4_^ L^IN+\+=M"j/-LI@@T"Jz|'~hOE`!tqo! ~jN ZPGWhV`JC5 5tk3\bj j4A.ItoIHϼiZL/5W Z18 XGx#E@P%r1At ] ʒUh4Ε:hAO@$d"ydT>Q#r{G qH͕ڌYũ))"(s@@ CBgc0{Yۃ0*k@>SqWڲ]Юz% 3@z4!jߺژNCp~D@Z*|?SS256E@'J@ h"Pr\xOdiXW\<,*mkRt 4F-h2C $ # v1ݾ"( R E@P %vǴ1A0HesnK},i~zR98jǏ!i#%}Ne&vd(ǽK#􊊀"`.Bm@Ha|ZcrFqH1D@6+ans?긧0ڴ`´PTP}мY.HktއqPT  BE@P%x״1iH]\5>9fe3ՌC՜Z$HNA~BLX;~4&{ H l=.%=Қ%9\UE@Xt.:zE tւwBP@F$1D5AE" f@^p 3 &4kL xa5X,&lGꭵ}Hf+D^WE@P%z1S"%1YrÔL!hA{ҥD@$)*ȣy6 p $'jpIPsѤ~GPtlTY A6>$2ADUE@VF~,ǀf҂FhƼZ`!]Uk\޿R|A7&uwf,Ja DBrQ-0ד򟈚!C@d|j};30\lE@X~.=(~cZ#ɩHT> 0UNz̀,ѧn,{AnVC: n?AMp"4#7,܀xPSjB݂ym'|O.kRnxB]*XVQE XvZWW'>tI<_}rm=E  dXd?Vn=ϡmg%TT'$z{ABRhMKAl=oiB"$|w@).։I 9]SPB䒣 &MO  ec#}6{==d,@E@l"u'O) rAqko+"WCpxG[&u$gE}rރ=LTZ1X&y_H<XMGo):_q>ϋ4s#FF|^K+˜O:KeieE->.(#2+Ҙi䬳2?m۶=czFPTNzݻW덯+v2@/,>mT'BN;cB#xxfqKmO?>ȧA|%N*H[H8OGdhDQO9&UL2Hr:ӀG@<_,g 7I|v UO%M"+a(棅}Qn_`Agi\e5X;WEkbcԣEzԫPF*/ۨ 9u xa{ݐq<$@!@(*>]Okbuc3~6йꪫdrYgW_w2o<9svmw/#Ut3@B CܦNCu%-M[̥ˎzW )XL*\(Uoh~4 T뗓z̀Cx>ҌTGdt IOM\٫u&3ґo+T`fc.we_rՃ\}{$SC,[G$&IT_ݢUV)=KQ14 ٠HH   p NU۶m3 a7tHW_1݂⃟8yz@VQEz *wkHOC<<- S~}Upbՠ {80АI.P\TlCm)eN4q (g!_Y?DnھEedAnTfVZ cCG BG_MaZ3-xGHH(@;*|7LbZ>F2D~i0`̝;T5@.ӦM3fջow!*dz-Yn9΋{Ԅ5jAs;! ]7BܰY*ZɌZHf{ix i"S5*hjk$NEIƄnRt&"KA,fiRzgK5fƨ/irRkLZh}',@֨ءPbvdLg7N=bDAh}u(Rz %#K,15X?V4ts?.EEErt.yWLYk:u|2}tS7iDW|<%@x ˜ՅA*.5kjtxA+ ƚ-CET^=__ftN[m;3@B4e4N-Hw^*4.^E𽕞-tĆ#R4[NV]djwoOKzz6³YAӴRbCp7xxe`VPm)PzR- HC )((0:rϟ?߈ 6ȳ>+/\wuI&IIIƍ3'N4ӡCʇ~hE+`4)u[o#UjZW-Vc0͡Bh4<2bYz++˥lk Vo+t%q kIO&-U%c䛚:SnX;т5TS.P C.j($.RpӬhn lX/}dŕ.5,ox0K|}"TK xϵy #XM߸qjGx6g̘1؎)|$kF62_|Ela4|J<̪cǚ~ERSoWƳ!&,Ot_}^Pjq~(1U:ݏvM*BGi"jO/lCsci$@$@$=pW^ǫQv!xx@J=h85F{,Cw,L݇>EZӻŨ3U3.^Pmm.hN&'&Ku[WNKMEd4|)/K$ :G$۷lCNzJۏcܷX;ArW֤ǽZwң nIM7ǒǬ]uaLjZ;@iO  ,1O>$3B.inw+լ&/0ݑ\bDyj.#,Хl ZwkL}d4L.n5?&YSk|ZLq E[{^=]HHH;' iZ^WSF]i\ ]W! Cr6=|D?["WhRHHH#(@;B@7ؙ.jwosv0t]bqJ4"ä-/A9}X*עOڌtR(HH#@!n'n$'%Mffh".}L&EFHvR!;e׮j)^yf̿7`4JDhZxK\A$@$(@Cs$P*U6x,~}wu:4:am=n6jcFp=]c<۲madzrD{;|$WLLj  @ ON4:H%*kxמJzzެiq)N]՟Iq:%_0$L$@$``}zn='XnjϓSی=E#lyWPzF;^PWѯDʴh 2t 3%؎xuIHBhh؆I! ؄M$ѳ':\B˟vfogZ^Pw{\ 'Xެ/$Rt|,.ߺd4I!'kݒY^mw[Ϫ7Nl65۷lDdž\"?s^fkGi??6D3Gg{LqqYZY_(c6op]rY#5,Z(QNJGY}~CMM;B|MTDswlK cnH?h0=-k@Sa1_o\L긨^Pw|c4Mb2"4rMrS;Hק-u ~SԱ֡-Z$ϓO>Y./>H_v+3;| w9U($fOWL=qT @ < LZ\"{`~iNfGn5t[,(Ʋ0\mC/ȳ6y)2dhO'I$@@ $hzw qLCK R]wY5SMXF@wCBR]Y١]w:A3οpϐ%qRt`X1Tq$Z]vzYT64>k=KJJ>g]#޻;r'R~wbcBkzw:ͯBB#^tӮb+%fxY6\*G<3wXt9'YhsGCU{AqeZ:j: oKIz:f䙣$,hMPMz}N)'x~O6My9sϕ;CG=2`ٺu̚5K{pl}5\#&Mc[l~Z֭['yr]wI.Pm]:'ug:'@oukWo.|SS,zSv{~tٕ!JˇgN;.G]==bA=SiSu*>Y ͻv:E %D?N } fח{5jL:3g|ߗ3ge…r%_.2h #@1P6lx??7i= 1!=6\.wuѱzvx qǥ9d$.d'd]F-)|.8QĨC@3--OLOAlnذ|饗3׀'?c)5|L>xE +4q?Ov;c 1b_ҿoKzK,Y#w=$@$@Pc"Шb@B{zH z.;;uAkZG'/_×j޵KUE ;4z`v|ZeˌtҥrJ>*'tsJw8P/wiisرc?kʚ5kL&~vv ^y!. @؍@ J, @7DTe0XϹ`3{EȺ<T㗬eKئ 辔SG>W~GN0*5 2#tȐ!CZIdV &xs9G:,QϨu= Q!Is] Cjhӵ/l u5!4),/1OK&k8PU^? !zYҠiTd4Gioݯ~+?Fq^wݯ$@$`gLB 5 f23|{xRgO K_ԿvTKOaiڰ^i-EC@=^dC@w}&+T;NQN }7=pr<Hh>9޷m h&e׾[POUx̡e֬9ǩѓ*ּ=!dСnjf+F#2xgL͛7[oq! 86ᑀ K i:tf{񉒛,](z|(o^Bk\)YVi f ^m</*iԬ|xO_r5Xr-m`Z}rp4;4vme]ڏ?IHZm̈́kHG$WoR~W/nԔdRfMc8G0Ηػmk tdفwT]4@~7 @PxK$0F[Pn(QK^W>z{O;z^G$@$`_}Y8W=#e WGY\KM hGq? E=S:Is!K<&O=ô8o-(e6qq% , А} @tn}M_GWϏ8KT+wJc'!1iߜ#2p̪ʮ#  P=L%p<|MuN2C%2cw`+vPY,UҼ8I-~GIꃒ=#}_+7cHHJԯyP +r &-u:~}=/5Q ,TQ\Y~ hl@E۷֑ P 4/## mӽݻPmY$ S7-v3-2:D[VqC_@  { jV,i34?B}T?oHH P3؀YZStJ~S)S$$b= Tdz c eYE,-. mF$@$`/zM7ԘNaJ3'* _>jZ~"teeV\M$@$ BO ,Z8%%cPjlFVˊJ)D/]{ ; `&Yr&3[c;唎Z;'G!YW]#U8vq3  x ReF(XLөuXbg:OyR1V# J$@$V_^>|} 0u*lcn4Gݘ\(+@]s G!۶mO>D|MS^_~Yx>W}:ܠ> p~Zjb<f[laÆ9 c ~֬Ym>FibC+FA?VۂyEiiɎN |sZn>UZImi65b qجaiZUUU <xpVWbccp$;>2J?~tz&(ZDU  Yj8{Zhedrss/3HIIx #PXX(xk'fOh$N")~ aF_PA4Aeȑ_ˎ;L<̙34n k1e[%55xM&Oy$@$@$@$@H:khh0|AwxÜŧc|`>P+Nx LmO   A#@3<1 'p P -OL$@$@$@$'*\G$@$@$@$3>C x"@ ב $@$@$@$@Pzu$@$@$@$@>#@3<1 'a5OHHHH|AP_P9IHHHHHHH|ATyN    (@    _UHHHH+[ PWW'_}lذA "Æ UVI\\qn"Eݻ%??_8 IHHxVh/}'7@h4wT[o%kɓ_K.k$$2e?ܜ9s[o{v4ܗΝ;ODNOOc+{Lnf:u>sСCyfٿղi&p6z[omOFϬ,/r]~ӟ:kٲe&\)99YŒgy H&(@m 5 ł{v}k1xLAʞ={p{d֬Y@=\Xz9V' @SOnMz)qGl_,ƍ3{C=$^) /l_x}v9:L_j̗|—|ю y_B/Kj3 J#;XRRR(ۻ~ag??Xx ٸqkhh'̙36O$`K[&(BٳMl(Ǵ'xDntuYO|FD& _%|Sx5ʈLу:OdZ' ؁ǐ(W]uַ֔81ߐ׿ՈH… DG IDAT0xCJI 뮻y 4 $ >\z7/|P  g {1>]CLSt (׉&aB.L2bEnjc"FF,(~^{?Q^xP;L,2 x#pW$9#^F)_J^yE2QO?"&a#O4ۥ7b;b?B2/~ (EPxwemq2!ooSC4m S8uϠp @>[Hq7lF=AbxTj!N0d? + P>YHH 62.sG-) oW(@}E%  /Pu@QSN /{r5 ؓ=+GE$@$@$@KYhxc$@$@$@$`O| ,a G#"RF Lwt% tݢ :{φzna4 5 '񒀏,..6E+۶mG+V4#%Cyܿacٷo\I$@v&)x;?]L_Ж/oSrƵݠo+ /7ydπ|2) e^B@zzۦ?豈F?MDth = O?~̙3M"G/'xB˭CL;M+SO>)ocV_LwtZvvm3={}ݦ}͡.:ӜwyrM7)s> uE8-_\nfsO='Z1jNLD# ;SH dgg6y֚0D ׈# `7n4sʔ)r'NFW]u_~L0|"7=O=T/'Nto]~gaQǎ+V*'ԢҟguҥKu 믛ֲ_ihTN>CN8t{ӦMb򗿔;x1=HHЊF$@K@Y;hvgm=裎8Gees_r477;MRt 4ȼ3fpn?1ϟܮ1(d֩Xu 0G>=sׂd چցiCŮy>*^zɡfy~y9T&Ε\  `-VpP$X0厬xCWk;wUtIf m ]ccXBzm D\J$*" ݫW/_o[NV\)hxa>Ǐ7\kweƋk>|:Zc8s&Md+@$@6")x=L~YT";iX w 0x@00Qo#6{ԓ*Z333Ml(bEջB(bwKKKk 5B"t"׷&!0N\u ^^s߮L$@v%@],EB;vLxReܹ)6o,-R?l;:`.!DQ Ͷ Oq}L 8E͛7OACHCZ"^Qąkf ='' @&py %H (@h~'` $#G1j7(;t`= Ec6M!!FmHq1ꫯ"RS HHB6<_x35HXꬍ5JlXmٲEHHn(@D9A3f<<w/,(L$yyy38Q. q8x>K|btXe7񜈳Dl(h{Xj%n]weS]!cHh0=-+ @ 3(6O&J'!]lv\`4  | %$" , Оϫ @|=rHHHzhIHHH P#IHHHg P,^HHHBh=rHHHz08b4IENDB`ggalluvial/man/figures/README-unnamed-chunk-6-1.png0000644000176200001440000021437015146461453021337 0ustar liggesusersPNG  IHDRz4iCCPkCGColorSpaceGenericRGB8U]hU>+$΃Ԧ5lRфem,lAݝi&3i)>A['!j-P(G 3k~s ,[%,-:t} }-+*&¿ gPG݅ج8"eŲ]A b ;l õWϙ2_E,(ۈ#Zsێ<5)"E6N#ӽEkۃO0}*rUt.iei #]r >cU{t7+ԙg߃xuWB_-%=^ t0uvW9 %/VBW'_tMۓP\>@y0`D i|[` hh)Tj0B#ЪhU# ~yhu fp#1I/I"0! 'Sdd:J5ǖ"sdy#R7wAgdJ7kʕn^:}nWFVst$gj-tԝr_װ_7Z ~V54V }o[G=Nd>-UlaY5V}xg[?k&>srq߀].r_r_qsGjy4k iQܟBZ-<(d=dKO a/zv7]ǰod}sn?TF'|3Nn#I?"mzv~K=گsl<b|_|4>?pߋQrib 2* (Ѧh{28oIyes8';Z9h6g>xRx'b8ՃWOϫ[xn%|^z}%x c8eXIfMM*i_@IDATx}xޛmYrq 1^ %) BB ɗ@!Лn^$Kw?JwJ}癝~sgvμ&XQQE@PE@P@bQE@PE@P J@FPE@PE@*J@ ^LPE@PE@ "("(QE@ hT֋)"("({@PE@PE $Gjz1E ܹS br=n!W\?OeРAE\.\wu2g93;@yy Jqq<~/gyg;d̘1~'|R͛K/TG2vX9z6i!=LbEP hw^><I'd^v<jL믿mn`IN AYY\Rhޜ8q5jaժUvZ>|ަ|9ѳ~dffv)u6}Ͳb 4it9^KQfΜiO 럔dbn,u.ApB-FJe2rHOJKKZ\6m18*-2o=0Dzƍ0_[N8M>]̱?xg}[ZZ?CIbL- ۥ"VzpM|ئZ),,4"4g;%{_ 2?|_}Lс&0;ψ'sE 8A@onK˳z.߾}_:Ojj\>묳,xͱx1Xه?g3gYO?`*s^ rԁuK.ĂYs,Ȱ|u=ǁX f]- 1~͜$V0:r>SN*++=ZقYҴ>I ?ďB bqN>sŋ=zč}gv~l?xN\SOɾ6# MvCJKKzN8̬ƙ/Y.`4` {j}/pKR,=k??{e <؜cLv7~gpO8:=|IMa;hC>Xow(@ # 1\?@4x4_?s9JOO7/2Hh qQނ6 իW-);cX.I"4`ZfL=?Cs-L,nߺuue`ͼN=T B9װ ("_fМY/eB`wqk$: ^" b}2ns!ӟyY_~9/_·~R_Śmֆ LY0;>'&к~ qy <'t.%Y n3eXp!6lŗ-$\E]dl^#hx9N{|| h"eYNL7+wX7Hlay"/IoV3G!$bgK:W @s_}fۼ=k x V81hA=ӿYo}M@Ey[!Mt"c⊀Ii 놤̞=l:I—OIJrp`~4!sr]SŲ9vyj+mm|1R{SlmM@mm%Y4?85Ivap۸q"*PDʏ=k S;ZtM1c0vqЮNQx]ͦL{~zv/,'|5:!%)Ж@ F CE7>l+S"޾SL1IC_צ/-xa >ϧӗ~ -rǚoL{{yrҥK G}9TCmSO5/ 4̦*p{;T qfZ#! -)7X" 8{M>N9LD޳β{lüA_n2ee(@!WW 69\ =$Bo~CĠ0W]u0:ftSy-HBHhBl &ht]7au8{*$g &p LUID2} i9?#>n+ɶAc6}m%Qm fm9ql?Q6$))k52$78þV)eCĉYm2y.715Ai3?^b!Pk!$D H= M9={߷ě®Goٞ`yg| 1(@\PFz js.r?_$LR;HmP ʼn$>f?L \e;\f7?:_Lr`u_:5t]rx'cO dhecg BM$W_dljo&mnrѸSnFr@aSH`).7mnN%搤vNJ\-51Lv&bg 6Db M0eyCKeǎ޻L5>vqnP~@gufx*8#i |MrM sqGaN<۔F : _4S$PCIM G PsJ t M4Rhnv)]L/JNaĀyq:')Ph~ @f'I}>V$ZS,os`mH2or|D駟"{Ẏy|7>tay$؇|^H+L-jO*@m4Bݳlͼý~D ".qE@b&5=\C*ң025~ d;jlmM^yG}$$;x͹?\cj4$v1mOɡC&dZw/)&o6&c֝!M2jj~ddHzȔpAy, Ͱ1.hf氤 B-JoY~0pt8}J+;ݵ[|p_kksnN{j^jMmr&G~D=ICs~җ>HlOXEM{wk7o?Zi9˨mAd7E /.QB cf‹㏻ӂFD,M.nLd}0^v8dj:( I1m\H[m*u}6utFǃ({6‡D_ÄoeQW!&<1`TFw'LP /ԨdLE"C $sws9G ֱ Km5WACv9G[/5H oje݀>5@sRsmW@p?^(FsGM*q _{-oף`5kʡFZo!u'nw]sa`cyh> _xz?cWCfM-PcEK4"9ICS:.Q*@ECW q>")"(>K 8QGeJ5Qّa jHgj虝>=AMQEo$MFTI$=(K&ZnE"pM7\̣ی ^z)"!]k"("(}@\a+"("(P ]RE@PE@J@^BPE@PE`7J@wcK"("(Q@@ h@K("("F@ n,tIPE@PE (#VTtRկ~)_ʷ-yͨE6lue4.?pldpI|Iy62C=xo[қJ_2yp{S("y_$l _~}5cóT$>&~^^?7c?̟?_}U^l8sO?gyK6jݱ"(}@r__\~ٲefTZVZ)/N,YD:,y衇̦6{lz z"(@!7ŋW\!wp?|qҟ{9ٺuNM&I"(7|\r%b+wSƷm;wo~K~mY`xf۝w)Jrk^rrJv 'oDžzKJ961m9)r_/~aI~_wfе&38CZϞwW?r駛2֯_/7n4ua}Y(3G?n ^)<9sO~\,9#znnމ'(?dӦM~jn9wZ^˲/iߜϟGyD{wi,?,Zȳ9k߽È/F3ϔ /Py.%/އrю>Nq)?#<ӦO?-E7|#\sǽ;,+"( $3G} v!C#GJff̚5KRSS e…dggrAM^{%]v!$?$92}t쳏ڵk@ M4s;?m6PNJ#WcPa78`8|H_p^ $f$ mhR'$t8Cd)OrDLplRnnަ6AcgΜil7#IVVV}'~dL_WZZP;hH'4r' }ǚIxٳɔK2ľ&` r9'Adm~pN:ɐ_s~4'{x(%Anƶ`/_ܔTUUepg{O=Ty#8‚ͬBiXnY=M`m2e"kVL<h#-{Os;94 )-v fuȰ@\:Ȱ"h7F҆뮻ݏO{bA<'|4u糂`@ /la_4끰U7EuAPE >x 5-&L0&]jh>K'o243Ҝ2;>.9,kذaLkOM%5ԤQCM-cǎUsjt=GcrFؘQ ^Fc:x MEEEAhz'QCLM1}Aa9PKK,/4;jm.%.Cjmf^5s-kjj Y~rm֋}b4ؚj~&ʘҝ{&{#c%I}ohbfI쉄/]h~hc\&A]6:V bL&$$4ӜLs-/r.sY?|2yD>OnݗGLa}ivѹ[5IbH~ Ij6! &O1wqX`%XnWE@.qA@¤)G- չN!v2ƿл dF?ӔM2Cs"}(bH.Z(BŲF8F^3#)wf iʱ-$4!3z# ޟ0*d~$c$wJ; f0f;P $V"d pk_נNE ɴMCwM3M"Gfw_{odB 3?Zxes9L.G=3?4H_r[pT5n`[lv>H=jK8ҹ"(@"n羾KTn2+o_  (1;9}|k_Լ1-/Ow+LúA6osh'A T`5mI>la5$21(),)ĖAE$$bVbP/}m YW]|]x~3}m"RurE@P#w40$梤IA2gc, }wif5&Я٦/XEPE@P"o5^䮧%ɾXnٲgĢɘn =%l?5x:S?.Z_E@PE VP hTI?Sz//*E@PE(1tz"("(@O(("("D%UKUE@PE@P?fE@PE@P 42j"("(~4L~ͻ*6y3uIDk3{gs0ԳՀ1se dK3֊*~(//X:f8eJ@cǴ"("8J@c"("J@cǴ"("8J@c"("J@cǴ"("8J@c"("J@cǴ"("8J@c"(" IJZ߆iii 4=6m(1 $9YΌnsJJ$&>C^^Oz^ 3h,j'WXXhoҹ"رC222$777f۠W'G4h)(@L!L1]ZYE@PE@Pb%߇E@PE@Pb %1]ZYE@PE@Pb%߇E@PE@Pb %1]ZYE@PE@PbCC}XZZ*͋zrI~''OzG`Ųr_ 555&mMffמȮ&$$ȉ'('kR[[kK]]dgg{:s kE'hG|zs}sqjD#eF+sUKK*mؿ_}L>=*5_tCprlI,\(b+RJ׭/I&^6XOHJ}IXd6,sH>۞\Fgͤ_acq6905ҊW]u<an-l1R$k^=D`g]9󩧞ٳg9/N:XbZ#\t8#/%!E2NHl/#iYN \W1ԶIekTLVJu{Ԁl4 0`KOO`2HpuiNNN\:5J@ ynC׀") $%?TbfHq& m6/ }d$KsqLfc76` 7^$w*vU+S㢭0=qRm">K-)hjSFv/vhLAJ$DƂT A롍 2$shZ ӠɃ/CZV)*_DH@(j…2|=Z.2?~'|r)m0 SO/Ҕ_!i?-bunS"He/--bqڵkO h%9ƔUHR;:RHh6_ e1S957KF@KϤNY Q[]V Gu*t?s7ސ;L&M$$r1ǘ?QF?3Hqq!+V2|o`̥K;pVJ@O_hMiq=5Pxs~i?4b|9TȚ(^j8fD2XfnצbE+0,@!@I/܅|%Lwwb:uT8 _䥗^|+<GyD[Zc*I.*@_"/k+"'>e**Qh-R4sSN e0\Y)A@iJ# Az!L{gDqF`ʯF}j@[WcU㡱ۓ}<7A6|x$|o[Ν+'|2e[2l0믗W^yEn&Y\rIruE6q6z=E  Zfb_ qbi H0g%Q)xN7LBԂIHNN!GB 8ju|4 T= ѯ)ɂ#G믿nF>˅$>Pd5]l8jTJ@ y"E IPbe:6jvKV]HH~k!]cƓ~adpΆ$N@ _)gij4@(&&^oh2糈lǔJ*h C D17@ f/t82}mľsi*}_r\&?v3ۻ=#y'f"y%¦;#+}0AmF%L4JB1!?AJE nuM' lnFbVLjs9[vwWkؖ"poS= {(3g΄WMkBn͐c=No>Jlv#䳋ۓ|tW ` zUE@x&jh3H} $|`Ed~uh$aXkQG^6' ȹjAlK(!)G `͈`stysb.. *QZ<3 ??$Lu9i~_ ^ZVjBg̘azw{S%P PA:?Yrq4p;#V̿Z,߀|дIi, &I-nlVָ(ss '^QW=*hu!&X75X wVIY(^ڜ Y[6oq2>!Gq 8a8@y?,UHƈxE/Pڗ0#P=0n*qͯ\j=%$_ -iC 2:.B)L4bϻ+1, vTS$FJkqy?3X[-JI2 Z7rQG?^m_./rogӫ*\pgd%R#J@ y"fK^' h*bkfy bυyNe|oj=HJ:ቿuU SB ri'AM4D֮Bܶtq/+ wY8 I -u/sNea;ISF[ &媫NȂ r0HRz}ٻuD%Q\/zZϽR &ԷGR1/11ΒxRi]+~b07&[|~66T*Mc:ɩ'}XG$]B;Ke3<<^fl(I  EU Y$ ;vlJ۳(%@ |)'x4POpH;J ꡘOOQi`ПH"gQSߩ.7>Ȇ"+@5@J236Х$5:׹ WM- m?Gm"Cκpa#da^2Kx6W4?3p: po7M*@OPSg[^:lҝ&uS}=y5OE` !P{Uw9اNزgD4;טr(&'a !mQcޯ /HAA}A׳>Re#ر.q i!}=bM͞d=d॔yi&FAnm,s!iԢs܎OfJLy |>h9 EAT3Z=׉x_NJ /f.Mƫ1๛!_5Ѫ^GH(H˶|&O (}9yeĉA8 l Do N`D-SxI *}`ˁF5f\&EDAA]ކ9 " EH0o`wlHF! !lNU.c;JeJe` _Vd~30ĀBFD%Ǹ_ _~_x cxժU>kƤv2CR@r j E%ܦF M7Y jAO 9e=^/' -P?  6nU;]UҎg1ceMFi>Uyjk9J@yEzhKdr]~ig}85X7BوhTX[2;|ۛe+caR0SjMОvjA޶ٲwk7Ksre.KDW5eb\k}<\Tj@:_ s;3A软w"YFߘ(=qO${ f4i_xrwсj?mX[ @Ӥv< "G)AepTvc$l݂Y~&^tNNVQ;axsߚ]2~$cI-O/޼\8Z%סZF *^g}V

{捛`RlW\؆ۉ!%O%\3n$|4$L%^NƔS2>"ԀUIJSJ'^)/;`=8*%E@.'QcǎK.D?|Y)b>#CJ|ꩧ'0տ()"۷o{Nt뛫E{$ "~|*1iĈ&=05%:*h8{av)e0QK`.i=6Lcj¶H9ro@*&f2ވoRfj7Zt@-ԛaPP(AX9a< ?vGZZ+i\N63[%t:@b>Ժ[S-_.c} >+"л^WI‹dee˾+$_{5i ~+ >JQQdb۶ma0%B\-1txLUrss夓N2'I P˹$jyN|-Q_Rƌ|\;/LzTr*HCM%1 r^ |y 5Ulmg}͇W} hmB<+A~$.`ʧ;eEMpx`Nż$,$\7{%Դ2%@27@ NmKmiNۺY]qnLG~jz^CGiG .yH%qJ0l?׳ƌdR9$?PVUU8_iBnX>δ:hҥK(yXXX嘹sJn=c{49$crIFWpסc=5͸ԣux1Ղnii/"݆?o u/|$ZI)R(v?{(GGmW6~ }UF\yq wzV?1em6 .C"@_ azTM<:X~6w%齨h3Qjkk.#J@ߋQ!lӽ d nvԩf&_<8ָ>OHl#hwpo'6}1HH"xX!p3Y~8: ]ղj;X *)R -h 1ЦRSX]@h)-懦ʄy^m)*? $7q&Դc~8UwNOlhAT Q%YA}B[$>w %@IDATH{cqӡ MO{(3aՋG$ XāB%D2Q42ټq,Yi55|:h`9M25DGHoڕ& $ڶkD`q:Eݗ6}>[b_RnWo˿:32lh)3AV3ᣚ D5<"M(wubelų6;Wvp~;Jcd|rRQz@T'& 7Хx1oٲW^yEf͚enh}_~e9?4C@k9] ֕BD|@iU5nd?ť0OWSQGQ`!eАrcwF׀|D_ L]j|H> 3Q\9E27-U+B-e ˗`g>QJ!|@9 %9m /XfhR#W̙*@, _6"i݆|{#? UٵQWDq%>sct0; !mr/7[^!+jd4H 8ґk7]MjyxAihwM&0-05LAe'7 .h\]вԺ2[ɀij,h0c9H!:Ng9'GVq# Y].'`cdʍvccl cUDZUgz]lE 7<'TE /hCk2X|- "rmh=@-"3C !kSH^ WODPgI!4G& s&a=L<d3XfSƕ$%6mXaVL-H9oF0C5˜7nT-EAyӳŸ"n`P %}^7*˧y$NNsNgM~K;aga.T4 nHIȁD[%J$o9! G15`zp60Dh?5m@UE!&l ^(< 6B| vV-y5ߧ9Om Qmekhbp@V7ĆZʖ ̭mѺSP%}^ox&!K2FLb*"_W Ý%К3t B* DгK}T?DG yɌ޺Mpɗ0pJybd9Ne چYOUZHl/ʹIsyG+1.0X )TYtap<-'[JSE@ %!h~ نNQ&%H>lG ЈAM ft7HNs7o\ڜwH4/@E@Fqq)a|LR )pچ;=TSNC9B1|ez% RŜﭑHt0|JAt7ƫ'$4B^҂ս}_a;r 6 :E@F`Cw[Jd6DhZ "А!6lYZ̨4 Ι-co&5MMh:}E{_ȐOG1;/;VEPh܎ѸZ`^O w r*X%c9/Zelŋe2'0LdiV̷Jy8oA5N0@VQGܹS0}ݞmyaٲe Mi.dڠ$lu˭jAdx F-ij™-0eAP #J&B9TCVr$!?Q]Oq Dٽ#E@Fަ{>Q*@"OeeeRvb13aވ1w4#ri7ɔ@,s@63r%iV216YHferĮJIGt38ZGKܥ'6>9JjӃ.(XGy"\^**Ǫ?t"PM&7ouk?h e:KrKzʐ TrbiFT\mba$5ZhEknzD6~3Z}׉]J0AVR2Ygv<.ޛ6.F.DfHϐzhRB{VO&r>X#y}hy I2#eʸ0 @I@C@ hP0P9Z+@D=|jWNJ"2sR]uQ^DIʑZbAdE$&V %q<R$.Ƽ< ZHD{Ṳnlݒ/_`TA\_XC wzE`g?گUb%ރZ@HۅЄ?YjA¬Am >ǎnD7,fDXgt\.)E'к ;y$/o22 F{}5jAsX4CvrMGQ~AZ%E J@c B> LOBDhnWC-Ime2,*"{(>g =*~&. N,  pORbuyЛՙRNtS肀.p@BB:$ Cv. Ϲ߃ ~Ҷ("Pюaw1وD5‘EDX<b2D73>y[`#iŐHߒ"H߂uNXn ht]pMmXozA;V抁^m655:ZhC2y7&b]/8%``c[2`T/.'s|$)XNd=!A\ -~FKkmr$JOU~o5ypSQD@ hl:Dfrd5xy+@dPFz<ν}{| K)_nxN}/M 5Ȑ: j;B59 x${dX |qGxCm߲YX,iK  2%d5CfA"͒Uku8jYAqy@=]'('Ո,|΁%7R ofqR,8e2BёP3+[23zWr삶eU/BDp*i'z3L* 7м%$B ra2$q2+ʄPNr O3fF |Q&r4^n1myk-yv|.7sv뇬ԇffаfBmjiV+Ijdc0hvO5s(7u$ kBIN%|BC ;yG4M{LH4vHEvtNм9 #hcꘓlA-s{J$ѤO46Հ̥ LH㌀ |`VRQo؂B3gsr4a }ۈ{hqe] ]-n3V5Y,<3YIYQMrod47<3ZoEwu++F /S\ަNv%YFae޶K}3>GsWfT@Z- ;A*ԖZ0IKAs~9hO_We֊U^%܊uV#")+6hLKf46pGzܿ }m8Q=H+'I_/*Qɸ0e,l<#F yVsS YZX$wCh(%DyB=5RA|lkO2 Y-e,Ci6AF A4"\$Ă{qj#x%PuTlýDڀ1 H]fH*4@RA!PC>zޡԨff9̈́F5dӗu  j3,ݦ(o[w"c~vaz $@imTM#nXae9DN](~,܁|p: 2P`4))(œ`]}JQwUKw'7m=IZO*: *˵ʷ=7H麖vY)(,U8n5t Ȁ64 iR@\0`9s1> - YLr{2VTE :(*6l_|.rꩧرc{\КO[nEA0=fѝm1z`S\HkMNd&Rh*`_H,A9ҙi^Σ/ӽe6mBG(#@-ej{ Dw}C4eUc6S_2<E*?` Y5~~ƴW LuEn6xqʧ fE >pX6wyog!˗/[oU{93gN*++{G05'!h@ǔࠤn#l):Q%#pYfCc/\j[h:',)9}6Q&]û;b(ϩOy,S"*&&<& UxZ( fhs xj)Lp{93 Udq( 忧Bdr_+9 &Ŗ( Ľ6| /ƍeȑ_|x=&hffF\GH&\Y9/1k0_@hő;񓑣>65HLeyR%e(B}((-A=Y^ IY!M5=~ 0'l܀MvGt2aE~æEҵI%5]F<pENIi*ɩ $&ŕIkTWsc9YXv!?_YFk{P1 I c]rę^"4/N.~Kh.{=s1FJM+_]w~cŋe„ rwʰaL5Zྷ~[nL᪟]N"^0MGRNFO$&~.V ?AcK&NXwoҡadGP#er~77)΋@4N&HVbzi_ ;kaY89婧< c?.}r!rdҥ믿^^y馛dr%8!>.~@ ZЩ^/uRaˆK9jyZ,4>m6y[GM͡tL}dЛy'tx)KU {]y AJ/(A@ ho@>7Rn4i̞=[JKKQ_dٲe2esԩSMRbde8V.Էl|ij,,GpOV^i>:pl22'B!Gm,U+x _q>\e$I 6V J@㤣kOS/)?]5kg}f_}y'wtI1K@/4+ b&Ñb0 ԻO ߩ81$cz(#W-1aSt }7 ޝ*:׫(C ZZSl/ D䮪%+@Piq^ksQGGmVW#Y9TNJjaieАK5 Zv!]Cg1:xJQ#jA]2ZFTk23JQQ&|EhQ"@?c nnοo}['ȴiBg̙R^^n43f0!|X(Umҩp|ncJvlk#d6PT:̵q1i>甂aeK GiH|+' -4CnO #(-1 grNՀnv!J@cә$C|IyGe~ 6C8'#~aBuFć[@g^XLD2Q$䖭]: :lLܵ I&O^,#S;4[#Snn䳟VCJ@ÃcJztzȘϯ=ί3##ñ)^}U dfG@oh8% sI$'yG#j$=ᯙcRGMf*#kuM힇޶UV!> @yQ%R~FT0&k*q_/e(-n@uqp-Z#/h:Ȃ LD||IJﾀr@;{ڥy\'`>EcfAqJ&GPD>^ōg ֑7Lm_\WUxA`#>KW=wT(%1֗&_=0r?.5q&sRv sPFBPuscC$v8lB&vы@>#bɂmүłVZE7Ygc 7T@@ hcBA!ЅedӠ!az qNÐ_s:|.'s5hJ)3H&F ۃJ r}TT V}0b"40۲eJck%bʡUf:/arPYR'6WǕUrcPr~@-k0Svᅸkސ f k qmXaU=6yP'I^j( Pϻ>ez>aL10G@N9uL| :e[S#́s]V>4"SQe{% ~׺Z ㅶ;eE@p PjLUO* ,lC^'G} 7oeؽdIʎ y@O^,I6Bh#ZOJFm3ɧ)V0gwa39|`ME@@3ve44I)iO@E Ήh.0*e;Ӥ6BW2iGkFi}=L6[1ʳ#K$G5'-PnobUyKϕ| nQ@`3>J" jxt"0`P Jm@=+&2sd r`n R м|X2^lCљÇKLHrnpG2w'4Y +Ľi9OE 4Z*яS{hъ@!4:LFZ`ߊH,[U%{%Ќ & |ZY>w;/6Y:Hy)^yOS{ hMC*+łߗ?]E?x46\M&ݣ nFp"AOA@ӖП3VDpKƌSa^EfѷHC|D˧dfQrq|]^*ɟY9(>xlB0t~B,LW~~E+EC?{^ d۲et䦣U QeC|B#^mFT`'4HgmX+;䤑o7ɢ]r@A9qnVx{5%iC_6E[oTK KPPNE`@ M: p0cABǴ$t!;%rY)թRBLmHnOq29Aeoz\;""**aEE?{/X@" H9pjʥwI&LvMI/Mo~l晷_ $\䪫1eRrM9}G`(sC`.6MI NsN[+A q>lzZvIIr<$;@;h4h#㙋9 ЂZe4+sel-B3L9^= )mBSE`:}ؔ,4E P75/i+)I:Pj ۠mlӬMJD.$gIG0PL4MHvsHM9$<Abki-ZNPl z>J*@-~E-V>B-QѫWB%Av6 _ mCZ_m8ʨY&EQ쏷I+4я9S6􈤇y`MSP,ohTJ:GAB׺VI2s^vR#7uE@0hv1>ފE@٭x4kcĚ9(Isz6s@Agk{e7Q"jU$>EJ $)^a3 RQh @Za,A@ߑs/CJbA@Pm(KM+z9>h"`v߁MFfMʡTxCN+S8Ѐ&#`PEP%sJS`*5>^MI=tdB0hGfj- H4l3؁nTNX7zRb(!>؟})Ν;'C&̴#<"r WGQQfBzϹnM(co/ѶVxHs3Wy!Lxӽ'ƩpC4nFihUW]%]t4443<#{/2Dʝw)~p SE_po&ԍW/䔫0޽[ +| ",S)ZTNض?2 gp u oD؄i;lȖ!@69tWdP6)W?\8.c h(yGoEx!}NMji'rc*ޭTp,=KB@]ֆ  Ό իp b'[Ԋƣ Ru&!I?d$wAyR&1h.,!0Zh۴v':З]h?-umۅz$Mb[9qkKIodKrk?}b0ނ9++˰P.# ,X7@LYHH񃶚,,,CjR(sE5Ϙ!vwv:: WDį֓4!z:B)@.Esz"`A`Y hww\ `>uY ',??Ӊ'({ZWNbE`K e%@:`] xi^ Vy!$A:@h!!9IJ\ZwEFX:j*y;!W_}A&i&7i\5\3~G_Wl̔R˖1=SH!@ ANOehAρ>d#؞mf5L!^"0:1>/]iZ~s!@( Q|@L?M˻ ~x]n=D.b SMFW@&ITzsR*9PsZ$t?Pc:[1YeE@j38$Ό,=})H", NoABvi:%&:_('g6H]x6"w-|S?zrDz.F>{ s"./:Zr:0.ݤ,) []țA^NIch`RPɘD*aWXyC҄ӓG%&zъ@8"4^GVN"i.hkcP9=fl4c%I5'Xt["Ќ[(~*"( W3OaG#\i+LicQ/͊@"*cɂ{"/ |^r@"yH S 0R֠M@@mpMoot(a@/, q RkE@_+iЂMn2č-\C63|*i-h5TpG g >:Po%1W%r:}FI6y}-%M\]F?Ga .*DZcDë(@y"7J@{AxE}&A@:%D3S-%JЀ8u"jABE)sA@ \Ҷa@L|9~iQޣ mXNΤ$$I7D zpQdU> xT ӊdV8LY2H$g[ᗜDL ixX0كfZ<#RnUE Pַ_/~6N[rtGDf@'70#wbI^롁Z95W..V\kgP@wC#tdo|"p+E< I*'7 mj!I I$ f NAT ݦ(C@ ԞBxMeZ@׎\o<^ɰrie-ߦ9593 s%])R!U033ǨCZ"Tk#Y^@kA&r04x'#}=hAt=|د'ʈ-Ӱ|#Gm& Ш}sv|ss򗿔+VȕW^9m}04ow!}yg)ʂ0~TbzhF.< ʴ^*I8RQ0U*Z3u> -RQ!_ΫB /NV9TD>cS"^N×ดOmnn932䁵r DXXvs=Mw)EEEӶ놥GHu$X}r-qr/Hn7]dtBKιtng֊@x"4<^<lޥe%"/Xf,Ѐz S ŒIxUB<,y=rwO9mUU7yvٿʻn kjR/,Gϗ뮻N53 X[QQE`OGGP< Ҭxd>.nc udŐQEMҗZ;vHII|ߞv.O=Q,][~C2g"yE@P $}9 p[4F$ۈ;a/A-e%֟l11B1 !cw ك) h`J)' FŜCJР!' @䦛nK]]a63}VVARiVg駟6*S MsD@=s]`)-Mr{ci.0T/nw!W+hLqst(֝89>kG"jG]F;hA+s24H(%V4tYBЅt ke鲥fL0 1Ɣi,T ~e}.ɾGu@IDATXKN[RR+HyFLl㺻 2þ=˚Wwr5cl~Mo.v~rfdz uCHFh)Y3Nah#1$>偘h~sՏk^v!Bd\k$J@CE-&ajC:6&AŽ/^ }C9DZt>`A<)C>)J|\_4qvyp@F[!nI6>y&j7y7>?y (vМIMM)&G}tv@ / (g|?I*c@V@V %ڧe8>"(VZeE6`V0^ Eւpr˸Q Zڛ5Ft? /q OzQ3S% e R ?Ѧ&q55BٳXCW43!},i}#(3A= (߿/?qo+g}\tE[Vӟdo1x9VxIR>N<.<'=pQɅ"u84^zq";J@}J[*47ɬǔHD}LWDfgav˖&L|Cal JFkKng WaCr\,SS snGT(&rv#9ޭ[ )et#]6}<kž+$i7ɧ/DMO_fD㉞-pMnѨzk?i\5 jL >fI߬V̙]ˣ1Àsnn5yu" <p~G?7|ot=Z WoQ>я*]}*3!@3*X[HT948i/Y-G>]7%)ie:ڬy*'O:<ÉPɈ_hם{^WcU,Y@>PZSi!~- c7*SdAV4YF:pY'B;۴iQꫯj\]@}:>E @`K$3|7^ *'zxEVb?֮dOK^hU<%s BH~ zARt;V$\[ >RA:8sf!k׮reׯ7\|01 ^)gm]]]{wmcco~c67,AL$+_Xژ-Uzn@Lhrl%@QKJL]q#61jDBCErGJlioz{VS = ^gW^F=?6FE`4^*͡+m5嗿yK7r$SHH($x̺AJSXPiρL\P$ }1СCFa ۶mўHHMa/~Fn?-\f'0wR+s(C(y|Y5f޽vgutI'ӜZΗrɔ0ßن qƦ5xsg^-iR5X9xaQUϙL8z#] _$"oF%l >2$zp~ #+Ye$o٣ 4-o14,̪pv+$$}#]J> 7#~q4ݩ44QIm(\OhΠ&o#wV Eȃ>hlCX^@h')Dm+#蹏務$MozZ (5|LBb׵|ߖrٱcoyl|Ycub\|llLnMُ<'lьg^'4C)Rҙ$$FECDobH)ٟp?07-z89M_<hVQg_k˜f3-cXk,{&lګʘX>ԧ&NgMGbV}ʇ>!}Mm(I%}8In#4SyG)sS3Jj EM'3nql~d x@@bSC1+I'ᶯ~n:cj=Tk~=s7rrdxC̱?qD!!KSqRjoc]g8䲛ϸ}GM4Q(K~g.vyk5c\y#o257 a?D}@bt'_?p2#3x&?oDڅy1 L/Q6DJL>9!L1s$zYR|D|VWc19 hc80y3m8-[$1Ԍ~__fE_c1>HggKD#QYDj ?ngQGeTj&}Vm Bm) ? >ZO}gQF1}㏟(֏=Lp9L@B{a$t;^KHz%r\zM mA~HeaND'MK$F̭9R:?C" 393㼠N`E o6&ElnV,泾PPCyWL4WRRŐ.T.q 5۷o7RDGkJ ]1܅j@`OwrYF:;H&( yanYa1%Q8rcCWn2PkdF&ss+F>}E%&:_2KֆSSd)ȧ9pNM}iiiȧt) (Aa& d cռ.+[YQ+[d`;Z"I<;LB@HDz"ۯ*/chv?'>8ܧ6T|@4] InqIPm(a0Kf"\^}Uد~+#%GڞG'|=׾数ڏ Zm&;gx|6[DӍsSbuxD"ix*ϓ&8| IdDOL8*R#PO@D@RcS ǻnf֗e.:G3؈tV5b@73i=h7Ardwf4y YBfccNͲS:">. \{MCj8>E d666dfeN0:gsotFCr!ցZ{ HvlY-$Q5})-AJ Rr|m56LjܾMUQ 7HAdHTr="TL@7l`hf:滢 WEFzPpvD"Kry_% e8ǥrqd K dgG4N̫q H LApUeDY Peʇ0~p@gz-q3H?ր}G[okܼyHcCEL B-Rxѻ>j:':-0(fx&7 YZSXD@8ñyӻAR۞7\ TF fb5/+AO7pQGM9|L^~嗛u,p n 7'J=6_ j(>A.PRltwN3;9D6)51cRg}OӾK(B8I0z>#XdA,܋vxy%z7QiFTżclLMWlDнۅ~+'4J>!Pg<ϫ#3 S?oTzfE@t|"?OZrRԈ 3 񹼑©MO׏Oxk: Tk CY"9ЀfQO֟FŰ6ȧ>ݩ(@;JFðTXGgZ^^./<+#]>\V" |tfX2h-Pvu0wbas cĶf+ˍdѰu};{1KOٶ\+oF0s=gSkJ^^_I@ Pr+lT0JINrH4%/XN'RLCE slȱ(@II|Nc64K->hTPKvy׌}#Z!./Ph yXs&0aJ|:zL0bzvm,uE|@ZK^5v/g56H (>>#Kq_c5!Y+R_zųg>- Arjw_x["w|SEQ3>[R7;ߑK.D7xhAqіҦ_HRQQk@U f+dժUӟp#qM^|Ey'7є~m&vB!` NHߗ}" s?j͚5mdggIu+~CiLSY=u#P0+ "2.LI,k Цon$Olv^6(ˍ@,Seɖ{}oQ~i#~YD>O$t/? 'u_g;T!]wݴQ_|H+=4]/ >]j́vTȇ.~ouE`8Pry1': (!˗\X`TK08GO$]zٍ G`9ۙiTB>YˠF^?uXG}{}MnfIgd׮]ַu~pZn۶MJKKG̜oe2O @p64QAJl4݅$v}dQDM<_dkk@B_8,S% DՔa|N{ez#fS+˂@sxagYv?fk(4\ʣ>*wut~UWYw¬zC>Sj7V/Fjp ݺ, vE˔~czؖ\UUUBʬSYeѺRF@i{"-C.X!ZQZIYZ*@)nQu g''QVw_ϔ!3|-c+N|xԩ2i)!~MɒxB^.rܿ=1rl[OATp ޑ#G& IUy?id,_^N/**7Nۯ@`Fj믿.Lj|[RN.3'F5(foW;AH+-+M[F&#[?7kc TKpabdi/BjzNu'VGF]Rz@ Cxb_}2q}C/3ӧ_RI (G$jz?7C3wtSx?mY҈:!Җى dРljm^hA\uu;I\K"m@4d0ujiDů}n7n\ '8 Ђ>3|;Y#[1.j<\e| H*˅Ui8Q233嗿r)FC93qB_vĺ.&og`,F4nanĔ]]% cGIdAIЈTH-їVI|E͍ GhmDY+Q3 A|.X UKg 1LN-60el _aIDR}E`9G0`Kb}-XB圽s=FDWbz${2r}% kUkqV*J@|C](-ErLY8 Dt?WK#7fdɶL9[6"RI?5ʓ/ Ƕō`Bi kFjeU-4/lDWX/ IUdU#vˌ *A$sMapVیIL [M@Z&>}6"m,/<|vjJ@l>,]2?>ew|# OQztf?)jJ[[0wYYY[l̽3 cb5ȺR tH74MMR䔮Y <'$r*|Pmtz8Q e4ʆ2 2YB'FoG"h^Cs0h|)V>5$Ix>U~;arp+dyWuz?hrGOh.L˃>({ǁf!}LD,5gμi&a$Fq"dĜn+++==u2?eǭ*rKXjjj\#wqގh aOK/8OBݏ; $GwFB4(e=xɛ!rwwy~FNrM7_z^z?<&v?ƪ}Eq: G++sse%>.#"-])gtFAhPX>dcdtg& ()COѦv$.3 KQŨ~]XCK$/oذaF%\2eo~a#ZBs0Rê+կ~՘JiT2" ݯh(K_g'{j unM!1ݲeD1w?~q?D (}Z<ci+5.F|ς}AU|9~ l} `>)=(*^S -fݞ)6ߕ|V Y$tƕ=S'V(HR[ZZ$(d@:oLضB*=Xk}~9~¨&qo>Jܹyr\zC#0kaU.4d#_-O%qG*T驭m5RMm/E(A)i[X99,x#Mw00., vq|pt};>~x;p~{L_=:??L].Q oQ7دΒ]]CXY.ix\ |/F>zVi=N>}3c Ź;̢-ղH:qEy-'OIwJ<}(قHyJx_z\frb |Hh$dBeYNf*uشf_:W!"=X7hͅ+KW\aT:3$|6?c~曍LJ[īBK]`<'>ј@V fq_"Qh|\ NTDr) ]CW47Q; !ݔd$FHRנ}b0RE UH1GEksE,D ^ڇ"P Z^^>Sm6?s*KD,+RzS.b.A=~Iy<A0P엕m-LBL2L"g2mBqtR`%FYV!],]"0&y!]^񔭺(&+9|"ԈҚLaeիWҊ yꩧozFIjE-)K@+NQR@=+d!c/'e II|) ƹx1j畂<9Go1C.Pd{.j@S' &[OJWy#2렕/"LLCG`;St2G#~?eR]](tQ`N6'Q*wɣHkJNEm|n9"zzVU`䋗 N_%pt'~g[m_3>Fa?5ZYeƙً!P{>/9Pdz=G+"(NS;_K/tݺu!j_ TeE}zQ.rI͍ č/?!1 B6WSDMdgSau/Je;Rq2*i=A5dhwF@ OqOK`2CPVEP1w۔N;ЀQSX$?[!c˓e<+΂ҍDv1Hfs**F~4NV9 u)s#*=x2V3< f EZ:nOžnK j9n h["&ViB0_Ls)"A 5 hDXF^.znzu54ODۉjAJIKв"(0=_Ym{ߝ&^2fx{iΪ(cB$\",%BҒ$AVQE(7ߒ#@ih=qfj== ڌ ɾCzK Rj }W. u|@?6?K?b)05K'#KEPg׮!~ ҍ('A4$N:Sqr;F= uI<;fs_;p ϯو&DA J Ma~<;AB?BVLap:-.;^LːL#5ҴIBT,O{ȟʕF'( y.$ys7!2?( "l~w X]W&^vOPh5 )#r\P技й"FbQ ͨOc bs&q#Q NM^ ܄$޻ &x֙UXT?7уa!  $S "d(d8S^"%N |HҶAH( _`O9! y9wgJrZZtR98?B:cb1I)y]+?fx+B:&E`>@wNi (\P:mP"@viJ34ܜՓl\2jEFxL"<*PjGbymOiyOalxCR_7E TE@Xl/b# '| FFD{cJnC@by>| ?U*\tL\uHnT p$"esE`*XƇK==mN]SE`Pjjh-EKB(8FRn26;It/D~ y=;רMozl=cKhAcעM>NKucTDB!Јe_[QU oi+E@XZzzl" w)L4& ۘ\~a^PL<:y %:](9SzC:iDUXkfxe~P31VE~bEEkJ,w^;"%sL|υ&D/s땾D5(U@m+dGF+؄^;aOTWwd4|EQE3< aZ, KOBOqR,!tWRF@ h` p4A߼"qŸӛNxt{Bh\;aJ߁$)YקZR˔N#(j`h2S12œ#b,ת̄x |d;/ݧ(()m %k$݈0ߝ_ ߩ?}#bZԧAc:cj&Rrh1MRa''I)L:nv@&#,f;+V*̔ m\RYeE@P技й"C֘?fBj27Gy$&p l60Ϡ\m!pV3$Ae-qڏH1 `t"EDEPB@ R!  }/gb„>0LrHn$?Q\:kjrѿ~zÈV6b2exP VӄI^34Y9Çu"(F@ 輡C1_M4kmY9MSjN: ABY}S3uuoR9 l2Q*DyGiϰ6 \v>uY0ʞnKL<;*",J@ i=O qr)Y }P* o!V?49Q1p~}5=r#Pg%]64*",%Wg)s ̫yEhx?7w7OQ5i$hA4q$CCzO|MM)3=„I6l U0ck"%~T; XsD +!ۡi/eA׹5toDK?YxEg^= -(Y ]O*q-pG U+ˉD_-eỲg҂Dc\܊RedIsm)i _%JaQ%d4{@Td4 L P튐IJ2XE@3agppP vK] V}opȝѱIޭqAU +k.vgڦLk`T׬n ($`n/)TIDwהc2qp4YUǟUXc bNO(_ ׁ0%o- EgdqQQ-I8dIH`.U&nBO \x` M:񁳯@6|Q$i=dj ABlY!v@zSlR$"9IhVLǠ`$הzTqn] <o@Yڸ{UBȨB c`ᤢ)=& U:/joiGzLЂI H?0=[(nQ0f>7iZe1 J)MIgopDQ0L#z͊"<(]A#I= 4 /zT!Mc+J5WSXj3BMO[yz1?4}~Ҏ ^-d+ /$jE`9P빃SfPORzQpkΛl!02ݒ)<+ fL3203٣C x֣A,("\(].A b ;f(ɜy>sUfi;Ju rٺǒڳBU%6O }:+Nb?&}07@ij0#z:f7r? <$85Ҕ,!qEz"( ;_v @z1BH o}q|ṗK ?Ε sA1үB]yO±:iϡT6bv<#=ڋ@xCd'k,Niz?584 ZKr(@ 0.3@*$rx f-͓%5Bd{T|;}R76_@VjiD9 zDR Wo&FDB #+p he!Fg~/.A+>QzPu+ xŸuIIbzVڧ˦: 7=i" .DCy8(l㽌;X<+q.?(GAb93>F##tL*",'J@}=w 1 /9mhiAۢhA鋐TIQD# Z^?]= %e%ھbd[$0ÿeWb[X#UT#po+Nm. [+",,1Vt5+%e%Y>;̹/VR. 0'74䖾M=>PrA"[R$7>nbųkpYNh5Ij2j"Hm21$:KU+f(#tv"% ZD"#fMt7sFGW9 DGMȯeDGja 61ɥ_jA @6iI\]hWs ::fɶˁ +l h#4c7jco W؅D5TSO-_iDjQrq?H]YJxqܥ@_̂/c}z!H+M0BA҄*! ڍl ‰hgjTQQ%Y*CSc ا(W: A`=w8Vq`y<ƺybمHvD G\ ~z)K9$0Lg7K h)4M1HI{ܢ{b H5| CgSd1H- )MiT10 @8d@[dp #pz4#efsf[܎ɜsٚm>E@@U~ E(H;)_W<$O0{{T)~'L ZdzX͗+Ey/~"Q+َ # Rmr3 /nA2|cΔZt}(aD SXE@ʡI)&N$+m\t s@6{g2z(ivId؛dc%ud"N( ׺S<5vl!<$1Z%8xܫ,d@MMl.vGEG(@;:@IB#0|As3,eZS|,?[ AzrK8'FhҺD`FśR{_\tBYytT"0 (tAX<NB$OIw+u= }7]vyf5މJ+X!C $C Ф@@̺4Ӈutt[zQg!IE5wBϨ(sC@ ֊ <ڃ/(;-WtfrN$QZR2+awä#ngPք,Ȩx:ܙz}>K H:ߊNr-=WQE PwH20WbiBnPOpuX A6($e;4M.BzJL1Y B%Q6 \)(Bp(dAPQE PwH20&xZPvQ :S{Mit!74.RWz"DH(Kr1}Na #ϠPe^DEUeXAB|(@0 41d8Z8ANFo5A>$AA{W*OhHʨs:NB7ғ0hCVC;ۆ6ОP&oo<㪯4~U޻dU.!1:$ lB ,8YH!rB L1q^,YU-Y]o̽g{Ϛ-j!;gTƒ]CR Y˜hU (%0*@MWQ%DtGHMvU1r ($%UJJ&Bayأg-<1vP/!l˜vafʫ'ԕg>`+Z4HYZAB1j5%eٲe׶mۜ%/[lqN>p| \FM )~v%‹W oqelD_/İS-Wc ĄCdGFH#<2=u1]% IKc Bbw[ڿi ALQ6Wm4ZnD]ģ %X~lgg}V^uZ|YDzuV4i\zrug-%%%駟ʫjZK /wi}3d|^=  Dtx}uL͗. Ʉ)bIb r"I#$8Qt$npn5 a=;9Y&V$Nh:Q~t)мןgS*\ 9bfoC&\!>C]M (%k*@3K mWTTȒ%KSNliX&NhxKj۷Oveo5mԩ`5/ѿk!b?~hm"!ݔ^rTH)U%%ɼ|9dnm;eDU`=ǝHhS1axz ̈́a-=P)q)21>Nb8xS`yn'}z~r_g.Sxx8HBOxK|0;!\avD9Ϟ9]eƏMojiieq{\MlL-~pbܬ|䝂=ЬCC9GA?~{0} 0ng0£\lCCZy8 \bѝm}rs# @TON7p?C]j 񗁇R:?7CQ,TO!#ym2ψd)uɀ݅Xv DS)RP%ߝ>`vMg&ZWp!$ zgs9lC 6~ uP<|<Ĺ!-++304HǚCYYYikڵΣLw܆2DtYןO 8jU!e pa(o[eN0Uz!3W̄4 uG3=8Dls^?56[0&|xS)ax`؊ K60孷2f|(E*_ӧO޽{MZJ;cF<=a4sG;@GJ)6S h ˔ǥq#8D6#fcK4p 4#&6$H\bǞr;c_V'j;B.g B&&!h(>GaAPMB n0b{,D/]wes.Ϭ$$b_WA> EaHݩrB{2)>ݼ+4fl6b&[d"{g@L@R4ְTSTs 7[Č B\v JQRxX;/ Db%pn,Ϙ?aPf3f'Y<5H 5,mj9C뢦^xW˕W^i]cI(,_~e0}\sΑs!zƠW\)lܸє"ުy}.pn͢ b4@JP/C`)][X.c3)PV'[b5AhC޵7 ߳[20/c/hDh&q)aC,WX (bbdSq]!; M]'kP9DOIXvƈWj# ZԔPBtŧ5i[!."yO:J< ~̞=@2GTBtXֈXU񉒋T3.dDJ(FːXC&{rp K*eu FmX؉=黰l;-eJB2Q34^ě^͈k,9\465Uf>CP ص>hFC~{L< 9xYv3֪@,LdPRl @1J*=|g&\fa'[6b!|nKu%] (O'(2{neꪫL7ui0K3 B7٘Hڈ$!CJ b>Y@"_P/i؞vFKfM!% JzI, HxC)T8N!Cf8bD!]#pX ^Լv0eЉ8FZ Ǝ+W\qnnO3#<{jI:+GV{ h?==Uƺ+ CTxgQ6P;A1 af gPJ Pw"~Ib%Wc[; &?.EEEtSOɞ={d&>ۚ7ol޼leĭjΘ1˰7kF`4T0nGPQ7, I=vf;m1Γ @L$cC rX>B)"2/r2>Ɗ_B@mWsaH9g2]  (,d|l#)%^v/rtn1}[gR/ 0V&ivtIF8@jxxdkjĨ2ra[Kb$}ˏ |OmiAs~D OQ /:/0=4φxO'z$A;]ZU )%xT5/%''RT.^؈V.ʙgibF7-P~d,'|bc1˲K0 LUy^['s52:z+!!^]һZ)X#tJ;YhxØHD8Rw4IGu =Sl$ gXSV LIJwZ&/d;O% ['""f'Hb8m}T 0Ԕ*@Zv{&*///gWo6m4d35k֘bo63Y }#@ʥ^*%%%#!|Ժ'PLr З=Hrэh#:ݭ".=RSRWs~9K `> DT2 "2!̄Qbؘ/ uW5xO(-$ cM|q9tv259>x}\q_dz2z 9tIV& ӘLg%\1!K=QyJ{Tz)>i rLq5~+Eu56;uC`:`mks~`JL ̏3|Yց M'7NH[ ;(ȡDI$ &?z1١q*SՂUd2V"ӿ)iV暴Cv`Ȇ;,_rX3믦@|пti"@2g;/(?ig\%E吻ej`}r5̙39s昒O)j(>_/(wZ me6NGqB2oMaPxkctn?C&V(ҥKMRs=gVǔE{1g'+uGiSպCFu%.h+PyN λA30)>\$-aЍi2e&x$Y[S'e(.iBi4kO P~BWvrי(#8C< ̚5$m۶ c:`o:vzw}%~X8oPN3N9wKX;vczhpa7 /퇀i';s ޷'0<(G,"'m9ZP.KP~P1hӉXz[O)%p%R/P@Ն½{Jvvv;t9Wf?šezv-_q؞ݗԺhk(Yd .)MDWj3r5l,nc:m1, s2MKHu)OjdrLDZdyx8݊VJN?+%@ t~ty! aSPPE|v%PaW1ދȉ/SM=d w{A mU^Ip ȸhټINJNN OUw%8R*@H _CQ-j1L)t?ZŁtW;viYf)ݍem gee/ߕPJ@ 1tJ p 0sc>!>-Z9ĂV{cO^PSb33NS]avNlWgeKۊRc]ι~PJ@ (%pT<]U A&>}N{c;C(tqvL@GB[DV|'".AjڶjLM,xoՔPJ@ ERl|Sd#U;M.#U;B1og:vP,^vAP|PJ@ ( t0(6  cDZDHE5= چVN.l:݉2L˔A.FvИr#X^M (%8_#<]] #d+|v#NT2,&1fp5;믭t%§0;MѲQ[#efN/J@ (%I@h?J7U|5wRo۳S.FvBy9=bmZqth*#z~xTi2;X'ghWlwT:M (%=\tr$S Y|Za}_<9ZǼH&Y_ɡ́mO͐Rm2",Pf׫)%߲lGQO`BΕ!$їit,Prpkij!u|GȊłrVxV)% Ҷ_rTy\<2uӔPJ@ P ؋!3GJ#}LG11W#;Iu^՗6)G :zV ӿ%_V27+ZjJ@ (%C@hhJ yCԭ}(U3b0&*&NAvk Ҿi)&jO֊=s Q\,_,&' [|)%+}%)0nRtxH|Z022B dkqL=Y&3}1MxeY#d%%d:Zɕ~VJ@ (펌NWX֚!.<`#\)qqDsXN6 ¶/G_;jGD«A&|RD,c5%P=PlcGȾ 5MѤѽh&O8KcZ9IAml=er]q獒Y⨫eKҲR9 cslg%\*@@++[zv 4&"x{ +5}r%}N%qb8ւ%+E:6{e4յUrSGxCc唀PJ;Tz zHJJyT">}pIG湍Q[km~ -@#{evHhMr/CY11M]9:xeˈfb\[ڠde+{Is}`Qq8eO $&j=\Nmoq-H`+QԔJ|c=ݰ<֦Xy+-c@J×@UsךhȔ tx\= /h/mԮ 9e,t (4)!^^ 㪜<9n.kn;#mxN?NE`6vcAz}̙Ku(_]jOu; h!@fǮ&f@CxwpG83MwW_s4JM w FVےPɆ1f}YٹCF:&OGᧆH;J*-;eNptt=Fm… ]'V_Cy?< =KUNkBzNO4Y|EMY0=5~Lr*-(V'G&1.^/}_wL`m}?C:TߵUjoÛ@ɡ4gGM#sz[L+%0F+* LpPt8~}3ߛ-OO 1S+%@P8ZCKJ1C{nb{V 1i^89jJ@ (% x3X>>|qTD#5%PE@`<٩)B %St(Vvj,,+USJ@ (%pT)A]? #O룠.M l #sm:'yǺPJ@ ~wI@Ex/Βv}bZz!jNs1_˲|9ٟuY%p=Wp8zJ;n{ԏ!=KTP]'E)ETI^E돚PJ@ (펌NWȈ $:4%|o2KGUȆn:Bvˈ4*Ir wP'uLp?۫Mp\n>80jmqGƤ +Me$JHG+%@P^OND|RNLYm Du(5>Br$ 4IZ-¼ vgt|@q>Tԣޠ)Jg;6IfeA_J7Z%&@%*F DAͿTjҳQ Y]YrU^DGIY (ą)%  M'3RdJ,IȌOCwIf='NT2,i,!6L~t&Iy3J@ (%00*@MC1vNqq^O˚ZW" aeU|^U%ZӎNSJ@ (PwV`w<:&ZQ`>0"=w1d: 08Y; ]Z (% Pz& ĄxO K|>:@552xC\S{%PJ+H.OI1fttb|EsMPJ Pw"$9 3?"Br2CwvRsRe#xd#Ǫ[PJ@ =~)+S 2#51T4A&#*vJvǺu%I*@}A@4eSQ2|N3qj#J6}=(_uՔPA1IDATJ@ /-[dϞ=2uTIII +hask! `st:Mj-8 |+-xBoiRxICB"N6C{v5d G 6Ș1c䩧'xBrssr)AN6%Rxgx 44LŊawTOh ݽ{|ꫯ^zI^x;0Cd7#YM2-jyߛ=*ʨ)%?>˾sN8q3C ,0ގY7G#/^gҷ///< qfқg,Gkx=y.u%g}O[NNW }pV[[+xwc`˕mzh[}()((.l_f7d'c;pRSS+33jNʗ&MӨ>钽,—̈OoHrss_OQ+ 4.:{yΈb CFOTWW 7 /V{뮓2?8;=@$P\\,_%ӟz@ڝ_WE?xy衇Jcc$KJJs~[[ٳGܧ^ͽ#Lw>QXS|0==OTM *@˕qIKKqCum'|"?ME)o\}r'nA<3irI'G:s|{ve<7'8PCFtG7,?MՔ ΁^z GxrH%\b33}s+&!Y$YNwZя~dӭMMMi{ǎѻۚ%//K {Ν;W^{5#<,Yb+% 'zYh*{P%cE)OY4%-tpzޗ|͘1C|MsH221[}n-JTz xx)>9!W(c8'p|WH$fd#̏wiKO(?d%5%),+??FDr>33f$&&ʄ 7LVb|(i&l:į~+袋L'Ք0qnԩrW=|dyu֙w&(1fy֭fs=:ݯ#CvTxɓ1 HǗu@Wj9992k,| ʒ c&Yƕ2?̈Gg5AI\M x9b,2Hx2d^P5\#_$xLLz/bOG t"wr5NG_Z6md߱c:vw[w%0)_Õ10p=""™!lw|f& y.az>VE+ڨ)oC&oS|Xh l 9}nH@Sx蘬=:vg7Y)I`4ϣ;S$7~Qrz+ <t]=%P} 93~߮s6(P5c%PJ@ & gPJ@ (P5c%PJ@ &MB gK12bwv%b@3vaך[oYˑ}qLM (%h44Ю"lfښ;ՁRX:|GKBooM{vŋ;YBfĪsO;ãHHHppߴs9ǁ_N ]<8K/u@@?sII97+6LPJOh_>VI)EC̊5N^C&-I2i$МOMMR`05Dro`k2u~zeвf͓͛7˚5kQEdΜ9ƃkM`[D[vZ6uT:߭s8䓝zPJ ?^U='%0aT2;a﨨( v(0P e <5I8 M("wN ܦ1՘xL@>8۱c,]Tq{p'c.)vϤ% D7{2z:ovhb1,,XjʲEY~(r())t-K(B_z%sݦ.}4GǦOOeɒ%&^͟&g~򓟘vqJ~{@l'4 LƧx9sIb"P1d!߿N& 1ACg<)_1c?ްbŀ #)ՔPF@]Q=%Ed5k=)_GE! /&eff dȑO8]\H-zD7nhr裏$66֔a{׵3Ɲ>CH!xRf3۝I˘M>Jz>SУJJjGUydee9\?WVV* ^5%RJ`s'ϖ1XO7񜌳dl(ho볟tWyXu@>s_@:J@ tX7z&wd$ff9LP'Cgk(%DĚjJ@ (%]*@_PJ@ (#CwPJ@ (%]*@_PJ@ (#4.PJ@ (%K@wޕPJ@ (%pT%VJ@ (%w ?>J5S9IENDB`ggalluvial/man/alluvial-data.Rd0000644000176200001440000002010215000311045016143 0ustar liggesusers% Generated by roxygen2: do not edit by hand % Please edit documentation in R/alluvial-data.r \name{alluvial-data} \alias{alluvial-data} \alias{is_lodes_form} \alias{is_alluvia_form} \alias{to_lodes_form} \alias{to_alluvia_form} \title{Check for alluvial structure and convert between alluvial formats} \usage{ is_lodes_form( data, key, value, id, weight = NULL, site = NULL, logical = TRUE, silent = FALSE ) is_alluvia_form( data, ..., axes = NULL, weight = NULL, logical = TRUE, silent = FALSE ) to_lodes_form( data, ..., axes = NULL, key = "x", value = "stratum", id = "alluvium", diffuse = FALSE, discern = FALSE ) to_alluvia_form(data, key, value, id, distill = FALSE) } \arguments{ \item{data}{A data frame.} \item{key, value, id}{In \code{to_lodes_form}, handled as in \code{\link[tidyr:gather]{tidyr::gather()}} and used to name the new axis (key), stratum (value), and alluvium (identifying) variables. In \code{to_alluvia_form}, handled as in \code{\link[tidyr:spread]{tidyr::spread()}} and used to identify the fields of \code{data} to be used as the axis (key), stratum (value), and alluvium (identifying) variables.} \item{weight}{Optional field of \code{data}, handled using \code{\link[rlang:topic-defuse]{rlang::enquo()}}, to be used as heights or depths of the alluvia or lodes.} \item{site}{Optional vector of fields of \code{data}, handled using \code{\link[rlang:topic-defuse]{rlang::enquos()}}, to be used to group rows before testing for duplicate and missing id-axis pairings. Variables intended for faceting should be passed to \code{site}.} \item{logical}{Defunct. Whether to return a logical value or a character string indicating the type of alluvial structure ("none", "lodes", or "alluvia").} \item{silent}{Whether to print messages.} \item{...}{Used in \code{is_alluvia_form} and \code{to_lodes_form} as in \code{\link[dplyr:select]{dplyr::select()}} to determine axis variables, as an alternative to \code{axes}. Ignored when \code{axes} is provided.} \item{axes}{In \verb{*_alluvia_form}, handled as in \code{\link[dplyr:select]{dplyr::select()}} and used to identify the field(s) of \code{data} to be used as axes.} \item{diffuse}{Fields of \code{data}, handled using \code{\link[tidyselect:vars_select]{tidyselect::vars_select()}}, to merge into the reshapen data by \code{id}. They must be a subset of the axis variables. Alternatively, a logical value indicating whether to merge all (\code{TRUE}) or none (\code{FALSE}) of the axis variables.} \item{discern}{Logical value indicating whether to suffix values of the variables used as axes that appear at more than one variable in order to distinguish their factor levels. This forces the levels of the combined factor variable \code{value} to be in the order of the axes.} \item{distill}{A logical value indicating whether to include variables, other than those passed to \code{key} and \code{value}, that vary within values of \code{id}. Alternatively, a function (or its name) to be used to distill each such variable to a single value. In addition to existing functions, \code{distill} accepts the character values \code{"first"} (used if \code{distill} is \code{TRUE}), \code{"last"}, and \code{"most"} (which returns the first modal value).} } \description{ Alluvial plots consist of multiple horizontally-distributed columns (axes) representing factor variables, vertical divisions (strata) of these axes representing these variables' values; and splines (alluvial flows) connecting vertical subdivisions (lodes) within strata of adjacent axes representing subsets or amounts of observations that take the corresponding values of the corresponding variables. This function checks a data frame for either of two types of alluvial structure: } \details{ \itemize{ \item One row per \strong{lode}, wherein each row encodes a subset or amount of observations having a specific profile of axis values, a \code{key} field encodes the axis, a \code{value} field encodes the value within each axis, and a \code{id} column identifies multiple lodes corresponding to the same subset or amount of observations. \code{is_lodes_form} tests for this structure. \item One row per \strong{alluvium}, wherein each row encodes a subset or amount of observations having a specific profile of axis values and a set \code{axes} of fields encodes its values at each axis variable. \code{is_alluvia_form} tests for this structure. } \code{to_lodes_form} takes a data frame with several designated variables to be used as axes in an alluvial plot, and reshapes the data frame so that the axis variable names constitute a new factor variable and their values comprise another. Other variables' values will be repeated, and a row-grouping variable can be introduced. This function invokes \code{\link[tidyr:gather]{tidyr::gather()}}. \code{to_alluvia_form} takes a data frame with axis and axis value variables to be used in an alluvial plot, and reshape the data frame so that the axes constitute separate variables whose values are given by the value variable. This function invokes \code{\link[tidyr:spread]{tidyr::spread()}}. } \examples{ # Titanic data in alluvia format titanic_alluvia <- as.data.frame(Titanic) head(titanic_alluvia) is_alluvia_form(titanic_alluvia, weight = "Freq") # Titanic data in lodes format titanic_lodes <- to_lodes_form(titanic_alluvia, key = "x", value = "stratum", id = "alluvium", axes = 1:4) head(titanic_lodes) is_lodes_form(titanic_lodes, key = "x", value = "stratum", id = "alluvium", weight = "Freq") # again in lodes format, this time diffusing the `Class` variable titanic_lodes2 <- to_lodes_form(titanic_alluvia, key = variable, value = value, id = cohort, 1:3, diffuse = Class) head(titanic_lodes2) is_lodes_form(titanic_lodes2, key = variable, value = value, id = cohort, weight = Freq) # use `site` to separate data before lode testing is_lodes_form(titanic_lodes2, key = variable, value = value, id = Class, weight = Freq) is_lodes_form(titanic_lodes2, key = variable, value = value, id = Class, weight = Freq, site = cohort) # curriculum data in lodes format data(majors) head(majors) is_lodes_form(majors, key = "semester", value = "curriculum", id = "student") # curriculum data in alluvia format majors_alluvia <- to_alluvia_form(majors, key = "semester", value = "curriculum", id = "student") head(majors_alluvia) is_alluvia_form(majors_alluvia, tidyselect::starts_with("CURR")) # distill variables that vary within `id` values set.seed(1) majors$hypo_grade <- LETTERS[sample(5, size = nrow(majors), replace = TRUE)] majors_alluvia2 <- to_alluvia_form(majors, key = "semester", value = "curriculum", id = "student", distill = "most") head(majors_alluvia2) # options to distinguish strata at different axes gg <- ggplot(majors_alluvia, aes(axis1 = CURR1, axis2 = CURR7, axis3 = CURR13)) gg + geom_alluvium(aes(fill = as.factor(student)), width = 2/5, discern = TRUE) + geom_stratum(width = 2/5, discern = TRUE) + geom_text(stat = "stratum", discern = TRUE, aes(label = after_stat(stratum))) gg + geom_alluvium(aes(fill = as.factor(student)), width = 2/5, discern = FALSE) + geom_stratum(width = 2/5, discern = FALSE) + geom_text(stat = "stratum", discern = FALSE, aes(label = after_stat(stratum))) # warning when inappropriate ggplot(majors[majors$semester \%in\% paste0("CURR", c(1, 7, 13)), ], aes(x = semester, stratum = curriculum, alluvium = student, label = curriculum)) + geom_alluvium(aes(fill = as.factor(student)), width = 2/5, discern = TRUE) + geom_stratum(width = 2/5, discern = TRUE) + geom_text(stat = "stratum", discern = TRUE) } \seealso{ Other alluvial data manipulation: \code{\link{self-adjoin}} } \concept{alluvial data manipulation} ggalluvial/DESCRIPTION0000644000176200001440000000343315146573312014121 0ustar liggesusersPackage: ggalluvial Type: Package Title: Alluvial Plots in 'ggplot2' Version: 0.12.6 Authors@R: c( person(given = "Jason Cory", family = "Brunson", role = c("aut", "cre"), email = "cornelioid@gmail.com"), person(given = "Quentin D.", family = "Read", role = 'aut')) Maintainer: Jason Cory Brunson Description: Alluvial plots use variable-width ribbons and stacked bar plots to represent multi-dimensional or repeated-measures data with categorical or ordinal variables; see Riehmann, Hanfler, and Froehlich (2005) and Rosvall and Bergstrom (2010) . Alluvial plots are statistical graphics in the sense of Wilkinson (2006) ; they share elements with Sankey diagrams and parallel sets plots but are uniquely determined from the data and a small set of parameters. This package extends Wickham's (2010) layered grammar of graphics to generate alluvial plots from tidy data. Depends: R (>= 3.6), ggplot2 (>= 2.2) Imports: stats, dplyr (>= 0.7), tidyr (>= 0.7), lazyeval, rlang, tidyselect Suggests: grid, alluvial, testthat, knitr, rmarkdown, babynames, sessioninfo, ggrepel, shiny (>= 1.4.0.2), htmltools, sp (>= 1.4-0), ggfittext (>= 0.6), vdiffr (>= 0.2) License: GPL-3 LazyData: true URL: http://corybrunson.github.io/ggalluvial/ BugReports: https://github.com/corybrunson/ggalluvial/issues VignetteBuilder: knitr RoxygenNote: 7.2.3 Encoding: UTF-8 NeedsCompilation: no Packaged: 2026-02-22 11:56:03 UTC; jasoncorybrunson Author: Jason Cory Brunson [aut, cre], Quentin D. Read [aut] Repository: CRAN Date/Publication: 2026-02-22 12:30:02 UTC