From 7457cd56dc81c6f9994445d47a618d2a678681d6 Mon Sep 17 00:00:00 2001 From: Claus Wilke Date: Mon, 26 Apr 2021 11:34:30 -0500 Subject: [PATCH 1/3] Improve color scale documentation --- R/scale-colour.r | 15 +++++++++++---- R/scale-gradient.r | 5 +++-- R/scale-steps.R | 2 +- man/scale_alpha.Rd | 1 + man/scale_brewer.Rd | 1 + man/scale_colour_continuous.Rd | 32 +++++++++++++++++++++++++++++++- man/scale_gradient.Rd | 6 ++++-- man/scale_grey.Rd | 3 +-- man/scale_hue.Rd | 1 + man/scale_steps.Rd | 3 ++- 10 files changed, 56 insertions(+), 13 deletions(-) diff --git a/R/scale-colour.r b/R/scale-colour.r index 262b8cfbfb..65e240a5d0 100644 --- a/R/scale-colour.r +++ b/R/scale-colour.r @@ -3,7 +3,12 @@ #' Colour scales for continuous data default to the values of the #' `ggplot2.continuous.colour` and `ggplot2.continuous.fill` options. These #' [options()] default to `"gradient"` (i.e., [scale_colour_gradient()] and -#' [scale_fill_gradient()]) +#' [scale_fill_gradient()]). Note that both continuous and binned scales +#' are configured with the same options values. In other words, +#' the option `ggplot2.continuous.colour` controls the behavior of both +#' `scale_colour_continuous()` and `scale_colour_binned()`. To manually set +#' the colors of the scale, consider using [scale_colour_gradient()] or +#' [scale_colour_steps()]. #' #' @param ... Additional parameters passed on to the scale type #' @param type One of the following: @@ -13,7 +18,7 @@ #' @seealso [scale_colour_gradient()], [scale_colour_viridis_c()], #' [scale_colour_steps()], [scale_colour_viridis_b()], [scale_fill_gradient()], #' [scale_fill_viridis_c()], [scale_fill_steps()], and [scale_fill_viridis_b()] -#' @export +#' @family colour scales #' @rdname scale_colour_continuous #' @section Color Blindness: #' Many color palettes derived from RGB combinations (like the "rainbow" color @@ -40,6 +45,10 @@ #' # The above are equivalent to #' v + scale_fill_gradient() #' v + scale_fill_viridis_c() +#' +#' # To make a binned version of this plot +#' v + scale_fill_binned(type = "viridis") +#' @export scale_colour_continuous <- function(..., type = getOption("ggplot2.continuous.colour", default = "gradient")) { if (is.function(type)) { @@ -70,7 +79,6 @@ scale_fill_continuous <- function(..., #' @export #' @rdname scale_colour_continuous -#' @usage NULL scale_colour_binned <- function(..., type = getOption("ggplot2.binned.colour", default = getOption("ggplot2.continuous.colour", default = "gradient"))) { if (is.function(type)) { @@ -86,7 +94,6 @@ scale_colour_binned <- function(..., #' @export #' @rdname scale_colour_continuous -#' @usage NULL scale_fill_binned <- function(..., type = getOption("ggplot2.binned.fill", default = getOption("ggplot2.continuous.fill", default = "gradient"))) { if (is.function(type)) { diff --git a/R/scale-gradient.r b/R/scale-gradient.r index 9e733712e9..cca53a10dd 100644 --- a/R/scale-gradient.r +++ b/R/scale-gradient.r @@ -2,7 +2,8 @@ #' #' `scale_*_gradient` creates a two colour gradient (low-high), #' `scale_*_gradient2` creates a diverging colour gradient (low-mid-high), -#' `scale_*_gradientn` creates a n-colour gradient. +#' `scale_*_gradientn` creates a n-colour gradient. For binned variants of +#' these scales, see the [color steps][scale_colour_steps] scales. #' #' Default colours are generated with \pkg{munsell} and #' `mnsl(c("2.5PB 2/4", "2.5PB 7/10"))`. Generally, for continuous @@ -17,7 +18,7 @@ #' colour bar, or `"legend"` for discrete colour legend. #' @inheritDotParams continuous_scale -na.value -guide -aesthetics #' @seealso [scales::seq_gradient_pal()] for details on underlying -#' palette +#' palette, [scale_colour_steps()] for binned variants of these scales. #' @family colour scales #' @rdname scale_gradient #' @export diff --git a/R/scale-steps.R b/R/scale-steps.R index b5f9df301d..92677b10f3 100644 --- a/R/scale-steps.R +++ b/R/scale-steps.R @@ -16,7 +16,7 @@ #' @inheritDotParams binned_scale -aesthetics -scale_name -palette -na.value -guide -rescaler #' #' @seealso [scales::seq_gradient_pal()] for details on underlying -#' palette +#' palette, [scale_colour_gradient()] for continuous scales without binning. #' @family colour scales #' @export #' @examples diff --git a/man/scale_alpha.Rd b/man/scale_alpha.Rd index ea70477ebc..31c92b4c05 100644 --- a/man/scale_alpha.Rd +++ b/man/scale_alpha.Rd @@ -44,6 +44,7 @@ p + scale_alpha(range = c(0.4, 0.8)) \seealso{ Other colour scales: \code{\link{scale_colour_brewer}()}, +\code{\link{scale_colour_continuous}()}, \code{\link{scale_colour_gradient}()}, \code{\link{scale_colour_grey}()}, \code{\link{scale_colour_hue}()}, diff --git a/man/scale_brewer.Rd b/man/scale_brewer.Rd index d90259a514..e3e4994e5f 100644 --- a/man/scale_brewer.Rd +++ b/man/scale_brewer.Rd @@ -174,6 +174,7 @@ v + scale_fill_fermenter() \seealso{ Other colour scales: \code{\link{scale_alpha}()}, +\code{\link{scale_colour_continuous}()}, \code{\link{scale_colour_gradient}()}, \code{\link{scale_colour_grey}()}, \code{\link{scale_colour_hue}()}, diff --git a/man/scale_colour_continuous.Rd b/man/scale_colour_continuous.Rd index 816581b7df..403541338b 100644 --- a/man/scale_colour_continuous.Rd +++ b/man/scale_colour_continuous.Rd @@ -18,6 +18,18 @@ scale_fill_continuous( ..., type = getOption("ggplot2.continuous.fill", default = "gradient") ) + +scale_colour_binned( + ..., + type = getOption("ggplot2.binned.colour", default = + getOption("ggplot2.continuous.colour", default = "gradient")) +) + +scale_fill_binned( + ..., + type = getOption("ggplot2.binned.fill", default = + getOption("ggplot2.continuous.fill", default = "gradient")) +) } \arguments{ \item{...}{Additional parameters passed on to the scale type} @@ -33,7 +45,12 @@ scale_fill_continuous( Colour scales for continuous data default to the values of the \code{ggplot2.continuous.colour} and \code{ggplot2.continuous.fill} options. These \code{\link[=options]{options()}} default to \code{"gradient"} (i.e., \code{\link[=scale_colour_gradient]{scale_colour_gradient()}} and -\code{\link[=scale_fill_gradient]{scale_fill_gradient()}}) +\code{\link[=scale_fill_gradient]{scale_fill_gradient()}}). Note that both continuous and binned scales +are configured with the same options values. In other words, +the option \code{ggplot2.continuous.colour} controls the behavior of both +\code{scale_colour_continuous()} and \code{scale_colour_binned()}. To manually set +the colors of the scale, consider using \code{\link[=scale_colour_gradient]{scale_colour_gradient()}} or +\code{\link[=scale_colour_steps]{scale_colour_steps()}}. } \section{Color Blindness}{ @@ -65,9 +82,22 @@ v + scale_fill_continuous(type = "viridis") # The above are equivalent to v + scale_fill_gradient() v + scale_fill_viridis_c() + +# To make a binned version of this plot +v + scale_fill_binned(type = "viridis") } \seealso{ \code{\link[=scale_colour_gradient]{scale_colour_gradient()}}, \code{\link[=scale_colour_viridis_c]{scale_colour_viridis_c()}}, \code{\link[=scale_colour_steps]{scale_colour_steps()}}, \code{\link[=scale_colour_viridis_b]{scale_colour_viridis_b()}}, \code{\link[=scale_fill_gradient]{scale_fill_gradient()}}, \code{\link[=scale_fill_viridis_c]{scale_fill_viridis_c()}}, \code{\link[=scale_fill_steps]{scale_fill_steps()}}, and \code{\link[=scale_fill_viridis_b]{scale_fill_viridis_b()}} + +Other colour scales: +\code{\link{scale_alpha}()}, +\code{\link{scale_colour_brewer}()}, +\code{\link{scale_colour_gradient}()}, +\code{\link{scale_colour_grey}()}, +\code{\link{scale_colour_hue}()}, +\code{\link{scale_colour_steps}()}, +\code{\link{scale_colour_viridis_d}()} } +\concept{colour scales} diff --git a/man/scale_gradient.Rd b/man/scale_gradient.Rd index af7720a1e9..cfd65b24cc 100644 --- a/man/scale_gradient.Rd +++ b/man/scale_gradient.Rd @@ -204,7 +204,8 @@ to map an arbitrary range to between 0 and 1.} \description{ \verb{scale_*_gradient} creates a two colour gradient (low-high), \verb{scale_*_gradient2} creates a diverging colour gradient (low-mid-high), -\verb{scale_*_gradientn} creates a n-colour gradient. +\verb{scale_*_gradientn} creates a n-colour gradient. For binned variants of +these scales, see the \link[=scale_colour_steps]{color steps} scales. } \details{ Default colours are generated with \pkg{munsell} and @@ -266,11 +267,12 @@ ggplot(df_na, aes(x = value, y)) + } \seealso{ \code{\link[scales:seq_gradient_pal]{scales::seq_gradient_pal()}} for details on underlying -palette +palette, \code{\link[=scale_colour_steps]{scale_colour_steps()}} for binned variants of these scales. Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_brewer}()}, +\code{\link{scale_colour_continuous}()}, \code{\link{scale_colour_grey}()}, \code{\link{scale_colour_hue}()}, \code{\link{scale_colour_steps}()}, diff --git a/man/scale_grey.Rd b/man/scale_grey.Rd index a6812aafc7..f011de1970 100644 --- a/man/scale_grey.Rd +++ b/man/scale_grey.Rd @@ -4,8 +4,6 @@ \alias{scale_colour_grey} \alias{scale_fill_grey} \alias{scale_color_grey} -\alias{scale_color_gray} -\alias{scale_fill_gray} \title{Sequential grey colour scales} \usage{ scale_colour_grey( @@ -117,6 +115,7 @@ ggplot(mtcars, aes(mpg, wt)) + Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_brewer}()}, +\code{\link{scale_colour_continuous}()}, \code{\link{scale_colour_gradient}()}, \code{\link{scale_colour_hue}()}, \code{\link{scale_colour_steps}()}, diff --git a/man/scale_hue.Rd b/man/scale_hue.Rd index dc0699eceb..c8b77eb9b1 100644 --- a/man/scale_hue.Rd +++ b/man/scale_hue.Rd @@ -150,6 +150,7 @@ ggplot(mtcars, aes(mpg, wt)) + Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_brewer}()}, +\code{\link{scale_colour_continuous}()}, \code{\link{scale_colour_gradient}()}, \code{\link{scale_colour_grey}()}, \code{\link{scale_colour_steps}()}, diff --git a/man/scale_steps.Rd b/man/scale_steps.Rd index fa57f6a198..267716d478 100644 --- a/man/scale_steps.Rd +++ b/man/scale_steps.Rd @@ -225,11 +225,12 @@ ggplot(df, aes(x, y)) + } \seealso{ \code{\link[scales:seq_gradient_pal]{scales::seq_gradient_pal()}} for details on underlying -palette +palette, \code{\link[=scale_colour_gradient]{scale_colour_gradient()}} for continuous scales without binning. Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_brewer}()}, +\code{\link{scale_colour_continuous}()}, \code{\link{scale_colour_gradient}()}, \code{\link{scale_colour_grey}()}, \code{\link{scale_colour_hue}()}, From f01becb61ed578eaf5ecd9c42a571009e4407054 Mon Sep 17 00:00:00 2001 From: Claus Wilke Date: Tue, 27 Apr 2021 12:48:43 -0500 Subject: [PATCH 2/3] more detailed documentation --- R/scale-colour.r | 42 ++++++++++++++++++++++++++------- man/scale_colour_continuous.Rd | 43 +++++++++++++++++++++++++++------- man/scale_viridis.Rd | 1 + 3 files changed, 68 insertions(+), 18 deletions(-) diff --git a/R/scale-colour.r b/R/scale-colour.r index 65e240a5d0..2e6d4e35b8 100644 --- a/R/scale-colour.r +++ b/R/scale-colour.r @@ -1,14 +1,31 @@ #' Continuous and binned colour scales #' -#' Colour scales for continuous data default to the values of the -#' `ggplot2.continuous.colour` and `ggplot2.continuous.fill` options. These -#' [options()] default to `"gradient"` (i.e., [scale_colour_gradient()] and -#' [scale_fill_gradient()]). Note that both continuous and binned scales -#' are configured with the same options values. In other words, -#' the option `ggplot2.continuous.colour` controls the behavior of both -#' `scale_colour_continuous()` and `scale_colour_binned()`. To manually set -#' the colors of the scale, consider using [scale_colour_gradient()] or -#' [scale_colour_steps()]. +#' The scales `scale_colour_continuous()` and `scale_fill_continuous()` are +#' the default colour scales ggplot2 uses when continuous data values are +#' mapped onto the `colour` or `fill` aesthetics, respectively. The scales +#' `scale_colour_binned()` and `scale_fill_binned()` are equivalent scale +#' functions that assign discrete color bins to the continuous values +#' instead of using a continuous color spectrum. +#' +#' All these colour scales use the [options()] mechanism to determine +#' default settings. Continuous colour scales default to the values of the +#' `ggplot2.continuous.colour` and `ggplot2.continuous.fill` options, and +#' binned colour scales default to the values of the `ggplot2.binned.colour` +#' and `ggplot2.binned.fill` options. These option values default to +#' `"gradient"`, which means that the scale functions actually used are +#' [scale_colour_gradient()]/[scale_fill_gradient()] for continuous scales and +#' [scale_colour_steps()]/[scale_fill_steps()] for binned scales. +#' Alternative option values are `"viridis"` or a different scale function. +#' See description of the `type` argument for details. +#' +#' Note that the binned +#' colour scales will use the settings of `ggplot2.continuous.colour` and +#' `ggplot2.continuous.fill` as fallback, respectively, if +#' `ggplot2.binned.colour` or `ggplot2.binned.fill` are not set. +#' +#' These scale functions are meant to provide simple defaults. If +#' you want to manually set the colors of a scale, consider using +#' [scale_colour_gradient()] or [scale_colour_steps()]. #' #' @param ... Additional parameters passed on to the scale type #' @param type One of the following: @@ -48,6 +65,13 @@ #' #' # To make a binned version of this plot #' v + scale_fill_binned(type = "viridis") +#' +#' # Set a different default scale using the options +#' # mechanism +#' tmp <- getOption("ggplot2.continuous.fill") # store current setting +#' options(ggplot2.continuous.fill = scale_fill_distiller) +#' v +#' options(ggplot2.continuous.fill = tmp) # restore previous setting #' @export scale_colour_continuous <- function(..., type = getOption("ggplot2.continuous.colour", default = "gradient")) { diff --git a/man/scale_colour_continuous.Rd b/man/scale_colour_continuous.Rd index 403541338b..1c0c108eb5 100644 --- a/man/scale_colour_continuous.Rd +++ b/man/scale_colour_continuous.Rd @@ -42,15 +42,33 @@ scale_fill_binned( }} } \description{ -Colour scales for continuous data default to the values of the -\code{ggplot2.continuous.colour} and \code{ggplot2.continuous.fill} options. These -\code{\link[=options]{options()}} default to \code{"gradient"} (i.e., \code{\link[=scale_colour_gradient]{scale_colour_gradient()}} and -\code{\link[=scale_fill_gradient]{scale_fill_gradient()}}). Note that both continuous and binned scales -are configured with the same options values. In other words, -the option \code{ggplot2.continuous.colour} controls the behavior of both -\code{scale_colour_continuous()} and \code{scale_colour_binned()}. To manually set -the colors of the scale, consider using \code{\link[=scale_colour_gradient]{scale_colour_gradient()}} or -\code{\link[=scale_colour_steps]{scale_colour_steps()}}. +The scales \code{scale_colour_continuous()} and \code{scale_fill_continuous()} are +the default colour scales ggplot2 uses when continuous data values are +mapped onto the \code{colour} or \code{fill} aesthetics, respectively. The scales +\code{scale_colour_binned()} and \code{scale_fill_binned()} are equivalent scale +functions that assign discrete color bins to the continuous values +instead of using a continuous color spectrum. +} +\details{ +All these colour scales use the \code{\link[=options]{options()}} mechanism to determine +default settings. Continuous colour scales default to the values of the +\code{ggplot2.continuous.colour} and \code{ggplot2.continuous.fill} options, and +binned colour scales default to the values of the \code{ggplot2.binned.colour} +and \code{ggplot2.binned.fill} options. These option values default to +\code{"gradient"}, which means that the scale functions actually used are +\code{\link[=scale_colour_gradient]{scale_colour_gradient()}}/\code{\link[=scale_fill_gradient]{scale_fill_gradient()}} for continuous scales and +\code{\link[=scale_colour_steps]{scale_colour_steps()}}/\code{\link[=scale_fill_steps]{scale_fill_steps()}} for binned scales. +Alternative option values are \code{"viridis"} or a different scale function. +See description of the \code{type} argument for details. + +Note that the binned +colour scales will use the settings of \code{ggplot2.continuous.colour} and +\code{ggplot2.continuous.fill} as fallback, respectively, if +\code{ggplot2.binned.colour} or \code{ggplot2.binned.fill} are not set. + +These scale functions are meant to provide simple defaults. If +you want to manually set the colors of a scale, consider using +\code{\link[=scale_colour_gradient]{scale_colour_gradient()}} or \code{\link[=scale_colour_steps]{scale_colour_steps()}}. } \section{Color Blindness}{ @@ -85,6 +103,13 @@ v + scale_fill_viridis_c() # To make a binned version of this plot v + scale_fill_binned(type = "viridis") + +# Set a different default scale using the options +# mechanism +tmp <- getOption("ggplot2.continuous.fill") # store current setting +options(ggplot2.continuous.fill = scale_fill_distiller) +v +options(ggplot2.continuous.fill = tmp) # restore previous setting } \seealso{ \code{\link[=scale_colour_gradient]{scale_colour_gradient()}}, \code{\link[=scale_colour_viridis_c]{scale_colour_viridis_c()}}, diff --git a/man/scale_viridis.Rd b/man/scale_viridis.Rd index 03dd0dbb5f..7246c07384 100644 --- a/man/scale_viridis.Rd +++ b/man/scale_viridis.Rd @@ -176,6 +176,7 @@ v + scale_fill_viridis_b() Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_brewer}()}, +\code{\link{scale_colour_continuous}()}, \code{\link{scale_colour_gradient}()}, \code{\link{scale_colour_grey}()}, \code{\link{scale_colour_hue}()}, From 0d08407b4b284249e25cff34c40050fa50226810 Mon Sep 17 00:00:00 2001 From: Claus Wilke Date: Tue, 27 Apr 2021 12:51:15 -0500 Subject: [PATCH 3/3] manual text wrap --- R/scale-colour.r | 8 ++++---- man/scale_colour_continuous.Rd | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/R/scale-colour.r b/R/scale-colour.r index 2e6d4e35b8..8797d0b7c1 100644 --- a/R/scale-colour.r +++ b/R/scale-colour.r @@ -18,10 +18,10 @@ #' Alternative option values are `"viridis"` or a different scale function. #' See description of the `type` argument for details. #' -#' Note that the binned -#' colour scales will use the settings of `ggplot2.continuous.colour` and -#' `ggplot2.continuous.fill` as fallback, respectively, if -#' `ggplot2.binned.colour` or `ggplot2.binned.fill` are not set. +#' Note that the binned colour scales will use the settings of +#' `ggplot2.continuous.colour` and `ggplot2.continuous.fill` as fallback, +#' respectively, if `ggplot2.binned.colour` or `ggplot2.binned.fill` are +#' not set. #' #' These scale functions are meant to provide simple defaults. If #' you want to manually set the colors of a scale, consider using diff --git a/man/scale_colour_continuous.Rd b/man/scale_colour_continuous.Rd index 1c0c108eb5..50d169628b 100644 --- a/man/scale_colour_continuous.Rd +++ b/man/scale_colour_continuous.Rd @@ -61,10 +61,10 @@ and \code{ggplot2.binned.fill} options. These option values default to Alternative option values are \code{"viridis"} or a different scale function. See description of the \code{type} argument for details. -Note that the binned -colour scales will use the settings of \code{ggplot2.continuous.colour} and -\code{ggplot2.continuous.fill} as fallback, respectively, if -\code{ggplot2.binned.colour} or \code{ggplot2.binned.fill} are not set. +Note that the binned colour scales will use the settings of +\code{ggplot2.continuous.colour} and \code{ggplot2.continuous.fill} as fallback, +respectively, if \code{ggplot2.binned.colour} or \code{ggplot2.binned.fill} are +not set. These scale functions are meant to provide simple defaults. If you want to manually set the colors of a scale, consider using