[Rd] Help useRs to use R's own Time/Date objects more efficiently

[Martin Maechler]

This is mostly a RFC  [but *not* about the many extra packages, please..]:

Noticing to my chagrin  how my students work in a project,
googling for R code and cut'n'pasting stuff together, accumulating
this and that package on the way  all just for simple daily time series
(though with partly missing parts),
using chron, zoo, lubridate, ...  all for things that are very
easy in base R *IF* you read help pages and start thinking on
your own (...), I've noted once more that the above "if" is a
very strong one, and seems to happen rarely nowadays by typical R users...
(yes, I stop whining for now).

In this case, I propose to slightly improve the situation ...
by adding a few more lines to one help page [[how could that
help in the age where "google"+"cut'n'paste" has replaced thinking ? .. ]] :

On R's own ?Dates  help page (and also on ?DateTimeClasses )
we have pointers, notably

See Also:

     ...............
     ...............
     
     'weekdays' for convenience extraction functions.

So people must find that and follow the pointer
(instead of installing one of the dozen helper packages).

Then on that page, one sees  weekdays(), months() .. julian()
in the usage ... which don't seem directly helpful for a person
who needs more.  If that person is diligent and patient (as good useRs are ;-),
she finds

   Note:

	Other components such as the day of the month or the year are very
	easy to compute: just use 'as.POSIXlt' and extract the relevant
	component.  Alternatively (especially if the components are
	desired as character strings), use 'strftime'.


But then, nowadays, the POSIXlt class is not so transparent to the
non-expert anymore (as it behaves very much like POSIXct, and
not like a list for good reasons) .. and so 97%  of R users will
not find this "very easy".

For this reason, I propose to at add the following to the
'Examples:' section of the help file ...
and I hope that also readers of  R-devel  who have not been
aware of how to do this nicely,  will now remember (or remember
where to look?).

I at least will tell my students in the future to use these or
write versions of these simple utility functions.


------------------------------------------------

## Show how easily you get month, day, year, day (of {month, week, yr}), ... :
## (remember to count from 0 (!): mon = 0..11, wday = 0..6,  etc !!)

##' Transform (Time-)Date vector  to  convenient data frame :
dt2df <- function(dt, dName = deparse(substitute(dt)), stringsAsFactors = FALSE) {
    DF <- as.data.frame(unclass(as.POSIXlt( dt )), stringsAsFactors=stringsAsFactors)
    `names<-`(cbind(dt, DF, deparse.level=0L), c(dName, names(DF)))
}
dt2df(.leap.seconds)    # date+time
dt2df(Sys.Date() + 0:9) # date

##' Even simpler:  Date -> Matrix:
d2mat <- function(x) simplify2array(unclass(as.POSIXlt(x)))
d2mat(seq(as.Date("2000-02-02"), by=1, length.out=30)) # has R 1.0.0's release date

------------------------------------------------------------

In the distant past / one of the last times I touched on people
using (base) R's  Date / Time-Date  objects, I had started
thinking if we should not provide some simple utilities to "base R"
(not in the 'base' pkg, but rather 'utils') for "extracting" from
{POSIX(ct), Date} objects ... and we may have discussed that
within R Core 20 years ago,  and had always thought that this
shouldn't be hard for useRs themselves to see how to do...

But then I see that "everybody" uses extension packages instead,
even in the many situations where there's no gain doing so, 
but rather increases the dependency-complexity of the data analysis
unnecessarily.

Martin Maechler
ETH Zurich  and   R Core Team.