diff --git a/R/scale-colour.R b/R/scale-colour.R index 5f9faab7df..3b4122f7f0 100644 --- a/R/scale-colour.R +++ b/R/scale-colour.R @@ -26,14 +26,13 @@ #' * a single string naming a palette. #' * a palette function that when called with a numeric vector with values #' between 0 and 1 returns the corresponding output values. -#' @param ... Additional parameters passed on to the scale type +#' @inheritDotParams continuous_scale -scale_name -trans -minor_breaks -expand +#' @inheritDotParams binned_scale -scale_name -trans -expand #' @param type `r lifecycle::badge("superseded")` One of the following: #' * "gradient" (the default) #' * "viridis" #' * A function that returns a continuous colour scale. -#' @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()] +#' @seealso [continuous_scale()] and [binned_scale()] #' #' The documentation on [colour aesthetics][aes_colour_fill_alpha]. #' @family colour scales @@ -173,7 +172,7 @@ scale_fill_binned <- function(..., palette = NULL, aesthetics = "fill", guide = #' * a single string naming a palette. #' * a palette function that when called with a single integer argument (the #' number of levels in the scale) returns the values that they should take. -#' @param ... Additional parameters passed on to the scale type, +#' @inheritDotParams discrete_scale -scale_name -expand -position -minor_breaks #' @inheritParams discrete_scale #' @param type `r lifecycle::badge("superseded")` The preferred mechanism for #' setting the default palette is by using the theme. For example: @@ -190,6 +189,8 @@ scale_fill_binned <- function(..., palette = NULL, aesthetics = "fill", guide = #' * A function that returns a discrete colour/fill scale (e.g., [scale_fill_hue()], #' [scale_fill_brewer()], etc). #' @export +#' @seealso [discrete_scale()] +#' @family colour scales #' @seealso #' The `r link_book("discrete colour scales section", "scales-colour#sec-colour-discrete")` #' @examples diff --git a/man/scale_alpha.Rd b/man/scale_alpha.Rd index 7c4a5784df..953d42b4f2 100644 --- a/man/scale_alpha.Rd +++ b/man/scale_alpha.Rd @@ -68,6 +68,7 @@ The \href{https://ggplot2-book.org/scales-colour#sec-scales-alpha}{alpha scales Other colour scales: \code{\link{scale_colour_brewer}()}, \code{\link{scale_colour_continuous}()}, +\code{\link{scale_colour_discrete}()}, \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 f9c6c124be..fb554e2bf7 100644 --- a/man/scale_brewer.Rd +++ b/man/scale_brewer.Rd @@ -196,6 +196,7 @@ The \href{https://ggplot2-book.org/scales-colour#brewer-scales}{brewer scales se Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_continuous}()}, +\code{\link{scale_colour_discrete}()}, \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 d9ab49b684..a4c285964a 100644 --- a/man/scale_colour_continuous.Rd +++ b/man/scale_colour_continuous.Rd @@ -46,7 +46,97 @@ scale_fill_binned( ) } \arguments{ -\item{...}{Additional parameters passed on to the scale type} +\item{...}{ + Arguments passed on to \code{\link[=continuous_scale]{continuous_scale}}, \code{\link[=binned_scale]{binned_scale}} + \describe{ + \item{\code{name}}{The name of the scale. Used as the axis or legend title. If +\code{waiver()}, the default, the name of the scale is taken from the first +mapping used for that aesthetic. If \code{NULL}, the legend title will be +omitted.} + \item{\code{breaks}}{One of: +\itemize{ +\item \code{NULL} for no breaks +\item \code{waiver()} for the default breaks computed by the +\link[scales:new_transform]{transformation object} +\item A numeric vector of positions +\item A function that takes the limits as input and returns breaks +as output (e.g., a function returned by \code{\link[scales:breaks_extended]{scales::extended_breaks()}}). +Note that for position scales, limits are provided after scale expansion. +Also accepts rlang \link[rlang:as_function]{lambda} function notation. +}} + \item{\code{n.breaks}}{An integer guiding the number of major breaks. The algorithm +may choose a slightly different number to ensure nice break labels. Will +only have an effect if \code{breaks = waiver()}. Use \code{NULL} to use the default +number of breaks given by the transformation.} + \item{\code{labels}}{One of the options below. Please note that when \code{labels} is a +vector, it is highly recommended to also set the \code{breaks} argument as a +vector to protect against unintended mismatches. +\itemize{ +\item \code{NULL} for no labels +\item \code{waiver()} for the default labels computed by the +transformation object +\item A character vector giving labels (must be same length as \code{breaks}) +\item An expression vector (must be the same length as breaks). See ?plotmath for details. +\item A function that takes the breaks as input and returns labels +as output. Also accepts rlang \link[rlang:as_function]{lambda} function +notation. +}} + \item{\code{limits}}{One of: +\itemize{ +\item \code{NULL} to use the default scale range +\item A numeric vector of length two providing limits of the scale. +Use \code{NA} to refer to the existing minimum or maximum +\item A function that accepts the existing (automatic) limits and returns +new limits. Also accepts rlang \link[rlang:as_function]{lambda} function +notation. +Note that setting limits on positional scales will \strong{remove} data outside of the limits. +If the purpose is to zoom, use the limit argument in the coordinate system +(see \code{\link[=coord_cartesian]{coord_cartesian()}}). +}} + \item{\code{rescaler}}{A function used to scale the input values to the +range [0, 1]. This is always \code{\link[scales:rescale]{scales::rescale()}}, except for +diverging and n colour gradients (i.e., \code{\link[=scale_colour_gradient2]{scale_colour_gradient2()}}, +\code{\link[=scale_colour_gradientn]{scale_colour_gradientn()}}). The \code{rescaler} is ignored by position +scales, which always use \code{\link[scales:rescale]{scales::rescale()}}. Also accepts rlang +\link[rlang:as_function]{lambda} function notation.} + \item{\code{oob}}{One of: +\itemize{ +\item Function that handles limits outside of the scale limits +(out of bounds). Also accepts rlang \link[rlang:as_function]{lambda} +function notation. +\item The default (\code{\link[scales:oob]{scales::censor()}}) replaces out of +bounds values with \code{NA}. +\item \code{\link[scales:oob]{scales::squish()}} for squishing out of bounds values into range. +\item \code{\link[scales:oob]{scales::squish_infinite()}} for squishing infinite values into range. +}} + \item{\code{transform}}{For continuous scales, the name of a transformation object +or the object itself. Built-in transformations include "asn", "atanh", +"boxcox", "date", "exp", "hms", "identity", "log", "log10", "log1p", "log2", +"logit", "modulus", "probability", "probit", "pseudo_log", "reciprocal", +"reverse", "sqrt" and "time". + +A transformation object bundles together a transform, its inverse, +and methods for generating breaks and labels. Transformation objects +are defined in the scales package, and are called \verb{transform_}. If +transformations require arguments, you can call them from the scales +package, e.g. \code{\link[scales:transform_boxcox]{scales::transform_boxcox(p = 2)}}. +You can create your own transformation with \code{\link[scales:new_transform]{scales::new_transform()}}.} + \item{\code{position}}{For position scales, The position of the axis. +\code{left} or \code{right} for y axes, \code{top} or \code{bottom} for x axes.} + \item{\code{call}}{The \code{call} used to construct the scale for reporting messages.} + \item{\code{super}}{The super class to use for the constructed scale} + \item{\code{nice.breaks}}{Logical. Should breaks be attempted placed at nice values +instead of exactly evenly spaced between the limits. If \code{TRUE} (default) +the scale will ask the transformation object to create breaks, and this +may result in a different number of breaks than requested. Ignored if +breaks are given explicitly.} + \item{\code{right}}{Should the intervals be closed on the right (\code{TRUE}, default) or +should the intervals be closed on the left (\code{FALSE})? 'Closed on the right' +means that values at break positions are part of the lower bin (open on the +left), whereas they are part of the upper bin when intervals are closed on +the left (open on the right).} + \item{\code{show.limits}}{should the limits of the scale appear as ticks} + }} \item{palette}{One of the following: \itemize{ @@ -136,9 +226,7 @@ p + scale_colour_binned() + theme_set(old) } \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()}} +\code{\link[=continuous_scale]{continuous_scale()}} and \code{\link[=binned_scale]{binned_scale()}} The documentation on \link[=aes_colour_fill_alpha]{colour aesthetics}. @@ -147,6 +235,7 @@ The \href{https://ggplot2-book.org/scales-colour#sec-colour-continuous}{continuo Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_brewer}()}, +\code{\link{scale_colour_discrete}()}, \code{\link{scale_colour_gradient}()}, \code{\link{scale_colour_grey}()}, \code{\link{scale_colour_hue}()}, diff --git a/man/scale_colour_discrete.Rd b/man/scale_colour_discrete.Rd index 87c8ad6f1c..7ba0f6bd1f 100644 --- a/man/scale_colour_discrete.Rd +++ b/man/scale_colour_discrete.Rd @@ -23,7 +23,56 @@ scale_fill_discrete( ) } \arguments{ -\item{...}{Additional parameters passed on to the scale type,} +\item{...}{ + Arguments passed on to \code{\link[=discrete_scale]{discrete_scale}} + \describe{ + \item{\code{breaks}}{One of: +\itemize{ +\item \code{NULL} for no breaks +\item \code{waiver()} for the default breaks (the scale limits) +\item A character vector of breaks +\item A function that takes the limits as input and returns breaks +as output. Also accepts rlang \link[rlang:as_function]{lambda} function +notation. +}} + \item{\code{limits}}{One of: +\itemize{ +\item \code{NULL} to use the default scale values +\item A character vector that defines possible values of the scale and their +order +\item A function that accepts the existing (automatic) values and returns +new ones. Also accepts rlang \link[rlang:as_function]{lambda} function +notation. +}} + \item{\code{drop}}{Should unused factor levels be omitted from the scale? +The default, \code{TRUE}, uses the levels that appear in the data; +\code{FALSE} includes the levels in the factor. Please note that to display +every level in a legend, the layer should use \code{show.legend = TRUE}.} + \item{\code{na.translate}}{Unlike continuous scales, discrete scales can easily show +missing values, and do so by default. If you want to remove missing values +from a discrete scale, specify \code{na.translate = FALSE}.} + \item{\code{name}}{The name of the scale. Used as the axis or legend title. If +\code{waiver()}, the default, the name of the scale is taken from the first +mapping used for that aesthetic. If \code{NULL}, the legend title will be +omitted.} + \item{\code{labels}}{One of the options below. Please note that when \code{labels} is a +vector, it is highly recommended to also set the \code{breaks} argument as a +vector to protect against unintended mismatches. +\itemize{ +\item \code{NULL} for no labels +\item \code{waiver()} for the default labels computed by the +transformation object +\item A character vector giving labels (must be same length as \code{breaks}) +\item An expression vector (must be the same length as breaks). See ?plotmath for details. +\item A function that takes the breaks as input and returns labels +as output. Also accepts rlang \link[rlang:as_function]{lambda} function +notation. +}} + \item{\code{guide}}{A function used to create a guide or its name. See +\code{\link[=guides]{guides()}} for more information.} + \item{\code{call}}{The \code{call} used to construct the scale for reporting messages.} + \item{\code{super}}{The super class to use for the constructed scale} + }} \item{palette}{One of the following: \itemize{ @@ -81,5 +130,20 @@ p theme_set(old) } \seealso{ +\code{\link[=discrete_scale]{discrete_scale()}} + The \href{https://ggplot2-book.org/scales-colour#sec-colour-discrete}{discrete colour scales section} of the online ggplot2 book. + +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}()}, +\code{\link{scale_colour_identity}()}, +\code{\link{scale_colour_manual}()}, +\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 6d0b5c8c15..781b5576bb 100644 --- a/man/scale_gradient.Rd +++ b/man/scale_gradient.Rd @@ -299,6 +299,7 @@ Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_brewer}()}, \code{\link{scale_colour_continuous}()}, +\code{\link{scale_colour_discrete}()}, \code{\link{scale_colour_grey}()}, \code{\link{scale_colour_hue}()}, \code{\link{scale_colour_identity}()}, diff --git a/man/scale_grey.Rd b/man/scale_grey.Rd index 9d838508dc..f45818cdb4 100644 --- a/man/scale_grey.Rd +++ b/man/scale_grey.Rd @@ -129,6 +129,7 @@ Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_brewer}()}, \code{\link{scale_colour_continuous}()}, +\code{\link{scale_colour_discrete}()}, \code{\link{scale_colour_gradient}()}, \code{\link{scale_colour_hue}()}, \code{\link{scale_colour_identity}()}, diff --git a/man/scale_hue.Rd b/man/scale_hue.Rd index 0a0aba8fcd..e60cb98aec 100644 --- a/man/scale_hue.Rd +++ b/man/scale_hue.Rd @@ -165,6 +165,7 @@ Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_brewer}()}, \code{\link{scale_colour_continuous}()}, +\code{\link{scale_colour_discrete}()}, \code{\link{scale_colour_gradient}()}, \code{\link{scale_colour_grey}()}, \code{\link{scale_colour_identity}()}, diff --git a/man/scale_identity.Rd b/man/scale_identity.Rd index 68100940e0..73cc9c19a8 100644 --- a/man/scale_identity.Rd +++ b/man/scale_identity.Rd @@ -138,6 +138,7 @@ Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_brewer}()}, \code{\link{scale_colour_continuous}()}, +\code{\link{scale_colour_discrete}()}, \code{\link{scale_colour_gradient}()}, \code{\link{scale_colour_grey}()}, \code{\link{scale_colour_hue}()}, diff --git a/man/scale_manual.Rd b/man/scale_manual.Rd index 75677d54d0..933ea25975 100644 --- a/man/scale_manual.Rd +++ b/man/scale_manual.Rd @@ -230,6 +230,7 @@ Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_brewer}()}, \code{\link{scale_colour_continuous}()}, +\code{\link{scale_colour_discrete}()}, \code{\link{scale_colour_gradient}()}, \code{\link{scale_colour_grey}()}, \code{\link{scale_colour_hue}()}, diff --git a/man/scale_steps.Rd b/man/scale_steps.Rd index 9f6740a561..126450bca2 100644 --- a/man/scale_steps.Rd +++ b/man/scale_steps.Rd @@ -249,6 +249,7 @@ Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_brewer}()}, \code{\link{scale_colour_continuous}()}, +\code{\link{scale_colour_discrete}()}, \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 35784d7a1d..165d24b062 100644 --- a/man/scale_viridis.Rd +++ b/man/scale_viridis.Rd @@ -200,6 +200,7 @@ Other colour scales: \code{\link{scale_alpha}()}, \code{\link{scale_colour_brewer}()}, \code{\link{scale_colour_continuous}()}, +\code{\link{scale_colour_discrete}()}, \code{\link{scale_colour_gradient}()}, \code{\link{scale_colour_grey}()}, \code{\link{scale_colour_hue}()},