diff --git a/R/scale-colour.r b/R/scale-colour.r index 262b8cfbfb..8797d0b7c1 100644 --- a/R/scale-colour.r +++ b/R/scale-colour.r @@ -1,9 +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()]) +#' 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: @@ -13,7 +35,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 +62,17 @@ #' # 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") +#' +#' # 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")) { if (is.function(type)) { @@ -70,7 +103,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 +118,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..50d169628b 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} @@ -30,10 +42,33 @@ scale_fill_continuous( }} } \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()}}) +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}{ @@ -65,9 +100,29 @@ 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") + +# 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()}}, \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}()}, 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}()},