Merge branch 'main' into figure-space

DESCRIPTION

@@ -33,8 +33,7 @@ Suggests:
     ggplot2,
     hms (>= 0.5.0),
     stringi,
-    testthat (>= 3.0.0),
-    waldo (>= 0.4.0)
+    testthat (>= 3.0.0)
 Config/Needs/website: tidyverse/tidytemplate
 Config/testthat/edition: 3
 Encoding: UTF-8

NAMESPACE

@@ -12,6 +12,7 @@ S3method(offset_by,numeric)
 S3method(plot,trans)
 S3method(print,trans)
 S3method(rescale,"NULL")
+S3method(rescale,AsIs)
 S3method(rescale,Date)
 S3method(rescale,POSIXt)
 S3method(rescale,difftime)
@@ -20,6 +21,7 @@ S3method(rescale,integer64)
 S3method(rescale,logical)
 S3method(rescale,numeric)
 S3method(rescale_mid,"NULL")
+S3method(rescale_mid,AsIs)
 S3method(rescale_mid,Date)
 S3method(rescale_mid,POSIXt)
 S3method(rescale_mid,dist)
@@ -35,12 +37,14 @@ export(abs_area)
 export(alpha)
 export(area_pal)
 export(as.trans)
+export(asinh_trans)
 export(asn_trans)
 export(atanh_trans)
 export(boxcox_trans)
 export(breaks_extended)
 export(breaks_log)
 export(breaks_pretty)
+export(breaks_timespan)
 export(breaks_width)
 export(brewer_pal)
 export(cbreaks)
@@ -66,6 +70,7 @@ export(demo_datetime)
 export(demo_discrete)
 export(demo_log10)
 export(demo_time)
+export(demo_timespan)
 export(dichromat_pal)
 export(discard)
 export(div_gradient_pal)
@@ -86,6 +91,7 @@ export(identity_trans)
 export(is.trans)
 export(label_bytes)
 export(label_comma)
+export(label_currency)
 export(label_date)
 export(label_date_short)
 export(label_dollar)
@@ -100,6 +106,7 @@ export(label_percent)
 export(label_pvalue)
 export(label_scientific)
 export(label_time)
+export(label_timespan)
 export(label_wrap)
 export(linetype_pal)
 export(log10_trans)
@@ -157,6 +164,7 @@ export(squish)
 export(squish_infinite)
 export(time_format)
 export(time_trans)
+export(timespan_trans)
 export(train_continuous)
 export(train_discrete)
 export(trans_breaks)

NEWS.md

