tind: A Common Representation of Time Indices of Different Types

Description

tind is an S3 class representing time indices of different types (years, quarters, months, ISO 8601 weeks, dates, date-time, and arbitrary integer/numeric indices). Time indices are represented by vectors of integers or doubles with type attribute and time zone attribute (date-time only). Objects of tind behave like plain vectors and can be easily used in data frames.

A tind object would usually be created using as.tind method or using parse_t and strptind functions. tind constructor allows to create time indices from components (like year, month, day) and to create vectors of a given length filled with NA values.

is.tind function checks whether an object is of tind class.

Usage

tind(..., length = 0L, type = NULL, tz = NULL)
is.tind(x)

Value

An object of tind class for tind or a logical value for is.tind.

Arguments

...

components of time index to be constructed (in arbitrary order), the following are accepted:

y: year.

q

quarter.

m

month.

w

week (ISO 8601).

d

day.

j

day of year.

u

day of week (ISO 8601).

H

hour.

M

minute.

S

second.

length

an integer value specifying the desired length.

type

a character value determining time index type (y - years, q - quarters, m - months, w - weeks, d - dates, t - date-time, h - time of day, n - numeric value, i - integer value).

(optional) a character value determining the time zone (the default NULL is interpreted as the system time zone). See tzone documentation for information on time zones.

any R object.

Details

tind class supports the following types of time indices:

years: internal code "y".
quarters: internal code "q".
months: internal code "m".
weeks: internal code "w".
dates: internal code "d".
date-time: internal code "t".
time of day: internal code "h".
arbitrary integer index: "i".
arbitrary numeric index: "n".

Valid ranges for time indices are:

years ("y"): 0000--9999.
quarters ("q"): 0000q1--9999q4.
months ("m"): 0000-01--9999-12.
weeks ("w"): 0000-W01--9999-W52.
dates ("d"): 0000-01-01--9999-12-31.
date-time ("t"): from 0000-01-01 15:00:00Z to 9999-12-31 09:00:00Z (between -62167165200 and 253402246800 seconds since the Unix epoch).
time of day ("h"): from 00:00 to 24:00 (between 0 and 86400 seconds since midnight).

Examples

Run this code

# years
tind(y = 2010:2020)
tind(type = "y")
tind(length = 11, type = "y")

# quarters
tind(y = rep(2020:2023, each = 4), q = 1:4)
tind(q = 1:4, y = rep(2020:2023, each = 4))
tind(type = "q")
tind(length = 4, type = "q")

# months
tind(y = 2023, m = 1:12)
tind(m = 1:12, y = 2023)
tind(type = "m")
tind(length = 12, type = "m")

# weeks
tind(y = 2024, w = 1 + 2 * (0:25))
tind(type = "w")
tind(length = 13, type = "w")

# dates
tind(m = 3, d = 15, y = 2024)
tind(y = 2024, m = rep(1:3, each = 2), d = c(1, 15))
tind(type = "d")
tind(length = 6, type = "d")

# time of day
tind(H = 16, M = (0:3) * 15)
tind(type = "h")
tind(length = 4, type = "h")

# date-time
# system time zone
tind(y = 2024, m = 8, d = 2, H = 16, M = (0:3) * 15)
tind(y = 2024, m = 8, d = 2, H = 16, M = (0:3) * 15)
tind(y = 2024, m = 8, d = 2, H = 16, M = 0, S = 10 * (0:5))
# time zone explicitly provided
tind(y = 2024, m = 8, d = 2, H = 16, M = (0:3) * 15, tz = "UTC")
tind(type = "t")
tind(type = "t", tz = "UTC")
tind(length = 4, type = "t")
tind(length = 4, type = "t", tz = "UTC")

# integer and numeric indices
# (cannot be constructed from components like above)
tind(length = 10, type = "i")
tind(length = 10, type = "n")