simplify options documentation + add options for curve params

DESCRIPTION

@@ -2,7 +2,7 @@ Package: ggalluvial
 Type: Package
 Title: Alluvial Plots in 'ggplot2'
 Version: 0.12.0
-Date: 2020-07-13
+Date: 2020-07-14
 Authors@R: 
     person(given = "Jason Cory",
            family = "Brunson",

NEWS.md

@@ -45,6 +45,10 @@ The `knot.pos` parameter of `geom_alluvium()` and `geom_flow()` is now interpret
 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

R/geom-alluvium.r

@@ -43,7 +43,7 @@ geom_alluvium <- function(mapping = NULL,
                           position = "identity",
                           width = 1/3,
                           knot.pos = 1/4, knot.prop = TRUE,
-                          curve_type = "xspline", curve_range = NULL,
+                          curve_type = NULL, curve_range = NULL,
                           segments = NULL,
                           na.rm = FALSE,
                           show.legend = NA,
@@ -110,9 +110,14 @@ GeomAlluvium <- ggproto(
   draw_group = function(self, data, panel_scales, coord,
                         width = 1/3,
                         knot.pos = 1/4, knot.prop = TRUE,
-                        curve_type = "xspline", curve_range = NULL,
+                        curve_type = NULL, curve_range = NULL,
                         segments = NULL) {
 
+    # 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)
 

R/geom-flow.r

@@ -28,7 +28,7 @@ geom_flow <- function(mapping = NULL,
                       position = "identity",
                       width = 1/3,
                       knot.pos = 1/4, knot.prop = TRUE,
-                      curve_type = "xspline", curve_range = NULL,
+                      curve_type = NULL, curve_range = NULL,
                       segments = NULL,
                       aes.flow = "forward",
                       na.rm = FALSE,
@@ -91,9 +91,14 @@ GeomFlow <- ggproto(
   draw_panel = function(self, data, panel_params, coord,
                         width = 1/3, aes.flow = "forward",
                         knot.pos = 1/4, knot.prop = TRUE,
-                        curve_type = "xspline", curve_range = NULL,
+                        curve_type = NULL, curve_range = NULL,
                         segments = NULL) {
-
+
+    # 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), ]
 

R/geom-utils.r

@@ -20,13 +20,13 @@ unit_sine <- function(x) {
 }
 # inverse tangent function compressed from a specified symmetric domain
 unit_arctangent <- function(x, curve_range) {
-  if (is.null(curve_range)) curve_range <- 2 + sqrt(3)
+  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.null(curve_range)) curve_range <- 6
+  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))

R/ggalluvial-package.r

@@ -13,13 +13,19 @@
 "_PACKAGE"
 
 # 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"
+  ggalluvial.aes.bind = "none",
+  # curves
+  ggalluvial.curve_type = "xspline",
+  ggalluvial.curve_range = NA_real_,
+  ggalluvial.segments = 48L
 )
 
 ggalluvial_opt <- function(x) {

R/stat-alluvium.r

@@ -38,16 +38,16 @@ stat_alluvium <- function(mapping = NULL,
                           data = NULL,
                           geom = "alluvium",
                           position = "identity",
-                          decreasing = ggalluvial_opt("decreasing"),
-                          reverse = ggalluvial_opt("reverse"),
-                          absolute = ggalluvial_opt("absolute"),
+                          decreasing = NULL,
+                          reverse = NULL,
+                          absolute = NULL,
                           discern = FALSE,
                           negate.strata = NULL,
                           aggregate.y = NULL,
-                          cement.alluvia = ggalluvial_opt("cement.alluvia"),
-                          lode.guidance = ggalluvial_opt("lode.guidance"),
+                          cement.alluvia = NULL,
+                          lode.guidance = NULL,
                           lode.ordering = NULL,
-                          aes.bind = ggalluvial_opt("aes.bind"),
+                          aes.bind = NULL,
                           infer.label = FALSE,
                           min.y = NULL, max.y = NULL,
                           na.rm = FALSE,
@@ -163,19 +163,27 @@ StatAlluvium <- ggproto(
   },
 
   compute_panel = function(data, scales,
-                           decreasing = ggalluvial_opt("decreasing"),
-                           reverse = ggalluvial_opt("reverse"),
-                           absolute = ggalluvial_opt("absolute"),
+                           decreasing = NULL,
+                           reverse = NULL,
+                           absolute = NULL,
                            discern = FALSE, distill = first,
                            negate.strata = NULL,
                            aggregate.y = NULL,
-                           cement.alluvia = ggalluvial_opt("cement.alluvia"),
-                           lode.guidance = ggalluvial_opt("lode.guidance"),
+                           cement.alluvia = NULL,
+                           lode.guidance = NULL,
                            lode.ordering = NULL,
-                           aes.bind = ggalluvial_opt("aes.bind"),
+                           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",

R/stat-flow.r

@@ -34,12 +34,12 @@ stat_flow <- function(mapping = NULL,
                       data = NULL,
                       geom = "flow",
                       position = "identity",
-                      decreasing = ggalluvial_opt("decreasing"),
-                      reverse = ggalluvial_opt("reverse"),
-                      absolute = ggalluvial_opt("absolute"),
+                      decreasing = NULL,
+                      reverse = NULL,
+                      absolute = NULL,
                       discern = FALSE,
                       negate.strata = NULL,
-                      aes.bind = ggalluvial_opt("aes.bind"),
+                      aes.bind = NULL,
                       infer.label = FALSE,
                       min.y = NULL, max.y = NULL,
                       na.rm = FALSE,
@@ -134,15 +134,21 @@ StatFlow <- ggproto(
   },
 
   compute_panel = function(self, data, scales,
-                           decreasing = ggalluvial_opt("decreasing"),
-                           reverse = ggalluvial_opt("reverse"),
-                           absolute = ggalluvial_opt("absolute"),
+                           decreasing = NULL,
+                           reverse = NULL,
+                           absolute = NULL,
                            discern = FALSE, distill = first,
                            negate.strata = NULL,
-                           aes.bind = ggalluvial_opt("aes.bind"),
+                           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",

R/stat-stratum.r

@@ -57,9 +57,9 @@ stat_stratum <- function(mapping = NULL,
                          data = NULL,
                          geom = "stratum",
                          position = "identity",
-                         decreasing = ggalluvial_opt("decreasing"),
-                         reverse = ggalluvial_opt("reverse"),
-                         absolute = ggalluvial_opt("absolute"),
+                         decreasing = NULL,
+                         reverse = NULL,
+                         absolute = NULL,
                          discern = FALSE, distill = first,
                          negate.strata = NULL,
                          infer.label = FALSE, label.strata = NULL,
@@ -165,15 +165,20 @@ StatStratum <- ggproto(
   },
 
   compute_panel = function(self, data, scales,
-                           decreasing = ggalluvial_opt("decreasing"),
-                           reverse = ggalluvial_opt("reverse"),
-                           absolute = ggalluvial_opt("absolute"),
+                           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",

inst/examples/ex-geom-alluvium.r

@@ -11,7 +11,7 @@ gg <- ggplot(alluvial::Refugees,
 # time series bump chart (quintic flows)
 gg + geom_alluvium(aes(fill = country, colour = country),
                    width = 1/4, alpha = 2/3, decreasing = FALSE,
-                   curve_type = "quintic")
+                   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)

inst/examples/ex-geom-flow.r

@@ -12,7 +12,7 @@ ggplot(as.data.frame(Titanic),
 ggplot(as.data.frame(Titanic),
        aes(y = Freq,
            axis1 = Class, axis2 = Sex)) +
-  geom_flow(aes(fill = Age), width = .4, curve_type = "sigmoid") +
+  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")) +

man-roxygen/geom-curves.r

@@ -1,5 +1,4 @@
 #' @section Curves:
-
 #' By default, `geom_alluvium()` and `geom_flow()` render flows between lodes as
 #' filled regions between parallel x-splines. These graphical elements,
 #' generated using [`grid::xsplineGrob()`][grid::grid.xspline], are
@@ -35,8 +34,20 @@
 #' 
 #' Only the (default) `"xspline"` option uses the `knot.*` parameters, while
 #' only the alternative curves use the `segments` parameter, and only
-#' `"arctangent"` and `"sigmoid"` use the `curve_range` parameter. Larger values
-#' of `curve_range` result in greater compression and steeper slopes. The `NULL`
-#' default will be changed to `2+sqrt(3)` for `"arctangent"` and to `6` for
-#' `"sigmoid"`.
+#' `"arctangent"` and `"sigmoid"` use the `curve_range` parameter. (Both are
+#' ignored if not needed.) Larger values of `curve_range` result in greater
+#' compression and steeper slopes. The `NULL` default will be changed to
+#' `2+sqrt(3)` for `"arctangent"` and to `6` for `"sigmoid"`.
+#' 
+#' These package-specific options set global values for `curve_type`,
+#' `curve_range`, and `segments` that will be defaulted to when not manually
+#' set:
+#' 
+#' - `ggalluvial.curve_type`: defaults to `"xspline"`.
+#' - `ggalluvial.curve_range`: defaults to `NA`, which triggers the
+#'   curve-specific default values.
+#' - `ggalluvial.segments`: defaults to `48L`.
 #' 
+#' See [base::options()] for how to use options.
+#' 
+