nanotime typeThe functions nano_floor and nano_ceiling
round down or up, respectively. Although the underlying implementation
of nanotime has negative numbers for values before
1970-01-01 UTC, the rounding is always done backward in time for
nano_floor and forward in time for
nano_ceiling. The functions take a nanotime
argument x which is the instance to round, together with a
second argument precision which indicates an arbitrary
precision to which the rounding should be performed. This argument can
be either a nanoduration or or a nanoperiod.
In the latter case, the argument tz must also be specified
in order to give the nanoperiod a meaning. Finally, the
nanotime argument origin can be optionally
specified to fix the rounding to a specific point in time.
nano_ceiling(x, precision, ...)
nano_floor(x, precision, ...)
# S4 method for signature 'nanotime,nanoduration'
nano_ceiling(x, precision, origin = nanotime())
# S4 method for signature 'nanotime,nanoduration'
nano_floor(x, precision, origin = nanotime())
# S4 method for signature 'nanotime,nanoperiod'
nano_ceiling(x, precision, origin = nanotime(), tz)
# S4 method for signature 'nanotime,nanoperiod'
nano_floor(x, precision, origin = nanotime(), tz)
x
|
a nanotime object which must be sorted
|
precision
|
a nanoduration or nanoperiod object indicating
the rounding precision
|
…
|
for future additional arguments |
origin
|
a nanotime scalar indicating the origin at which the
rounding is considered
|
tz
|
a character scalar indicating the time zone in which to
conduct the rounding
|
This flexible rounding must be understood in the context of a vector.
The rounding precision can then be considered as an interval that
defines a grid over which the elements are either assigned to the
starting value of the interval to which they belong
(nano_floor) or the ending value of the interval to which
they belong (nano_ceiling). This allows for a grouping of a
nanotime vector on which a statistic may then be run. In
the examples below, such a use case is shown in the context of a
data.table object.
If “business” concepts such as month or days are needed, the
argument precision must be of type period. It
is then mandatory to specify the timezone argument tz as
this ensures timezone correctness of the intervals including for example
for the rare hourly transitions of some countries going from a timezone
with a whole hour difference with UTC to one with a fractional hour
difference. In the case of a period, the functions align
the rounding if the precision is an integer divisor of a larger
quantity. For instance, if one specifies a rounding of 6 hours, a
divisor of a day, the hours are aligned on days and the rounding is made
to a grid at hours 0, 6, 12 and 18 in the specified timezone. If the
precision is not a divisor, the grid is aligned to the nearest hour
before the first element of the vector to round.
The argument origin controls the reference point of the
rounding, allowing arbitrary specification of the reference point of the
rounding.
library("nanotime")
# "classic" rounding:
nano_floor(as.nanotime("2010-10-10 11:12:15 UTC"), as.nanoduration("01:00:00"))
# rounding with arbitrary precision:
nano_floor(as.nanotime("2010-10-10 11:12:15 UTC"), as.nanoduration("06:00:00"))
nano_floor(as.nanotime("2010-10-10 11:23:15 UTC"), as.nanoduration("00:15:00"))
nano_ceiling(as.nanotime("2010-10-10 11:23:15 UTC"), as.nanoduration("01:15:23"))
# controlling the reference point via the 'origin' argument:
nano_ceiling(as.nanotime("2010-10-10 11:23:15 UTC"),
as.nanoduration("01:15:23"),
origin=as.nanotime("2010-10-10 11:23:15 UTC"))
# using business concepts and rounding across a daylight saving change:
v <- seq(as.nanotime("2020-03-08 America/New_York"),
by=as.nanoperiod("06:00:00"), length.out=8, tz="America/New_York")
print(nano_floor(v, as.nanoperiod("1d"), tz="America/New_York"), tz="America/New_York")
# using the concept in a 'data.table':
library(data.table)
n <- 3 * 24
idx <- seq(as.nanotime("2020-03-07 America/New_York"),
by=as.nanoperiod("01:00:00"), length.out=n, tz="America/New_York")
dt <- data.table(idx, a=1:n, b=2:(n+1))
dt_mean <- dt[, list(mean = mean(a)),
by=nano_ceiling(idx, as.nanoperiod("1d"), tz="America/New_York")]