anytime: Anythingto POSIXct or Date Converter
Motivation
R excels at computing with dates, and times. Usingtypedrepresentation for your data is highly recommended not only because ofthe functionality offered but also because of the added safety stemmingfrom proper representation.
But there is a small nuisance cost in interactive work as well as inprogramming. Users must have toldas.POSIXct() about amillion times that the origin is (of course) theepoch. Do we reallyhave to say it a million more times? Similarly, when parsing dates thataresome form of YYYYMMDD format, do we really have to manuallyconvert frominteger ornumeric orfactor orordered to character? Having one ofseveral common separators and/or date / time month forms (YYYY-MM-DD,YYYY/MM/DD, YYYYMMDD, YYYY-mon-DD and so on, with or without times), dowe really need a format string? Or could a smart converter function dothis?
anytime() aims to be thatgeneral purposeconverter returning a properPOSIXct (orDate)object no matter the input (provided it was somewhat parseable), relyingonBoostdate_time for the (efficient, performant) conversion.anydate() is an additional wrapper returning aDate object instead.
Examples
We show some simple examples onDate types.
(Note that in the first few examples, and for numeric conversion inthis range we now only useanydate asanytimeis consistent in computing seconds since epoch. If you want thebehaviour of version older than 0.3.0, setoldHeuristic=TRUE, seehelp(anytime) formore.)
From Integer orNumeric or Factor or Ordered
library(anytime)## also caches TZ in local envoptions(digits.secs=6)## for fractional seconds below## integeranydate(20160101L+0:2)## older version used anytime for this too[1]"2016-01-01 CST""2016-01-02 CST""2016-01-03 CST"## numericanydate(20160101+0:2)[1]"2016-01-01 CST""2016-01-02 CST""2016-01-03 CST"## factoranydate(as.factor(20160101+0:2))[1]"2016-01-01 CST""2016-01-02 CST""2016-01-03 CST"## orderedanydate(as.ordered(20160101+0:2))[1]"2016-01-01 CST""2016-01-02 CST""2016-01-03 CST"Character: Simple
## Dates: Characteranydate(as.character(20160101+0:2))[1]"2016-01-01 CST""2016-01-02 CST""2016-01-03 CST"## Dates: alternate formatsanydate(c("20160101","2016/01/02","2016-01-03"))[1]"2016-01-01 CST""2016-01-02 CST""2016-01-03 CST"Character: ISO
## Datetime: ISO with/without fractional secondsanytime(c("2016-01-01 10:11:12","2016-01-01 10:11:12.345678"))[1]"2016-01-01 10:11:12.000000 CST""2016-01-01 10:11:12.345678 CST"## Datetime: ISO alternate (?) with 'T' separatoranytime(c("20160101T101112","20160101T101112.345678"))[1]"2016-01-01 10:11:12.000000 CST""2016-01-01 10:11:12.345678 CST"Character: Textual monthformats
## ISO styleanytime(c("2016-Sep-01 10:11:12","Sep/01/2016 10:11:12","Sep-01-2016 10:11:12"))[1]"2016-09-01 10:11:12 CDT""2016-09-01 10:11:12 CDT""2016-09-01 10:11:12 CDT"## Datetime: Mixed format (cf http://stackoverflow.com/questions/39259184)anytime(c("Thu Sep 01 10:11:12 2016","Thu Sep 01 10:11:12.345678 2016"))[1]"2016-09-01 10:11:12.000000 CDT""2016-09-01 10:11:12.345678 CDT"Character: Dealing with DST
This shows an important aspect. When not working localtime (byoverriding toUTC) thechanging difference UTC iscorrectly covered (which the underlyingBoostDate_Time library does not by itself).
## Datetime: pre/post DSTanytime(c("2016-01-31 12:13:14","2016-08-31 12:13:14"))[1]"2016-01-31 12:13:14 CST""2016-08-31 12:13:14 CDT"anytime(c("2016-01-31 12:13:14","2016-08-31 12:13:14"),tz="UTC")# important: catches change[1]"2016-01-31 18:13:14 UTC""2016-08-31 17:13:14 UTC"Technical Details
The heavy lifting is done by a combination ofBoostlexical_cast to go fromanything to string representationwhich is then parsed byBoostDate_Time. We use theBH package toaccessBoost, and rely onRcpp for aseamless C++ interface to and fromR.
Further, as theBoostDate_Time library cannot resolve timezones on the Windows platform(where timezone information is typically provided by R itself for itsuse), we offer a fallback of calling into R (via facilities fromRcpp); see thehelp for theuseR argument for more details.
Status
The package should work as expected.
Example Uses
Currently, just over ten differentCRAN packages import this package.Among them are the following research-focused packages:
- AGread byHibbinget al which reads and transforms ActiGraph physicalactivity measures;
- cqcr byOdell accesses ‘Care Quality Commission’ data from the health and adultsocial care regulator for England;
- E4tools byKleiman which reads data from Empatica wearable physiologymonitors;
- RDS by Handcocket al which is part of the “RDS Ananlyst” suite for analysingrespondent-driven sampling data;
- tsbox by Saxfor format-agnostic time series data representation andconversions;
- tsibble byWanget al for temporal data in an explicit data- andmodel-oriented format.
Changes
See the NEWS.Rd file onCRAN orGitHub.In particular, version 0.3.0 corrects an overly optimistic heuristic forinteger or numeric arguments and now behaves more like R itself.Specifically, epoch offsets are interpreted as seconds for datetimeobjects, and days for date objects. The prior behaviour can be restoredwith an option which also be be set globally, see the help page fordetails.
Installation
The package is now onCRANand can be installed via a standard
install.packages("anytime")Continued Testing
As we rely on thetinytest package,the already-installed package can also be verified via
tinytest::test_package("anytime")at any later point.
Contributing
Any problems, bug reports, or features requests for the package canbe submitted and handled most conveniently asGithub issuesin the repository.
Before submitting pull requests, it is frequently preferable to firstdiscuss need and scope in such an issue ticket. See the fileContributing.md(in theRcpp repo) for abrief discussion.
Author
Dirk Eddelbuettel
License
GPL (>= 2)
Initially created: Sun Sep 11 11:39:17 CDT 2016
Last modified: Fri Dec 20 08:23:40 CST 2024