indexOf: Find the index of timestamps in the time series

In CFtime: Using CF-Compliant Calendars with Climate Projection Data

Find the index of timestamps in the time series

Description

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; 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

indexOf(x, y, method = "constant")

Arguments

x	Vector of character, POSIXt or Date values to find indices for, or a numeric vector.
y	A CFTime instance.
method	Single value of "constant" or "linear". If "constant" or when bounds are set on argument y, return the index value for each match. If "linear", return the index value with any fractional value.

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. If negative values are passed, the positive counterparts will be excluded and then the remainder returned. Positive and negative values may not be mixed. Using a numeric vector 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 data set associated with y for the values of x. If there is at least 1 valid index, then attribute "CFTime" contains an instance of CFTime that describes the dimension of filtering the data set 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)

CFtime documentation built on April 12, 2025, 5:07 p.m.