diff --git a/R/scale-.r b/R/scale-.r index e1a81f8f2b..9ccd77b42d 100644 --- a/R/scale-.r +++ b/R/scale-.r @@ -38,17 +38,21 @@ #' Use `NA` to refer to the existing minimum or maximum #' - A function that accepts the existing (automatic) limits and returns #' new limits -#' -#' Note that setting limits on positional scales will **remove** data outside of the limits. -#' If the purpose is to zoom, use the limit argument in the coordinate system (see [coord_cartesian()]). +#' Note that setting limits on positional scales will **remove** data outside of the limits. +#' If the purpose is to zoom, use the limit argument in the coordinate system +#' (see [coord_cartesian()]). #' @param rescaler A function used to scale the input values to the #' range \[0, 1]. This is always [scales::rescale()], except for #' diverging and n colour gradients (i.e., [scale_colour_gradient2()], #' [scale_colour_gradientn()]). The `rescaler` is ignored by position #' scales, which ways use [scales::rescale()]. -#' @param oob Function that handles limits outside of the scale limits -#' (out of bounds). The default ([scales::censor()]) replaces out of +#' @param oob One of: +#' - Function that handles limits outside of the scale limits +#' (out of bounds). +#' - The default ([scales::censor()]) replaces out of #' bounds values with `NA`. +#' - [scales::squish()] for squishing out of bounds values into range. +#' - [scales::squish_infinite()] for squishing infitite values into range. #' @param na.value Missing values will be replaced with this value. #' @param trans For continuous scales, the name of a transformation object #' or the object itself. Built-in transformations include "asn", "atanh", diff --git a/man/continuous_scale.Rd b/man/continuous_scale.Rd index b69e36b262..6c5ee2a3fb 100644 --- a/man/continuous_scale.Rd +++ b/man/continuous_scale.Rd @@ -61,10 +61,10 @@ as output Use \code{NA} to refer to the existing minimum or maximum \item A function that accepts the existing (automatic) limits and returns new limits -} - 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()}}).} +If the purpose is to zoom, use the limit argument in the coordinate system +(see \code{\link[=coord_cartesian]{coord_cartesian()}}). +}} \item{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 @@ -72,9 +72,15 @@ diverging and n colour gradients (i.e., \code{\link[=scale_colour_gradient2]{sca \code{\link[=scale_colour_gradientn]{scale_colour_gradientn()}}). The \code{rescaler} is ignored by position scales, which ways use \code{\link[scales:rescale]{scales::rescale()}}.} -\item{oob}{Function that handles limits outside of the scale limits -(out of bounds). The default (\code{\link[scales:censor]{scales::censor()}}) replaces out of -bounds values with \code{NA}.} +\item{oob}{One of: +\itemize{ +\item Function that handles limits outside of the scale limits +(out of bounds). +\item The default (\code{\link[scales:censor]{scales::censor()}}) replaces out of +bounds values with \code{NA}. +\item \code{\link[scales:squish]{scales::squish()}} for squishing out of bounds values into range. +\item \code{\link[scales:squish_infinite]{scales::squish_infinite()}} for squishing infitite values into range. +}} \item{expand}{For position scales, a vector of range expansion constants used to add some padding around the data to ensure that they are placed some distance diff --git a/man/scale_continuous.Rd b/man/scale_continuous.Rd index 55133ea46a..ef810c005f 100644 --- a/man/scale_continuous.Rd +++ b/man/scale_continuous.Rd @@ -75,10 +75,10 @@ as output Use \code{NA} to refer to the existing minimum or maximum \item A function that accepts the existing (automatic) limits and returns new limits -} - 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()}}).} +If the purpose is to zoom, use the limit argument in the coordinate system +(see \code{\link[=coord_cartesian]{coord_cartesian()}}). +}} \item{expand}{For position scales, a vector of range expansion constants used to add some padding around the data to ensure that they are placed some distance @@ -87,9 +87,15 @@ to generate the values for the \code{expand} argument. The defaults are to expand the scale by 5\% on each side for continuous variables, and by 0.6 units on each side for discrete variables.} -\item{oob}{Function that handles limits outside of the scale limits -(out of bounds). The default (\code{\link[scales:censor]{scales::censor()}}) replaces out of -bounds values with \code{NA}.} +\item{oob}{One of: +\itemize{ +\item Function that handles limits outside of the scale limits +(out of bounds). +\item The default (\code{\link[scales:censor]{scales::censor()}}) replaces out of +bounds values with \code{NA}. +\item \code{\link[scales:squish]{scales::squish()}} for squishing out of bounds values into range. +\item \code{\link[scales:squish_infinite]{scales::squish_infinite()}} for squishing infitite values into range. +}} \item{na.value}{Missing values will be replaced with this value.} diff --git a/man/scale_date.Rd b/man/scale_date.Rd index 30fdd48422..26c0f32b8d 100644 --- a/man/scale_date.Rd +++ b/man/scale_date.Rd @@ -95,10 +95,10 @@ like "2 weeks", or "10 years". If both \code{minor_breaks} and Use \code{NA} to refer to the existing minimum or maximum \item A function that accepts the existing (automatic) limits and returns new limits -} - 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()}}).} +If the purpose is to zoom, use the limit argument in the coordinate system +(see \code{\link[=coord_cartesian]{coord_cartesian()}}). +}} \item{expand}{For position scales, a vector of range expansion constants used to add some padding around the data to ensure that they are placed some distance @@ -115,9 +115,15 @@ expand the scale by 5\% on each side for continuous variables, and by \item{timezone}{The timezone to use for display on the axes. The default (\code{NULL}) uses the timezone encoded in the data.} -\item{oob}{Function that handles limits outside of the scale limits -(out of bounds). The default (\code{\link[scales:censor]{scales::censor()}}) replaces out of -bounds values with \code{NA}.} +\item{oob}{One of: +\itemize{ +\item Function that handles limits outside of the scale limits +(out of bounds). +\item The default (\code{\link[scales:censor]{scales::censor()}}) replaces out of +bounds values with \code{NA}. +\item \code{\link[scales:squish]{scales::squish()}} for squishing out of bounds values into range. +\item \code{\link[scales:squish_infinite]{scales::squish_infinite()}} for squishing infitite values into range. +}} \item{na.value}{Missing values will be replaced with this value.} } diff --git a/man/scale_gradient.Rd b/man/scale_gradient.Rd index a177a96a3f..9569378fd7 100644 --- a/man/scale_gradient.Rd +++ b/man/scale_gradient.Rd @@ -85,18 +85,24 @@ as output Use \code{NA} to refer to the existing minimum or maximum \item A function that accepts the existing (automatic) limits and returns new limits -} - 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()}}).} +If the purpose is to zoom, use the limit argument in the coordinate system +(see \code{\link[=coord_cartesian]{coord_cartesian()}}). +}} \item{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 ways use \code{\link[scales:rescale]{scales::rescale()}}.} - \item{oob}{Function that handles limits outside of the scale limits -(out of bounds). The default (\code{\link[scales:censor]{scales::censor()}}) replaces out of -bounds values with \code{NA}.} + \item{oob}{One of: +\itemize{ +\item Function that handles limits outside of the scale limits +(out of bounds). +\item The default (\code{\link[scales:censor]{scales::censor()}}) replaces out of +bounds values with \code{NA}. +\item \code{\link[scales:squish]{scales::squish()}} for squishing out of bounds values into range. +\item \code{\link[scales:squish_infinite]{scales::squish_infinite()}} for squishing infitite values into range. +}} \item{trans}{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", diff --git a/man/scale_size.Rd b/man/scale_size.Rd index e4bed55520..17614721fc 100644 --- a/man/scale_size.Rd +++ b/man/scale_size.Rd @@ -54,10 +54,10 @@ as output Use \code{NA} to refer to the existing minimum or maximum \item A function that accepts the existing (automatic) limits and returns new limits -} - 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()}}).} +If the purpose is to zoom, use the limit argument in the coordinate system +(see \code{\link[=coord_cartesian]{coord_cartesian()}}). +}} \item{range}{a numeric vector of length 2 that specifies the minimum and maximum size of the plotting symbol after transformation.} @@ -116,13 +116,19 @@ as output Use \code{NA} to refer to the existing minimum or maximum \item A function that accepts the existing (automatic) limits and returns new limits -} - 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{oob}{Function that handles limits outside of the scale limits -(out of bounds). The default (\code{\link[scales:censor]{scales::censor()}}) replaces out of -bounds values with \code{NA}.} +If the purpose is to zoom, use the limit argument in the coordinate system +(see \code{\link[=coord_cartesian]{coord_cartesian()}}). +}} + \item{oob}{One of: +\itemize{ +\item Function that handles limits outside of the scale limits +(out of bounds). +\item The default (\code{\link[scales:censor]{scales::censor()}}) replaces out of +bounds values with \code{NA}. +\item \code{\link[scales:squish]{scales::squish()}} for squishing out of bounds values into range. +\item \code{\link[scales:squish_infinite]{scales::squish_infinite()}} for squishing infitite values into range. +}} \item{na.value}{Missing values will be replaced with this value.} \item{trans}{For continuous scales, the name of a transformation object or the object itself. Built-in transformations include "asn", "atanh",