pretty                 package: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, 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)

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 numeric by a 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'.

Details:

     'pretty' ignores non-finite values in 'x'.

     Let 'd <- max(x) - min(x)' >= 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^(floor(log10(c))) such that b <= 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'.

     .........

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

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, h=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))
     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 = .2)
     for(k in -7:3)
       cat("shrink=", formatC(2^k, width=9),":",
           formatC(pretty(1001.1001, shrink.sml = 2^k), width=6),"\n")

