| indexOf,ANY,CFtime-method {CFtime} | R Documentation |
Find the index of timestamps in the time series
Description
In the CFtime instance y, find the index in the time series for each
timestamp given in argument x. Values of x that are before the earliest
value in y will be returned as 0 (except when the value is before the
datum of y, in which case the value returned is NA); values of x that
are after the latest values in y will be returned as
.Machine$integer.max. Alternatively, when x is a numeric vector of index
values, return the valid indices of the same vector, with the side effect
being the attribute "CFtime" associated with the result.
Usage
## S4 method for signature 'ANY,CFtime'
indexOf(x, y, method = "constant")
Arguments
x |
Vector of character, POSIXt or Date values to find indices for, or a numeric vector. |
y |
CFtime instance. |
method |
Single value of "constant" or "linear". If |
Details
Timestamps can be provided as vectors of character strings, POSIXct or
Date.
Matching also returns index values for timestamps that fall between two
elements of the time series - this can lead to surprising results when time
series elements are positioned in the middle of an interval (as the CF
Metadata Conventions instruct us to "reasonably assume"): a time series of
days in January would be encoded in a NetCDF file as
c("2024-01-01 12:00:00", "2024-01-02 12:00:00", "2024-01-03 12:00:00", ...)
so x <- c("2024-01-01", "2024-01-02", "2024-01-03") would result in
(NA, 1, 2) (or (NA, 1.5, 2.5) with method = "linear") because the date
values in x are at midnight. This situation is easily avoided by ensuring
that y has bounds set (use bounds(y) <- TRUE as a proximate solution if
bounds are not stored in the NetCDF file). See the Examples.
If bounds are set, the indices are taken from those bounds. Returned indices
may fall in between bounds if the latter are not contiguous, with the
exception of the extreme values in x.
Values of x that are not valid timestamps according to the calendar of y
will be returned as NA.
x can also be a numeric vector of index values, in which case the valid
values in x are returned. Negative values are excluded and then the
remainder returned. Positive and negative values may not be mixed. This has
the side effect that the result has the attribute "CFtime" describing the
temporal dimension of the slice. If index values outside of the range of y
(1:length(y)) are provided, an error will be thrown.
Value
A numeric vector giving indices into the "time" dimension of the
dataset associated with y for the values of x. Attribute "CFtime"
contains an instance of CFtime that describes the dimension of filtering
the dataset associated with y with the result of this function, excluding
any NA, 0 and .Machine$integer.max values.
Examples
cf <- CFtime("days since 2020-01-01", "360_day", 1440:1799 + 0.5)
as_timestamp(cf)[1:3]
x <- c("2024-01-01", "2024-01-02", "2024-01-03")
indexOf(x, cf)
indexOf(x, cf, method = "linear")
bounds(cf) <- TRUE
indexOf(x, cf)
# Non-existent calendar day in a `360_day` calendar
x <- c("2024-03-30", "2024-03-31", "2024-04-01")
indexOf(x, cf)
# Numeric x
indexOf(c(29, 30, 31), cf)