@@ -8,12 +8,27 @@
   vectors during training. Mixing of character and factor data will still lead
   to different results depending on the training order.
 * Add a rescale method for `difftime` objects (#382)
+* `rescale(I(x), ...)` and `rescale_mid(I(x), ...)` return `I(x)` unaltered 
+  (@teunbrand, #403).
 * The `scale_cut` argument in `number()` now works as advertised for values 
   below the lowest cut value (#346)
 * Added a new option to the `style_positive` argument in `label_*()` functions.
   Setting this to `"space"` will add a figure space in front of the number to 
   make it easier to align positive and negative values as figure space takes up
   the same amount of space as `-` (#366)
+* `label_dollar()` has been superseeded by `label_currency()` for clarity (#344)
+* `sqrt_trans()` no longer returns an inverse for values outside of its domain 
+  (#214)
+* Add better support for `difftime` objects. `label_timespan()` adds 
+  functionality for adding correct unit suffix to timespan data, 
+  `breaks_timespan()` adds functionality for finding pleasant breakpoints across
+  the various bases in time units, while `timespan_trans()` wraps it all 
+  together and provides an alternative to `hms_trans()` (#212)
+* Add an inverse (area) hyperbolic sine transformation `asinh_trans()`, which
+  provides a logarithm-like transformation of a space, but which accommodates
+  negative values (#297)
+* Transformation objects can optionally include the derivatives of the transform
+  and the inverse transform (@mjskay, #322).
 
 # scales 1.2.1
 

R/bounds.R

@@ -5,6 +5,9 @@
 #' @param from input range (vector of length two).  If not given, is
 #'   calculated from the range of `x`
 #' @param ... other arguments passed on to methods
+#' @details
+#' Objects of class `<AsIs>` are returned unaltered.
+#'
 #' @keywords manip
 #' @export
 #' @examples
@@ -62,6 +65,9 @@ rescale.integer64 <- function(x, to = c(0, 1), from = range(x, na.rm = TRUE), ..
 #' @export
 rescale.difftime <- rescale.numeric
 
+#' @rdname rescale
+#' @export
+rescale.AsIs <- function(x, to, from, ...) x
 
 #' Rescale vector to have specified minimum, midpoint, and maximum
 #'
@@ -72,6 +78,8 @@ rescale.difftime <- rescale.numeric
 #'   calculated from the range of `x`
 #' @param mid mid-point of input range
 #' @param ... other arguments passed on to methods
+#' @details
+#' Objects of class `<AsIs>` are returned unaltered.
 #' @examples
 #' rescale_mid(1:100, mid = 50.5)
 #' rescale_mid(runif(50), mid = 0.5)
@@ -133,6 +141,10 @@ rescale_mid.integer64 <- function(x, to = c(0, 1), from = range(x, na.rm = TRUE)
 }
 
 
+#' @rdname rescale_mid
+#' @export
+rescale_mid.AsIs <- function(x, to, from, ...) x
+
 #' Rescale numeric vector to have specified maximum
 #'
 #' @export

R/breaks.R

@@ -140,3 +140,45 @@ breaks_pretty <- function(n = 5, ...) {
 #' @export
 #' @inheritParams breaks_pretty
 pretty_breaks <- breaks_pretty
+
+#' Breaks for timespan data
+#'
+#' As timespan units span a variety of bases (1000 below seconds, 60 for second
+#' and minutes, 24 for hours, and 7 for days), the range of the input data
+#' determines the base used for calculating breaks
+#'
+#' @param unit The unit used to interpret numeric data input
+#' @inheritParams breaks_extended
+#' @export
+#' @examples
+#' demo_timespan(seq(0, 100), breaks = breaks_timespan())
+#'
+breaks_timespan <- function(unit = c("secs", "mins", "hours", "days", "weeks"), n = 5) {
+  unit <- arg_match(unit)
+  force(n)
+  function(x) {
+    x <- as.numeric(as.difftime(x, units = unit), units = "secs")
+    rng <- range(x)
+    diff <- rng[2] - rng[1]
+
+    if (diff <= 2 * 60) {
+      scale <- 1
+    } else if (diff <= 2 * 3600) {
+      scale <- 60
+    } else if (diff <= 2 * 86400) {
+      scale <- 3600
+    } else if (diff <= 2 * 604800) {
+      scale <- 86400
+    } else {
+      scale <- 604800
+    }
+
+    rng <- rng / scale
+    breaks <- labeling::extended(
+      rng[1], rng[2], n,
+      Q = c(1, 2, 1.5, 4, 3),
+      only.loose = FALSE
+    )
+    as.difftime(breaks * scale, units = "secs")
+  }
+}

R/label-dollar.R → R/label-currency.R

@@ -1,59 +1,57 @@
-#' Label currencies ($100, $2.50, etc)
+#' Label currencies ($100, €2.50, etc)
 #'
-#' Format numbers as currency, rounding values to dollars or cents using
-#' a convenient heuristic.
+#' Format numbers as currency, rounding values to monetary or fractional
+#' monetary using unit a convenient heuristic.
 #'
 #' @inherit label_number return params
-#' @param accuracy,largest_with_cents Number to round to. If `NULL`, the default,
-#'   values will be rounded to the nearest integer, unless any of the
-#'   values has non-zero fractional component (e.g. cents) and the largest
-#'   value is less than `largest_with_cents` which by default is 100,000.
+#' @param accuracy,largest_with_fractional Number to round
+#'   to. If `NULL`, the default, values will be rounded to the nearest integer,
+#'   unless any of the values has non-zero fractional component (e.g. cents) and
+#'   the largest value is less than `largest_with_fractional` which by default
+#'   is 100,000.
 #' @param prefix,suffix Symbols to display before and after value.
-#' @param negative_parens `r lifecycle::badge("deprecated")` Use
-#'   `style_negative = "parens"` instead.
 #' @inheritDotParams number
 #' @export
 #' @family labels for continuous scales
 #' @examples
-#' demo_continuous(c(0, 1), labels = label_dollar())
-#' demo_continuous(c(1, 100), labels = label_dollar())
+#' demo_continuous(c(0, 1), labels = label_currency())
+#' demo_continuous(c(1, 100), labels = label_currency())
 #'
 #' # Customise currency display with prefix and suffix
-#' demo_continuous(c(1, 100), labels = label_dollar(prefix = "USD "))
-#' euro <- label_dollar(
-#'   prefix = "",
-#'   suffix = "\u20ac",
+#' demo_continuous(c(1, 100), labels = label_currency(prefix = "USD "))
+#' yen <- label_currency(
+#'   prefix = "¥",
+#'   suffix = "",
 #'   big.mark = ".",
 #'   decimal.mark = ","
 #' )
-#' demo_continuous(c(1000, 1100), labels = euro)
+#' demo_continuous(c(1000, 1100), labels = yen)
 #'
-#' # Use negative_parens = TRUE for finance style display
-#' demo_continuous(c(-100, 100), labels = label_dollar(style_negative = "parens"))
+#' # Use style_negative = "parens" for finance style display
+#' demo_continuous(c(-100, 100), labels = label_currency(style_negative = "parens"))
 #'
 #' # Use scale_cut to use K/M/B where appropriate
 #' demo_log10(c(1, 1e16),
 #'   breaks = log_breaks(7, 1e3),
-#'   labels = label_dollar(scale_cut = cut_short_scale())
+#'   labels = label_currency(scale_cut = cut_short_scale())
 #' )
 #' # cut_short_scale() uses B = one thousand million
 #' # cut_long_scale() uses B = one million million
 #' demo_log10(c(1, 1e16),
 #'   breaks = log_breaks(7, 1e3),
-#'   labels = label_dollar(scale_cut = cut_long_scale())
+#'   labels = label_currency(scale_cut = cut_long_scale())
 #' )
 #'
 #' # You can also define your own breaks
-#' gbp <- label_dollar(
+#' gbp <- label_currency(
 #'   prefix = "\u00a3",
 #'   scale_cut = c(0, k = 1e3, m = 1e6, bn = 1e9, tn = 1e12)
 #' )
 #' demo_log10(c(1, 1e12), breaks = log_breaks(5, 1e3), labels = gbp)
-label_dollar <- function(accuracy = NULL, scale = 1, prefix = "$",
-                         suffix = "", big.mark = ",", decimal.mark = ".",
-                         trim = TRUE, largest_with_cents = 100000,
-                         negative_parens = deprecated(),
-                         ...) {
+label_currency <- function(accuracy = NULL, scale = 1, prefix = "$",
+                           suffix = "", big.mark = ",", decimal.mark = ".",
+                           trim = TRUE, largest_with_fractional = 100000,
+                           ...) {
   force_all(
     accuracy,
     scale,
@@ -62,8 +60,7 @@ label_dollar <- function(accuracy = NULL, scale = 1, prefix = "$",
     big.mark,
     decimal.mark,
     trim,
-    largest_with_cents,
-    negative_parens,
+    largest_with_fractional,
     ...
   )
   function(x) {
@@ -76,8 +73,7 @@ label_dollar <- function(accuracy = NULL, scale = 1, prefix = "$",
       big.mark = big.mark,
       decimal.mark = decimal.mark,
       trim = trim,
-      largest_with_cents = largest_with_cents,
-      negative_parens = negative_parens,
+      largest_with_cents = largest_with_fractional,
       ...
     )
   }
@@ -95,18 +91,55 @@ needs_cents <- function(x, threshold) {
   !all(x == floor(x), na.rm = TRUE)
 }
 
-#' Superseded interface to `label_dollar()`
+#' Superseded interface to `label_currency()`
 #'
 #' @description
 #' `r lifecycle::badge("superseded")`
 #'
 #' These functions are kept for backward compatibility; you should switch
-#' to [label_dollar()] for new code.
+#' to [label_currency()] for new code.
 #'
 #' @keywords internal
 #' @export
-#' @inheritParams label_dollar
-dollar_format <- label_dollar
+#' @inheritParams label_currency
+#' @param largest_with_cents Like `largest_with_fractional()` in
+#'   [label_currency()]
+#' @param negative_parens `r lifecycle::badge("deprecated")` Use
+#'   `style_negative = "parens"` instead.
+dollar_format <- function(accuracy = NULL, scale = 1, prefix = "$",
+                          suffix = "", big.mark = ",", decimal.mark = ".",
+                          trim = TRUE, largest_with_cents = 100000,
+                          negative_parens = deprecated(),
+                          ...) {
+  force_all(
+    accuracy,
+    scale,
+    prefix,
+    suffix,
+    big.mark,
+    decimal.mark,
+    trim,
+    largest_with_cents,
+    negative_parens,
+    ...
+  )
+  function(x) {
+    dollar(
+      x,
+      accuracy = accuracy,
+      scale = scale,
+      prefix = prefix,
+      suffix = suffix,
+      big.mark = big.mark,
+      decimal.mark = decimal.mark,
+      trim = trim,
+      largest_with_cents = largest_with_cents,
+      negative_parens = negative_parens,
+      ...
+    )
+  }
+}
+
 
 #' @export
 #' @rdname dollar_format
@@ -151,3 +184,7 @@ dollar <- function(x, accuracy = NULL, scale = 1, prefix = "$",
     ...
   )
 }
+
+#' @export
+#' @rdname dollar_format
+label_dollar <- dollar_format