From de9eb903e2c5e2f783a0c0f790ec682499546bbb Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Wed, 29 Nov 2023 13:04:49 +0100 Subject: [PATCH 1/8] deprecate `raster` in favour of `display` --- R/guide-colorbar.R | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/R/guide-colorbar.R b/R/guide-colorbar.R index 6e2206a26e..54913fbc38 100644 --- a/R/guide-colorbar.R +++ b/R/guide-colorbar.R @@ -134,7 +134,8 @@ guide_colourbar <- function( barwidth = NULL, barheight = NULL, nbin = 300, - raster = TRUE, + display = "raster", + raster = lifecycle::deprecated(), # frame frame = element_blank(), @@ -158,6 +159,12 @@ guide_colourbar <- function( available_aes = c("colour", "color", "fill"), ... ) { + if (lifecycle::is_present(raster)) { + deprecate_soft0("3.5.0", "guide_colourbar(raster)", "guide_colourbar(display)") + check_bool(raster) + display <- if (raster) "raster" else "rectangles" + } + display <- match.arg(display, c("raster", "rectangles", "gradient")) if (!(is.null(barwidth) || is.unit(barwidth))) { barwidth <- unit(barwidth, default.unit) } @@ -229,7 +236,7 @@ guide_colourbar <- function( keywidth = barwidth, keyheight = barheight, nbin = nbin, - raster = raster, + display = display, # frame frame = frame, @@ -282,7 +289,7 @@ GuideColourbar <- ggproto( keywidth = NULL, keyheight = NULL, nbin = 300, - raster = TRUE, + display = "raster", draw_lim = c(TRUE, TRUE), From 82403475f6b65e5434904a158ba95773801f7e06 Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Wed, 29 Nov 2023 13:05:14 +0100 Subject: [PATCH 2/8] Use 15 colours as default for gradient --- R/guide-colorbar.R | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/R/guide-colorbar.R b/R/guide-colorbar.R index 54913fbc38..90988bafc6 100644 --- a/R/guide-colorbar.R +++ b/R/guide-colorbar.R @@ -133,7 +133,7 @@ guide_colourbar <- function( # bar barwidth = NULL, barheight = NULL, - nbin = 300, + nbin = NULL, display = "raster", raster = lifecycle::deprecated(), @@ -165,6 +165,8 @@ guide_colourbar <- function( display <- if (raster) "raster" else "rectangles" } display <- match.arg(display, c("raster", "rectangles", "gradient")) + nbin <- nbin %||% switch(display, gradient = 15, 300) + if (!(is.null(barwidth) || is.unit(barwidth))) { barwidth <- unit(barwidth, default.unit) } From 2904d0ca7102f415682c0cddfe78b0e77a5f2b7d Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Wed, 29 Nov 2023 13:06:40 +0100 Subject: [PATCH 3/8] Don't account for bins to offset labels --- R/guide-colorbar.R | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/R/guide-colorbar.R b/R/guide-colorbar.R index 90988bafc6..04a732e64c 100644 --- a/R/guide-colorbar.R +++ b/R/guide-colorbar.R @@ -354,13 +354,13 @@ GuideColourbar <- ggproto( params$title <- scale$make_title( params$title %|W|% scale$name %|W|% title ) - limits <- c(params$decor$value[1], params$decor$value[nrow(params$decor)]) - params$key$.value <- rescale( - params$key$.value, - c(0.5, params$nbin - 0.5) / params$nbin, - limits + to <- switch( + params$display, + gradient = c(0, 1), + c(0.5, params$nbin - 0.5) / params$nbin ) + params$key$.value <- rescale(params$key$.value, to = to, from = limits) params }, From 554a1f39bab03e3759b5a927ad5d2c1bf2da898e Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Wed, 29 Nov 2023 13:07:18 +0100 Subject: [PATCH 4/8] add gradient display --- R/guide-colorbar.R | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/R/guide-colorbar.R b/R/guide-colorbar.R index 04a732e64c..3e27fe8e30 100644 --- a/R/guide-colorbar.R +++ b/R/guide-colorbar.R @@ -447,8 +447,7 @@ GuideColourbar <- ggproto( }, build_decor = function(decor, grobs, elements, params) { - - if (params$raster) { + if (params$display == "raster") { image <- switch( params$direction, "horizontal" = t(decor$colour), @@ -462,7 +461,7 @@ GuideColourbar <- ggproto( gp = gpar(col = NA), interpolate = TRUE ) - } else{ + } else if (params$display == "rectangles") { if (params$direction == "horizontal") { width <- elements$key.width / nrow(decor) height <- elements$key.height @@ -481,6 +480,20 @@ GuideColourbar <- ggproto( default.units = "cm", gp = gpar(col = NA, fill = decor$colour) ) + } else if (params$display == "gradient") { + check_device("gradients", call = expr(guide_colourbar())) + value <- if (isTRUE(params$reverse)) { + rescale(decor$value, to = c(1, 0)) + } else { + rescale(decor$value, to = c(0, 1)) + } + position <- switch( + params$direction, + horizontal = list(y1 = unit(0.5, "npc"), y2 = unit(0.5, "npc")), + vertical = list(x1 = unit(0.5, "npc"), x2 = unit(0.5, "npc")) + ) + gradient <- inject(linearGradient(decor$colour, value, !!!position)) + grob <- rectGrob(gp = gpar(fill = gradient, col = NA)) } frame <- element_grob(elements$frame, fill = NA) From bb3f434c24091feffc717659e5969124bbd1c7dc Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Wed, 29 Nov 2023 13:19:46 +0100 Subject: [PATCH 5/8] deal with old R versions --- R/backports.R | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/R/backports.R b/R/backports.R index 4679be5680..f03f483064 100644 --- a/R/backports.R +++ b/R/backports.R @@ -22,3 +22,17 @@ if (getRversion() < "3.5") { isFALSE <- function(x) is.logical(x) && length(x) == 1L && !is.na(x) && !x isTRUE <- function(x) is.logical(x) && length(x) == 1L && !is.na(x) && x } + +version_unavailable <- function(...) { + fun <- as_label(current_call()[[1]]) + cli::cli_abort("{.fn {fun}} is not available in R version {getRversion()}.") +} + +# Unavailable prior to R 4.1.0 +linearGradient <- version_unavailable + +on_load({ + if ("linearGradient" %in% getNamespaceExports("grid")) { + linearGradient <- grid::linearGradient() + } +}) From 8edc906cb9e32a25662724f506b40c772338e310 Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Wed, 29 Nov 2023 13:57:26 +0100 Subject: [PATCH 6/8] document options --- R/guide-colorbar.R | 16 ++++++++++++---- R/guide-colorsteps.R | 2 +- man/guide_colourbar.Rd | 28 ++++++++++++++++++++-------- 3 files changed, 33 insertions(+), 13 deletions(-) diff --git a/R/guide-colorbar.R b/R/guide-colorbar.R index 3e27fe8e30..57fa237278 100644 --- a/R/guide-colorbar.R +++ b/R/guide-colorbar.R @@ -33,10 +33,18 @@ NULL #' drawn around the bar. #' @param nbin A numeric specifying the number of bins for drawing the #' colourbar. A smoother colourbar results from a larger value. -#' @param raster A logical. If `TRUE` then the colourbar is rendered as a -#' raster object. If `FALSE` then the colourbar is rendered as a set of -#' rectangles. Note that not all graphics devices are capable of rendering -#' raster image. +#' @param display A string indicating a method to display the colourbar. Can be +#' one of the following: +#' +#' * `"raster"` to display as a bitmap image. +#' * `"rectangles"` to display as a series of rectangles. +#' * `"gradient"` to display as a linear gradient. +#' +#' Note that not all devices are able to render rasters and gradients. +#' @param raster `r lifecycle::badge("deprecated")` A logical. If `TRUE` then +#' the colourbar is rendered as a raster object. If `FALSE` then the colourbar +#' is rendered as a set of rectangles. Note that not all graphics devices are +#' capable of rendering raster image. #' @param ticks A theme object for rendering tick marks at the colourbar. #' Usually, the object of `element_line()` is expected (default). If #' `element_blank()`, no tick marks are drawn. For backward compatibility, diff --git a/R/guide-colorsteps.R b/R/guide-colorsteps.R index c5315e6da6..8493943841 100644 --- a/R/guide-colorsteps.R +++ b/R/guide-colorsteps.R @@ -16,7 +16,7 @@ #' (default), no tick marks are drawn. For backward compatibility, can also #' be a logical which translates `TRUE` to `element_line()` and `FALSE` to #' `element_blank()`. -#' @inheritDotParams guide_colourbar -nbin -raster -ticks -available_aes +#' @inheritDotParams guide_colourbar -nbin -raster -ticks -available_aes -display #' #' @inheritSection guide_bins Use with discrete scale #' diff --git a/man/guide_colourbar.Rd b/man/guide_colourbar.Rd index 7813c12b1c..d2aa8fd7c6 100644 --- a/man/guide_colourbar.Rd +++ b/man/guide_colourbar.Rd @@ -18,8 +18,9 @@ guide_colourbar( label.vjust = NULL, barwidth = NULL, barheight = NULL, - nbin = 300, - raster = TRUE, + nbin = NULL, + display = "raster", + raster = lifecycle::deprecated(), frame = element_blank(), frame.colour = NULL, frame.linewidth = NULL, @@ -51,8 +52,9 @@ guide_colorbar( label.vjust = NULL, barwidth = NULL, barheight = NULL, - nbin = 300, - raster = TRUE, + nbin = NULL, + display = "raster", + raster = lifecycle::deprecated(), frame = element_blank(), frame.colour = NULL, frame.linewidth = NULL, @@ -120,10 +122,20 @@ the height of the colourbar. Default value is \code{legend.key.height} or \item{nbin}{A numeric specifying the number of bins for drawing the colourbar. A smoother colourbar results from a larger value.} -\item{raster}{A logical. If \code{TRUE} then the colourbar is rendered as a -raster object. If \code{FALSE} then the colourbar is rendered as a set of -rectangles. Note that not all graphics devices are capable of rendering -raster image.} +\item{display}{A string indicating a method to display the colourbar. Can be +one of the following: +\itemize{ +\item \code{"raster"} to display as a bitmap image. +\item \code{"rectangles"} to display as a series of rectangles. +\item \code{"gradient"} to display as a linear gradient. +} + +Note that not all devices are able to render rasters and gradients.} + +\item{raster}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} A logical. If \code{TRUE} then +the colourbar is rendered as a raster object. If \code{FALSE} then the colourbar +is rendered as a set of rectangles. Note that not all graphics devices are +capable of rendering raster image.} \item{frame}{A theme object for rendering a frame drawn around the bar. Usually, the object of \code{element_rect()} is expected. If \code{element_blank()} From 051191b264be91124177fb77c12cf2b73fbcc5f6 Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Thu, 14 Dec 2023 12:12:31 +0100 Subject: [PATCH 7/8] use `arg_match0()` --- R/guide-colorbar.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/R/guide-colorbar.R b/R/guide-colorbar.R index 91a7181aae..ab72b8aeda 100644 --- a/R/guide-colorbar.R +++ b/R/guide-colorbar.R @@ -130,7 +130,7 @@ guide_colourbar <- function( check_bool(raster) display <- if (raster) "raster" else "rectangles" } - display <- match.arg(display, c("raster", "rectangles", "gradient")) + display <- arg_match0(display, c("raster", "rectangles", "gradient")) nbin <- nbin %||% switch(display, gradient = 15, 300) theme <- deprecated_guide_args(theme, ...) From e2890b4e7cfe9d70862adf0eef1eceff90469a53 Mon Sep 17 00:00:00 2001 From: Teun van den Brand Date: Thu, 14 Dec 2023 12:14:42 +0100 Subject: [PATCH 8/8] Add news bullet --- NEWS.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/NEWS.md b/NEWS.md index 55dffd0401..952f5007ec 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,8 @@ # ggplot2 (development version) +* New `display` argument in `guide_colourbar()` supplants the `raster` argument. + In R 4.1.0 and above, `display = "gradient"` will draw a gradient. + * The `trans` argument in scales and secondary axes has been renamed to `transform`. The `trans` argument itself is deprecated. To access the transformation from the scale, a new `get_transformation()` method is