normalize_thickness -> apply_subscale

NAMESPACE

@@ -3,6 +3,10 @@
 S3method(Mode,default)
 S3method(Mode,distribution)
 S3method(Mode,rvar)
+S3method(apply_subscale,"NULL")
+S3method(apply_subscale,data.frame)
+S3method(apply_subscale,default)
+S3method(apply_subscale,ggdist_thickness)
 S3method(cdf,ggdist__weighted_sample)
 S3method(cdf,ggdist__wrapped_categorical)
 S3method(curve_interval,data.frame)
@@ -33,10 +37,6 @@ S3method(is.na,ggdist_partial_colour_ramp)
 S3method(is.na,ggdist_thickness)
 S3method(makeContent,dots_grob)
 S3method(mean,ggdist__weighted_sample)
-S3method(normalize_thickness,"NULL")
-S3method(normalize_thickness,data.frame)
-S3method(normalize_thickness,default)
-S3method(normalize_thickness,ggdist_thickness)
 S3method(parse_dist,brmsprior)
 S3method(parse_dist,character)
 S3method(parse_dist,data.frame)

R/geom_dotsinterval.R

@@ -577,6 +577,7 @@ GeomDotsinterval = ggproto("GeomDotsinterval", GeomSlabinterval,
   ), GeomSlabinterval$param_docs),
 
   default_params = defaults(list(
+    subscale = "thickness",
     normalize = "none",
     binwidth = NA,
     dotsize = 1.07,
@@ -589,7 +590,7 @@ GeomDotsinterval = ggproto("GeomDotsinterval", GeomSlabinterval,
   ), GeomSlabinterval$default_params),
 
   hidden_params = union(c(
-    "normalize", "fill_type"
+    "subscale", "normalize", "fill_type"
   ), GeomSlabinterval$hidden_params),
 
 

R/geom_interval.R

@@ -76,7 +76,7 @@ GeomInterval = ggproto("GeomInterval", GeomSlabinterval,
 
   hidden_params = union(c(
     "show_slab", "show_point", "show_interval",
-    "normalize", "fill_type",
+    "subscale", "normalize", "fill_type",
     "subguide",
     "fatten_point"
   ), GeomSlabinterval$hidden_params)

R/geom_pointinterval.R

@@ -71,7 +71,7 @@ GeomPointinterval = ggproto("GeomPointinterval", GeomSlabinterval,
 
   hidden_params = union(c(
     "show_slab", "show_point", "show_interval",
-    "normalize", "fill_type",
+    "subscale", "normalize", "fill_type",
     "subguide"
   ), GeomSlabinterval$hidden_params),
 

R/geom_slabinterval.R

@@ -6,35 +6,6 @@
 
 # thickness handling functions -------------------------------------------------------
 
-#' normalize thickness values to between 0 and 1
-#' @noRd
-normalize_thickness = function(x, ...) UseMethod("normalize_thickness")
-
-#' @export
-normalize_thickness.NULL = function(x, ...) {
-  NULL
-}
-
-#' @export
-normalize_thickness.default = function(x, subscale = subscale_thickness) {
-  subscale(x)
-}
-
-#' @importFrom scales oob_squish_infinite
-#' @export
-normalize_thickness.ggdist_thickness = function(x, ...) {
-  # thickness values passed directly into the geom (e.g. by
-  # scale_thickness_shared()) are not normalized again.
-  x
-}
-
-#' @export
-normalize_thickness.data.frame = function(x, ...) {
-  x$thickness = normalize_thickness(x$thickness, ...)
-  x
-}
-
-
 #' rescale the slab data (ymin / ymax) to be within the confines of the bounding box
 #' we do this *again* here (rather than in setup_data) because
 #' position_dodge doesn't work if we only do it up there:
@@ -622,8 +593,21 @@ GeomSlabinterval = ggproto("GeomSlabinterval", AbstractGeom,
 
   param_docs = defaults(list(
     # SLAB PARAMS
+    subscale = glue_doc('
+      Sub-scale used to scale values of the `thickness` aesthetic within
+      the groups determined by `normalize`. One of:
+      \\itemize{
+        \\item A function that takes an `x` argument giving a numeric vector
+          of values to be scaled and then returns a [thickness] vector representing
+          the scaled values, such as [subscale_thickness()] or [subscale_identity()].
+        \\item A string giving the name of such a function when prefixed
+          with `"subscale_"`; e.g. `"thickness"` or `"identity"`.
+      }
+      For a comprehensive discussion and examples of slab scaling and normalization, see the
+      [`thickness` scale article](https://mjskay.github.io/ggdist/articles/thickness.html).
+      '),
     normalize = glue_doc('
-      How to normalize heights of functions input to the `thickness` aesthetic. One of:
+      Groups within which to scale values of the `thickness` aesthetic. One of:
       \\itemize{
         \\item `"all"`: normalize so that the maximum height across all data is `1`.
         \\item `"panels"`: normalize within panels so that the maximum height in each panel is `1`.
@@ -700,13 +684,14 @@ GeomSlabinterval = ggproto("GeomSlabinterval", AbstractGeom,
           [subguide_none()] (to draw no annotation). See [subguide_axis()]
           for a list of possibilities and examples.
         \\item A string giving the name of such a function when prefixed
-          with `"subguide"`; e.g. `"axis"` or `"none"`.
+          with `"subguide_"`; e.g. `"axis"` or `"none"`.
       }
       ')
   ), AbstractGeom$param_docs),
 
   default_params = list(
     orientation = NA,
+    subscale = "thickness",
     normalize = "all",
     fill_type = "segments",
     interval_size_domain = c(1, 6),
@@ -779,11 +764,12 @@ GeomSlabinterval = ggproto("GeomSlabinterval", AbstractGeom,
     # must do this here: not setup_data, so it happens after the thickness scale
     # has been applied; and not draw_panel, because normalization may be applied
     # across panels.
+    subscale_fun = match_function(params$subscale, "subscale_")
     switch(params$normalize,
       all = {
         # normalize so max height across all data is 1
         # this preserves slabs across groups in slab plots
-        data = normalize_thickness(data)
+        data = apply_subscale(data, subscale = subscale_fun)
       },
       panels = ,
       xy = ,
@@ -794,11 +780,12 @@ GeomSlabinterval = ggproto("GeomSlabinterval", AbstractGeom,
           xy = c("PANEL", y),
           groups = c("PANEL", y, "group")
         )
-        data = ddply_(data, normalization_groups, normalize_thickness)
+        data = ddply_(data, normalization_groups, apply_subscale, subscale = subscale_fun)
       },
       none = {
         # ensure thickness is a thickness-type vector so it is not normalized again
-        data$thickness = normalize_thickness(data$thickness, subscale = subscale_identity)
+        # TODO: deprecate this and direct people to use `subscale = "identity"` to turn off scaling
+        data$thickness = apply_subscale(data$thickness, subscale = subscale_identity)
       },
       stop0('`normalize` must be "all", "panels", "xy", groups", or "none", not "', params$normalize, '"')
     )

R/subscale.R

@@ -74,6 +74,37 @@ subscale_identity = function(x) {
 }
 
 
+# apply a thickness subscale ----------------------------------------------
+
+#' apply a thickness subscale to an object
+#' @noRd
+apply_subscale = function(x, subscale) UseMethod("apply_subscale")
+
+#' @export
+apply_subscale.NULL = function(x, subscale) {
+  NULL
+}
+
+#' @export
+apply_subscale.default = function(x, subscale) {
+  subscale(x)
+}
+
+#' @importFrom scales oob_squish_infinite
+#' @export
+apply_subscale.ggdist_thickness = function(x, subscale) {
+  # thickness values passed directly into the geom (e.g. by
+  # scale_thickness_shared()) are not normalized again.
+  x
+}
+
+#' @export
+apply_subscale.data.frame = function(x, subscale) {
+  x$thickness = apply_subscale(x$thickness, subscale = subscale)
+  x
+}
+
+
 # helpers -----------------------------------------------------------------
 
 #' Validate an `expand` argument and return a canonical version