[Rd] A 'pretty' function for POSIXt objects

[Don MacQueen]

I have written a set of functions for POSIXt objects that I would 
like to offer for consideration for use in base R. They augment and 
extend existing functions. Briefly,

##   pretty.ct         function(x,specs=pretty.ct.specs)
##   round.ct          function(x, tstr='1 min' )
##   axis.ct           function(side,x,specs=NULL,...)
##   parse.timeint     function(dv)
##   parse.tstr        function(tstr)
##   pretty.ct.specs   default value for the 'specs' argument of pretty.ct()

pretty.ct() is a 'pretty' function for POSIXt objects. It implements 
my idea of what is pretty, which is dependent on the time scale, and 
with the default specs prefers hours in multiples of 3, 6, or 12, and 
days in multiples of 7 or 14.

round.ct() serves the same purpose as round.POSIXt(), but allows 
rounding to multiples of the time unit, i.e., '15 min' , '2 hours', 
and the like.

axis.ct() serves the same purpose as axis.POSIXct() but selects tick 
values and intervals using pretty.ct(). Surprisingly, axis.ct() is 
significantly faster than axis.POSIXct() when passed a long vector.

The two parse functions translate strings like '10 min' or '36 h' to 
other more useable forms. These are based on code found in an early 
version of seq.POSIXct(), written, I believe, by Prof. Ripley.

A few examples are below.

If there is interest, I can send the source code, and will write Rd 
files for them.

-Don

>  hrs <- 3600
>  dys <- 24*hrs

##
## time range 60 hours
## pretty.ct() chooses 3 hours as a pretty interval
##
nhr <- 60
>  t1 <- ISOdatetime(2002,6,14,0,0,0)+hrs*runif(5,0,nhr)
>  pretty.ct(t1)
  [1] "2002-06-15 03:00:00 PDT" "2002-06-15 06:00:00 PDT" "2002-06-15 
09:00:00 PDT" "2002-06-15 12:00:00 PDT"
  [5] "2002-06-15 15:00:00 PDT" "2002-06-15 18:00:00 PDT" "2002-06-15 
21:00:00 PDT" "2002-06-16 00:00:00 PDT"
  [9] "2002-06-16 03:00:00 PDT" "2002-06-16 06:00:00 PDT" "2002-06-16 
09:00:00 PDT"

>  t1 <- sort(t1)
>  cbind(format(t1),format(round.ct(t1,'6 h')))
      [,1]                  [,2]
[1,] "2002-06-15 02:49:03" "2002-06-15 00:00:00"
[2,] "2002-06-15 04:40:25" "2002-06-15 06:00:00"
[3,] "2002-06-15 11:12:29" "2002-06-15 12:00:00"
[4,] "2002-06-15 14:47:43" "2002-06-15 12:00:00"
[5,] "2002-06-16 09:01:32" "2002-06-16 12:00:00"

##
## time range 65 days
## pretty.ct() chooses 1 week as a pretty interval
##
>  ndy <- 65
>  t2 <- ISOdatetime(2002,6,24,0,0,0)+ndy*dys*(0:5)/5
>  pretty.ct(t2)
  [1] "2002-06-23 PDT" "2002-06-30 PDT" "2002-07-07 PDT" "2002-07-14 
PDT" "2002-07-21 PDT" "2002-07-28 PDT" "2002-08-04 PDT"
  [8] "2002-08-11 PDT" "2002-08-18 PDT" "2002-08-25 PDT"
>  cbind(format(t2),format(round.ct(t2,'1 w')))
      [,1]         [,2]
[1,] "2002-06-24" "2002-06-23"
[2,] "2002-07-07" "2002-07-07"
[3,] "2002-07-20" "2002-07-21"
[4,] "2002-08-02" "2002-08-04"
[5,] "2002-08-15" "2002-08-18"
[6,] "2002-08-28" "2002-08-25"

##
## the parse functions
##
>  parse.tstr('36 h')
$secs
[1] 129600

$nunits
[1] 36

$units
[1] "hours"

$tstr
[1] "36 h"

>  parse.timeint('36 h')
[1] 129600


##
## speed comparison
##
>  t8 <- 
>structure(sort(runif(100000,1017820800,2*1017820800)),class=c('POSIXt','POSIXct'))
>  plot(t8,1:100000,xaxt='n',pch=3)
>  system.time(axis.ct(1,t8))
[1] 0.65 0.02 0.69 0.00 0.00
>  system.time(axis.POSIXct(1,t8))
[1] 11.94  0.00 12.07  0.00  0.00

>  version
          _
platform sparc-sun-solaris2.7
arch     sparc
os       solaris2.7
system   sparc, solaris2.7
status
major    1
minor    7.1
year     2003
month    06
day      16
language R

-- 
--------------------------------------
Don MacQueen
Environmental Protection Department
Lawrence Livermore National Laboratory
Livermore, CA, USA