ti {tis}

Time Index Objects

Description

The function ti is used to create time index objects, which are useful for date calculations and as indexes for tis (time indexed series).

as.ti and asTi coerce an object to a time index, the difference being that as.ti calls the constructor ti, while asTi simply forces the class of its argument to be "ti" without any checking as to whether or not it makes sense to do so.

is.ti tests whether an object is a time index.

couldBeTi tests whether or not x is numeric and has all elements within the range expected for a ti time index with the given tif. If tif is NULL (the default), the test is whether or not x could be a ti of any frequency. If so, it can be safely coerced to class ti by as.ti.

Usage

ti(x, ...)
## S3 method for class 'Date'
ti(x, ...)
## Default S3 method:
ti(x, tif = NULL, freq = NULL, ...)
## S3 method for class 'jul'
ti(x, tif = NULL, freq = NULL, hour = 0, minute = 0, second = 0, ...)
## S3 method for class 'ssDate'
ti(x, ...)
## S3 method for class 'ti'
ti(x, tif = NULL, freq = NULL, ...)
## S3 method for class 'tis'
ti(x, ...)
## S3 method for class 'yearmon'
ti(x, ...)
## S3 method for class 'yearqtr'
ti(x, ...)
as.ti(x, ...)
asTi(x)
is.ti(x)
couldBeTi(x, tif = NULL)

Arguments

x

object to be tested (is.ti) or converted into a ti object. As described in the details below, the constructor function ti can deal with several different kinds of x.

hour

used if and only if tif is an intraday frequency

minute

used if and only if tif is an intraday frequency

second

used if and only if tif is an intraday frequency

...

other args to be passed to the method called by the generic function.

tif

a ti Frequency, given as either a numerical code or a string. tif() with no arguments returns a list of the allowable numerical codes and names. Either tif or freq must be supplied for the variants of ti().

freq

some tif's can alternatively be specified by their frequency, such as 1 (annual), 2 (semiannual), 4 (quarterly), 6 (bimonthly), 12 (monthly), 24 (semimonthly), 26 (biweekly), 36 (tenday), 52 (weekly), 262 (business) and 365 (daily). Either tif or freq must be supplied for the variants of ti().

Details

A ti has a tif (ti Frequency) and a period. The period represents the number of periods elapsed since the base period for that frequency. Adding or subtracting an integer to a ti gives another ti. Provided their corresponding element have matching tifs, the comparison operators <, >, <=, >=, == all work, and subtracting one ti from another gives the number of periods between them. See the examples section below.

The ti class implements methods for a number of generic functions, including "[", as.Date, as.POSIXct, as.POSIXlt, c, cycle, edit, format, frequency, jul, max, min, print, rep, seq, tif, tifName, time, ymd.

ti is a generic function with specialized methods to handle jul, Date, ti. tis, yearmon and yearqtr objects.

The default method (ti.default) deals with character x by calling as.Date on it. Otherwise, it proceeds as follows:

If x is numeric, a check is made to see if x could be a ti object that has somehow lost it's class attribute. Failing that, isYmd is used to see if it could be yyyymmdd date, then isTime is called to see if x could be a decimal time (a number between 1799 and 2200). If x is of length 2, an attempt to interpret it as a c(year, period) pair is made. Finally, if all else fails, as.Date(x) is called to attempt to create a Date object that can then be used to construct a ti.

Value

is.ti and couldBeTi return TRUE or FALSE.

as.ti returns a ti object.

asTi returns its argument with the class attribute set to "ti".

ti constructs a ti object like x, except for two special cases:

1. If x is a tis series, the return value is a vector time index with elements corresponding to the observation periods of x.

2. If x is a numeric object of length 2 interpretable as c(year, period), the return value is a single ti.

Note

The as.Date(x) call is not wrapped in a try-block, so it may be at the top of the stack when ti fails.

The return value from asTi is not guaranteed to be a valid ti object. For example, asTi("a") will not throw an error, and it will return the string "a" with a class attribute "ti", but that's not a valid time index.

See Also

jul, ymd, tif, tifName, as.Date

Examples

z <- ti(19971231, "monthly")   ##  monthly ti for Dec 97
is.ti(z)                       ##  TRUE
is.ti(unclass(z))              ##  FALSE
couldBeTi(unclass(z))          ##  TRUE
ymd(z + 4)                     ##  19980430
z - ti(c(1997,6), freq = 12)   ##  monthly ti for June 1997
ti(z, tif = "wmonday")         ##  week ending Monday June 30, 1997