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, ...)

.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 as.numeric. 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 min.n == 0, pretty(.) may return a single value. shrink.sml positive number, a factor (smaller than one) by which a default scale is shrunk in the case when range(x) is very small (usually 0). high.u.bias non-negative numeric, typically > 1. The interval unit is determined as {1,2,5,10} times b, a power of 10. Larger high.u.bias values favor larger units. u5.bias non-negative numeric multiplier favoring factor 5 over 2. Default and ‘optimal’: u5.bias = .5 + 1.5*high.u.bias. 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 range(x); in the small case, the correction is only done if eps.correct >= 2. f.min positive factor multiplied by .Machine\$double.xmin to get the smallest “acceptable” cell c_m which determines the unit of the algorithm. Smaller cell values are set to c_n signalling a warning about being “corrected”. New from R 4.2.0,: previously f.min = 20 was hardcoded in the algorithm. bounds a logical indicating if the resulting vector should cover the full range(x), i.e., strictly include the bounds of x. New from R 4.2.0, allowing bound=FALSE to reproduce how R's graphics engine computes axis tick locations (in GEPretty()). ... further arguments for methods.

### 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.

.........

### 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. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.

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}