nanotime: Nanosecond Time Resolution for R

Build Status License CRAN Dependencies Downloads Code Coverage Last Commit

Motivation

R has excellent tools for dates and times. The Date and POSIXct classes (as well as the ‘wide’ representation in POSIXlt) are versatile, and a lot of useful tooling has been built around them.

However, POSIXct is implemented as a double with fractional seconds since the epoch. Given the 53 bits accuracy, it leaves just a bit less than microsecond resolution. Which is good enough for most things.

But more and more performance measurements, latency statistics, … are now measured more finely, and we need nanosecond resolution. For which commonly an integer64 is used to represent nanoseconds since the epoch.

And while R does not have a native type for this, the bit64 package by Jens Oehlschlägel offers a performant one implemented as a lightweight S3 class. So this package uses this integer64 class, along with two helper functions for parsing and formatting, respectively, at nano-second resolution from the RcppCCTZ package which wraps the CCTZ library from Google. CCTZ is a modern C++11 library extending the (C++11-native) chrono type.

In addition to the point-in-time type nanotime, this package also provides an interval type nanoival which may have open or closed start/end, a period type nanoperiod that is a human representation of time, such as day, month, etc., and a duration type nanoduration. These types are similar to what the lubridate package proposes.

Set and arithmetic operations on these types are available. All functionality is designed to correctly handle instances across different time zones. Because these temporal types are based on R built-in types, most functions have an efficient implementation and the types are suitable for use in data.frame and data.table. nanotime is also a better choice than the native POSIXct in most of the cases where fractional seconds are needed because it avoids floating point issues.

Demo

See the included demo script nanosecondDelayExample.R for a (completely simulated and hence made-up) study of network latency measured in nanoseconds resulting in the figure below

Examples

Simple Parsing and Arithmetic

R> x <- nanotime("1970-01-01T00:00:00.000000001+00:00")
R> print(x)
integer64
[1] 1
R> format(x)
[1] "1970-01-01T00:00:00.000000001+00:00"
R> x <- x + 1
R> print(x)
integer64
[1] 2
R> format(x)
[1] "1970-01-01T00:00:00.000000002+00:00"
R>

Vectorised

R> options("width"=60)
R> v <- nanotime(Sys.time()) + 1:5
R> v
integer64
[1] 1481505724483583001 1481505724483583002
[3] 1481505724483583003 1481505724483583004
[5] 1481505724483583005
R> format(v)
[1] "2016-12-12T01:22:04.483583001+00:00"
[2] "2016-12-12T01:22:04.483583002+00:00"
[3] "2016-12-12T01:22:04.483583003+00:00"
[4] "2016-12-12T01:22:04.483583004+00:00"
[5] "2016-12-12T01:22:04.483583005+00:00"
R> 

Use with zoo

R> z <- zoo(cbind(A=1:5, B=5:1), v)
R> options("nanotimeFormat"="%d %b %H:%M:%E*S")  ## override default
R> z
                          A B
12 Dec 01:47:55.812513001 1 5
12 Dec 01:47:55.812513002 2 4
12 Dec 01:47:55.812513003 3 3
12 Dec 01:47:55.812513004 4 2
12 Dec 01:47:55.812513005 5 1
R> 

Technical Details

The bit64 package (by Jens Oehlschlägel) supplies the integer64 type used to store the nanosecond resolution time as (positive or negative) offsets to the epoch of January 1, 1970. The RcppCCTZ package supplies the formatting and parsing routines based on the (modern C++) library CCTZ from Google.

Status

Still early stages. Expect changes, maybe even breaking ones. But the package has some tests, and code coverage.

Installation

The package is on CRAN and can be installed via a standard

install.packages("nanotime")

whereas in order to install development versions a

remotes::install_github("eddelbuettel/nanotime")  # dev version

should suffice. It requires the packages bit64, RcppCCTZ and zoo all of which are on CRAN and will be installed automatically.

Author

Dirk Eddelbuettel

License

GPL (>= 2)

Initially created: Web Dec 14 21:00:15 CST 2016
Last modified: Sat May 30 08:26:35 CDT 2020