discontinue defunct params + add examples with negative y values

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: ggalluvial
 Type: Package
 Title: Alluvial Plots in 'ggplot2'
-Version: 0.11.0
+Version: 0.11.0.0001
 Date: 2019-11-25
 Authors@R: person('Jason Cory', 'Brunson', email = 'cornelioid@gmail.com',
     role = c('aut', 'cre'))

NEWS.md

@@ -9,6 +9,7 @@
 - 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
 

R/alluvial-data.r

@@ -35,7 +35,7 @@
 #' @import tidyselect
 #' @family alluvial data manipulation
 #' @param data A data frame.
-#' @param logical Deprecated. Whether to return a logical value or a character
+#' @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.
@@ -100,10 +100,6 @@ is_lodes_form <- function(data,
     if (! is.numeric(data[[weight_var]])) {
       if (! silent) message("Lode weights are non-numeric.")
       return(if (logical) FALSE else "none")
-    } else if (any(data[[weight_var]] < 0)) {
-      if (! silent) message("Some lode weights are negative.")
-      #return(if (logical) FALSE else "none")
-      return(if (logical) TRUE else "lodes")
     }
   }
 
@@ -125,9 +121,6 @@ is_alluvia_form <- function(data,
     if (! is.numeric(data[[weight_var]])) {
       if (! silent) message("Alluvium weights are non-numeric.")
       return(if (logical) FALSE else "none")
-    } else if (any(data[[weight_var]] < 0)) {
-      if (! silent) message("Some alluvium weights are negative.")
-      return(if (logical) FALSE else "none")
     }
   }
 

R/stat-alluvium.r

@@ -1,12 +1,12 @@
 #' Alluvial positions
 #'
 #' Given a dataset with alluvial structure, `stat_alluvium` calculates the
-#' centroids (`x` and `y`) of the **lodes**, the intersections of
-#' the alluvia with the strata, together with their weights (heights;
-#' `ymin` and `ymax`). It leverages the `group` aesthetic for
-#' plotting purposes (for now).
+#' 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 order-options
+#' @template defunct-stat-params
 #'
 
 #' @import ggplot2
@@ -113,15 +113,9 @@ StatAlluvium <- ggproto(
       data <- transform(data, stratum = alluvium)
     }
 
-    # assign uniform weight if not provided
+    # assign unit amounts if not provided
     if (is.null(data$y)) {
-      if (is.null(data$weight)) {
-        data$y <- rep(1, nrow(data))
-      } else {
-        defunct_parameter("weight", "y", type = "aesthetic")
-        data$y <- data$weight
-        data$weight <- NULL
-      }
+      data$y <- rep(1, nrow(data))
     } else if (any(is.na(data$y))) {
       stop("Data contains missing `y` values.")
     }
