| pretty {base} | R Documentation |
Pretty Breakpoints
Description
Compute a sequence of about n+1 equally spaced ‘round’
values which cover the range of the values in x.
The values are chosen so that they are 1, 2 or 5 times a power of 10.
Usage
pretty(x, ...)
## Default S3 method:
pretty(x, n = 5, min.n = n %/% 3, shrink.sml = 0.75,
high.u.bias = 1.5, u5.bias = .5 + 1.5*high.u.bias,
eps.correct = 0, f.min = 2^-20, bounds = TRUE, ...)
.pretty(x, n = 5L, min.n = n %/% 3, shrink.sml = 0.75,
high.u.bias = 1.5, u5.bias = .5 + 1.5*high.u.bias,
eps.correct = 0L, f.min = 2^-20, bounds = TRUE)
Arguments
x |
an object coercible to numeric by |
n |
integer giving the desired number of intervals. Non-integer values are rounded down. |
min.n |
nonnegative integer giving the minimal number of
intervals. If |
shrink.sml |
positive number, a factor (smaller than one)
by which a default scale is shrunk in the case when
|
high.u.bias |
non-negative numeric, typically |
u5.bias |
non-negative numeric
multiplier favoring factor 5 over 2. Default and ‘optimal’:
|
eps.correct |
integer code, one of {0,1,2}. If non-0, an
epsilon correction is made at the boundaries such that
the result boundaries will be outside |
f.min |
positive factor multiplied by |
bounds |
a |
... |
further arguments for methods; unused in default method. |
Details
pretty ignores non-finite values in x.
Let d <- max(x) - min(x) \ge 0.
If d is not (very close) to 0, we let c <- d/n,
otherwise more or less c <- max(abs(range(x)))*shrink.sml / min.n.
Then, the 10 base b is
10^{\lfloor{\log_{10}(c)}\rfloor} such
that b \le c < 10b.
Now determine the basic unit u as one of
\{1,2,5,10\} b, depending on
c/b \in [1,10)
and the two ‘bias’ coefficients, h
=high.u.bias and f =u5.bias.
.........
R's graphics engine GEPretty() C function calls
R_pretty() and is used in both packages graphics and
grid (and hence lattice, ggplot2, etc.) for
axis range and tick computations. For these, partly for back
compatibility reasons, the optional arguments are set, corresponding to
(min.n = 1, shrink.sml = 0.25, high.u.bias = 0.8, u5.bias = 1.7, f.min = 1.125, eps.correct = 2, bounds = FALSE)
Value
pretty() returns an numeric vector of approximately
n increasing numbers which are “pretty” in decimal notation.
(in extreme range cases, the numbers can no longer be “pretty”
given the other constraints; e.g., for pretty(..)
For ease of investigating the underlying C R_pretty()
function, .pretty() returns a named list. By
default, when bounds=TRUE, the entries are l, u,
and n, whereas for bounds=FALSE, they are
ns, nu, n, and (a “pretty”) unit
where the n*'s are integer valued (but only n is of class
integer). Programmers may use this to create pretty
sequence (iterator) objects.
References
Becker R. A., Chambers J. M., Wilks A. R. (1988). The New S Language. Chapman and Hall/CRC, London. ISBN 053409192X.
See Also
axTicks for the computation of pretty axis tick
locations in plots, particularly on the log scale.
Examples
pretty(1:15) # 0 2 4 6 8 10 12 14 16
pretty(1:15, high.u.bias = 2) # 0 5 10 15
pretty(1:15, n = 4) # 0 5 10 15
pretty(1:15 * 2) # 0 5 10 15 20 25 30
pretty(1:20) # 0 5 10 15 20
pretty(1:20, n = 2) # 0 10 20
pretty(1:20, n = 10) # 0 2 4 ... 20
for(k in 5:11) {
cat("k=", k, ": "); print(diff(range(pretty(100 + c(0, pi*10^-k)))))}
##-- more bizarre, when min(x) == max(x):
pretty(pi)
add.names <- function(v) { names(v) <- paste(v); v}
utils::str(lapply(add.names(-10:20), pretty))
## min.n = 0 returns a length-1 vector "if pretty":
utils::str(lapply(add.names(0:20), pretty, min.n = 0))
sapply( add.names(0:20), pretty, min.n = 4)
pretty(1.234e100)
pretty(1001.1001)
pretty(1001.1001, shrink.sml = 0.2)
for(k in -7:3)
cat("shrink=", formatC(2^k, width = 9),":",
formatC(pretty(1001.1001, shrink.sml = 2^k), width = 6),"\n")