oob: Out of bounds handling

In r-lib/scales: Scale Functions for Visualization

Out of bounds handling

Description

This set of functions modify data values outside a given range. The ⁠oob_*()⁠ functions are designed to be passed as the oob argument of ggplot2 continuous and binned scales, with oob_discard being an exception.

These functions affect out of bounds values in the following ways:

• oob_censor() replaces out of bounds values with NAs. This is the default oob argument for continuous scales.

• oob_censor_any() acts like oob_censor(), but also replaces infinite values with NAs.

• oob_squish() replaces out of bounds values with the nearest limit. This is the default oob argument for binned scales.

• oob_squish_any() acts like oob_squish(), but also replaces infinite values with the nearest limit.

• oob_squish_infinite() only replaces infinite values by the nearest limit.

• oob_keep() does not adjust out of bounds values. In position scales, behaves as zooming limits without data removal.

• oob_discard() removes out of bounds values from the input. Not suitable for ggplot2 scales.

Usage

oob_censor(x, range = c(0, 1), only.finite = TRUE)

oob_censor_any(x, range = c(0, 1))

oob_discard(x, range = c(0, 1))

oob_squish(x, range = c(0, 1), only.finite = TRUE)

oob_squish_any(x, range = c(0, 1))

oob_squish_infinite(x, range = c(0, 1))

oob_keep(x, range = c(0, 1))

censor(x, range = c(0, 1), only.finite = TRUE)

discard(x, range = c(0, 1))

squish(x, range = c(0, 1), only.finite = TRUE)

squish_infinite(x, range = c(0, 1))

Arguments

x	A numeric vector of values to modify.
range	A numeric vector of length two giving the minimum and maximum limit of the desired output range respectively.
only.finite	A logical of length one. When TRUE, only finite values are altered. When FALSE, also infinite values are altered.

Details

The oob_censor_any() and oob_squish_any() functions are the same as oob_censor() and oob_squish() with the only.finite argument set to FALSE.

Replacing position values with NAs, as oob_censor() does, will typically lead to removal of those datapoints in ggplot.

Setting ggplot coordinate limits is equivalent to using oob_keep() in position scales.

Value

Most oob_() functions return a vector of numerical values of the same length as the x argument, wherein out of bounds values have been modified. Only oob_discard() returns a vector of less than or of equal length to the x argument.

Old interface

censor(), squish(), squish_infinite() and discard() are no longer recommended; please use oob_censor(), oob_squish(), oob_squish_infinite() and oob_discard() instead.

Author(s)

oob_squish(): Homer Strong [e-mail]

Examples

# Censoring replaces out of bounds values with NAs
oob_censor(c(-Inf, -1, 0.5, 1, 2, NA, Inf))
oob_censor_any(c(-Inf, -1, 0.5, 1, 2, NA, Inf))

# Squishing replaces out of bounds values with the nearest range limit
oob_squish(c(-Inf, -1, 0.5, 1, 2, NA, Inf))
oob_squish_any(c(-Inf, -1, 0.5, 1, 2, NA, Inf))
oob_squish_infinite(c(-Inf, -1, 0.5, 1, 2, NA, Inf))

# Keeping does not alter values
oob_keep(c(-Inf, -1, 0.5, 1, 2, NA, Inf))

# Discarding will remove out of bounds values
oob_discard(c(-Inf, -1, 0.5, 1, 2, NA, Inf))

r-lib/scales documentation built on June 14, 2025, 10:56 p.m.