@@ -205,7 +199,7 @@ StatAlluvium <- ggproto(
     # sign variable (sorts positives before negatives)
     data$yneg <- data$y < 0
 
-    # aggregate weights over otherwise equivalent alluvia
+    # cement (aggregate) `y` over otherwise equivalent alluvia
     if (! is.null(aggregate.y)) {
       deprecate_parameter("aggregate.y", "cement.alluvia")
       cement.alluvia <- aggregate.y
@@ -295,7 +289,7 @@ StatAlluvium <- ggproto(
                       fan = xtfrm(alluvium) *
                         (-1) ^ (yneg * absolute + reverse))
 
-    # sort data in preparation for 'y' sums
+    # sort data in preparation for `y` sums
     sort_fields <- c(
       "x",
       "deposit",
@@ -305,7 +299,7 @@ StatAlluvium <- ggproto(
       "fan"
     )
     data <- data[do.call(order, data[, sort_fields]), , drop = FALSE]
-    # calculate 'y' sums
+    # calculate `y` sums
     data$ycum <- NA
     for (xx in unique(data$x)) {
       for (yn in c(FALSE, TRUE)) {
@@ -351,7 +345,7 @@ StatAlluvium <- ggproto(
   }
 )
 
-# aggregate 'y' and 'label' over equivalent alluvia (omitting missing values)
+# aggregate `y` and `label` over equivalent alluvia (omitting missing values)
 cement_data <- function(data, key, id, fun) {
 
   agg_vars <- intersect(c("y", "label"), names(data))
@@ -377,7 +371,7 @@ cement_data <- function(data, key, id, fun) {
   # transform `id` in `data` accordingly
   data[[id]] <- alluv_agg[match(data[[id]], alluv_orig)]
 
-  # aggregate 'y' and 'label' by all other variables
+  # aggregate `y` and `label` by all other variables
   by_vars <- c(key, id, "binding")
   data_agg <- dplyr::group_by(data[, c(by_vars, agg_vars)], .dots = by_vars)
   data_agg <- if ("label" %in% agg_vars) {
@@ -421,7 +415,7 @@ cement_data_alt <- function(data, key, id) {
   alluv_data <- merge(alluv_data, alluv_agg, all.x = TRUE, all.y = FALSE)
   data[[id]] <- alluv_data$.id[match(data[[id]], alluv_data[[id]])]
 
-  # aggregate 'y' by `key`, `id`, and .binding
+  # aggregate `y` by `key`, `id`, and .binding
   data_agg <- stats::aggregate(
     formula = y ~ .,
     data = data[, c(key, id, ".binding", "y")],

R/stat-flow.r

@@ -1,10 +1,11 @@
 #' Flow positions
 #'
 #' Given a dataset with alluvial structure, `stat_flow` calculates the centroids
-#' (`x` and `y`) and weights (heights; `ymin` and `ymax`) of alluvial flows
-#' between each pair of adjacent axes.
+#' (`x` and `y`) and heights (`ymin` and `ymax`) of the flows between each pair
+#' of adjacent axes.
 #' @template stat-aesthetics
 #' @template order-options
+#' @template defunct-stat-params
 #'
 
 #' @import ggplot2
@@ -82,15 +83,9 @@ StatFlow <- ggproto(
       data <- transform(data, stratum = alluvium)
     }
 
-    # assign uniform weight if not provided
+    # assign unit amounts if not provided
     if (is.null(data$y)) {
-      if (is.null(data$weight)) {
-        data$y <- rep(1, nrow(data))
-      } else {
-        defunct_parameter("weight", "y", type = "aesthetic")
-        data$y <- data$weight
-        data$weight <- NULL
-      }
+      data$y <- rep(1, nrow(data))
     } else if (any(is.na(data$y))) {
       stop("Data contains missing `y` values.")
     }
@@ -219,18 +214,18 @@ StatFlow <- ggproto(
     # designate these flow pairings the alluvia
     data$alluvium <- as.integer(interaction(data[, adj_vars], drop = TRUE))
 
-    # sum 'y' and, if numeric, 'label' over 'x', 'yneg', and 'stratum'
+    # sum `y` and, if numeric, `label` over `x`, `yneg`, and `stratum`
     sum_vars <- c("y", if (is.numeric(data$label)) "label")
-    # exclude 'group' because it will be redefined below
+    # exclude `group` because it will be redefined below
     data$group <- NULL
     by_vars <- setdiff(names(data), c("group", sum_vars))
     # keep NAs in order to correctly position flows
     data <- dplyr::summarize_at(dplyr::group_by(data, .dots = by_vars),
                                 sum_vars, sum, na.rm = TRUE)
-    # redefine 'group' to be used to control grobs in the geom step
+    # redefine `group` to be used to control grobs in the geom step
     data <- transform(data, group = alluvium)
 
-    # sort data in preparation for 'y' sums
+    # sort data in preparation for `y` sums
     sort_fields <- c(
       "link", "x",
       "deposit",
@@ -239,7 +234,7 @@ StatFlow <- ggproto(
       "alluvium", "contact"
     )
     data <- data[do.call(order, data[, sort_fields]), , drop = FALSE]
-    # calculate 'y' sums
+    # calculate `y` sums
     data$ycum <- NA
     for (ll in unique(data$link)) {
       for (ss in unique(data$contact)) {

R/stat-stratum.r

@@ -1,9 +1,11 @@
 #' Stratum positions
 #'
 #' Given a dataset with alluvial structure, `stat_stratum` calculates the
-#' centroids of the strata at each axis, together with their weights (heights).
+#' centroids (`x` and `y`) and heights (`ymin` and `ymax`) of the strata at each
+#' axis.
 #' @template stat-aesthetics
 #' @template order-options
+#' @template defunct-stat-params
 #'
 
 #' @import ggplot2
@@ -16,8 +18,8 @@
 #'    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 total weight (largest on top, `FALSE`), or
-#'   in descending order of total weight (largest on bottom, `TRUE`).
+#'   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,
@@ -37,9 +39,9 @@
 #'   in which the data are in alluva form and are therefore converted to lode
 #'   form before the statistical transformation.
 #' @param label.strata Deprecated; alias for `infer.label`.
-#' @param min.y,max.y Numeric; bounds on the heights (weights) 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.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
@@ -101,15 +103,9 @@ StatStratum <- ggproto(
       }
     }
 
-    # assign uniform weight if not provided
+    # assign unit amounts if not provided
     if (is.null(data$y)) {
-      if (is.null(data$weight)) {
-        data$y <- rep(1, nrow(data))
-      } else {
-        defunct_parameter("weight", "y", type = "aesthetic")
-        data$y <- data$weight
-        data$weight <- NULL
-      }
+      data$y <- rep(1, nrow(data))
     } else if (any(is.na(data$y))) {
       stop("Data contains missing `y` values.")
     }
@@ -188,8 +184,8 @@ StatStratum <- ggproto(
     # sign variable (sorts positives before negatives)
     data$yneg <- data$y < 0
 
-    # aggregate variables over 'x', 'yneg', and 'stratum':
-    # take sums of 'y' and, if numeric, of 'label'
+    # aggregate variables over `x`, `yneg`, and `stratum`:
+    # take sums of `y` and, if numeric, of `label`
     # require others hold constant (or else be lost)
     agg_dat <- unique(data[, c("x", "yneg", "stratum")])
     for (var in setdiff(names(data), c("x", "yneg", "stratum"))) {
@@ -214,10 +210,10 @@ StatStratum <- ggproto(
     # define 'deposit' variable to rank strata vertically
     data <- deposit_data(data, decreasing, reverse, absolute)
 
-    # sort data in preparation for 'y' sums
+    # sort data in preparation for `y` sums
     data <- data[with(data, order(deposit)), , drop = FALSE]
 
-    # calculate 'y' sums
+    # calculate `y` sums
     data$ycum <- NA
     for (xx in unique(data$x)) {
       for (yn in c(FALSE, TRUE)) {

inst/examples/ex-stat-alluvium.r

@@ -112,3 +112,14 @@ ggplot(data = bn2,
                 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", infer.label = TRUE, absolute = FALSE) +
+  scale_x_discrete(limits = c("Class", "Sex", "Age"), expand = c(.1, .05)) +
+  scale_alpha_discrete(range = c(.25, .75), guide = FALSE)

inst/examples/ex-stat-stratum.r

@@ -44,3 +44,13 @@ ggplot(vaccinations,
            fill = response, label = response)) +
   stat_stratum(width = .5) +
   geom_text(stat = "stratum", min.y = 100)
+
+# use negative y values to encode rejection versus acceptance
+admissions <- as.data.frame(UCBAdmissions)
+admissions <- transform(admissions, Count = Freq * (-1) ^ (Admit == "Rejected"))
+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", infer.label = TRUE, min.y = 200) +
+  scale_x_discrete(limits = c("Department", "Gender"), expand = c(.05, .05))

man-roxygen/defunct-geom-params.r

@@ -1,4 +1,4 @@
 #' @section Defunct parameters:
-#' The previously deprecated parameters `axis_width` and `ribbon_bend` are now
-#' defunct. Use `width` and `knot.pos` instead.
+#' The previously defunct parameters `axis_width` and `ribbon_bend` have been
+#' discontinued. Use `width` and `knot.pos` instead.
 #'

man-roxygen/defunct-stat-params.r

@@ -0,0 +1,4 @@
+#' @section Defunct parameters:
+#' The previously defunct parameters `weight` and `aggregate.wts` have been
+#' discontinued. Use `y` and `cement.alluvia` instead.
+#'