# R: Utilities and Tools Package

timeDate-package {timeDate} | R Documentation

## Utilities and Tools Package

### Description

Package of calendar, date, time tools and utilities for Rmetrics.

### Overview of Topics

This help file describes the concepts and methods behind the S4 'timeDate' class used in Rmetrics for financial data and time management together with the management of public and ecclesiastical holidays.

The 'timeDate' class fulfils the conventions of the ISO 8601 standard as well as of the ANSI C and POSIX standards. Beyond these standards it provides the "Financial Center" concept which allows to handle data records collected in different time zones and mix them up to have always the proper time stamps with respect to your personal financial center, or alternatively to the GMT reference time. It can thus also handle time stamps from historical data records from the same time zone, even if the financial centers changed day light saving times at different calendar dates.

Moreover 'timeDate' is almost compatible with the 'timeDate' class in Insightful's SPlus 'timeDate' class. If you move between the two worlds of R and SPlus, you will not have to rewrite your code. This is important for business applications.

The 'timeDate' class offers not only date and time functionality but it also offers sophisticated calendar manipulations for business days, weekends, public and ecclesiastical holidays.

This help page is presented in four sections:

1. S4 'timeDate' Class and Functions
2. Operations on 'timeDate' Objects
3. Daylight Saving Time and Financial Centers
4. Holidays and Holiday Calendars

### 1. S4 'timeDate' Class and Generator Functions

Date and time stamps are represented by an S4 object of class 'timeDate'.

        setClass("timeDate",
        representation(
        Data = "POSIXct",
        format = "character",
        FinCenter = "character"
        ))

They have three slots. The `@Data` slot holds the time stamps which are `POSIXct` formatted as specified in the `@format` slot. The time stamps are local and belong to the financial center expressed through the slot `@FinCenter`.

There are several possibilities to generate a 'timeDate' object. The most forward procedure is to use one of the following functions:

`timeDate` – Creates a 'timeDate' object from scratch,
`timeSequence` – creates a sequence of 'timeDate' objects,
`timeCalendar` – creates a 'timeDate' object from calendar atoms,
`Sys.timeDate` – returns the current date and time as a 'timeDate' object.

With the function `timeDate` you can create 'timeDate' objects from scratch by specifying a character vector of time stamps and a financial center which the character vector belongs to. "GMT" is used by default as the reference for all date/time operations. But you can set the variable `myFinCenter` to your local financial center reference if you want to reference dates/time to it.

Examples:

        # Show My local Financial Center - Note, by Default this is "GMT"
        getRmetricsOptions("myFinCenter")

        # Compose Character Vectors of Dates and Times:
        Dates <- c("1989-09-28","2001-01-15","2004-08-30","1990-02-09")
        Times <- c(  "23:12:55",  "10:34:02",  "08:30:00",  "11:18:23")
        charvec = paste(Dates, Times)

        # Create a 'timeDate' object
        timeDate(charvec)

        # Create a 'timeDate' object with my financial center set to Zurich
        myFinCenter <- "Zurich"
        timeDate(charvec)

        # if the 'timeDate' was recorded in a different financial center, it
        # will be automatically converted to your financial center,
        # i.e. "Zurich".
        timeDate(charvec, zone = "Tokyo")

        # You can also convert a recorded 'timeDate' from your financial
        # center "Zurich" to another one, for example "NewYork".
        timeDate(charvec, FinCenter = "NewYork")

NOTE: Rmetrics has implemented an automated date/time format identifier for many common date/time formats which tries to automatically recognise the format for the character vector of dates and times. You can have a look at
`whichFormat(charvec)`.

NOTE: Rmetrics always uses the midnight standard on dates and times. You can see it with
`.midnightStandard("2008-01-31 24:00:00")`

Alternatively we can create a sequence of 'timeDate' objects with the help of the function `timeSequence`. This can be done in several ways, either by specifying the range of the data through the arguments `from` and `to`, or when `from` is missing, by setting the argument `length.out` of the desired series. Note in the case of a monthly sequence, you have further options. For example you can generate the series with the first or last day in each month, or use more complex rules like the last or n-th Friday in every month.

Examples:

        # Lets work in an international environment:
        setRmetricsOptions(myFinCenter = "GMT")

        # Your 'timeDate' is now in the Financial Center "GMT"
        timeDate(charvec)

        # Daily January 2008 Sequence:
        timeSequence(from = "2008-01-01", to = "2008-01-31", by = "day")

        # Monthly 2008 Sequence:
        tS = timeSequence(from = "2008-01-01", to = "2008-12-31", by = "month")
        tS

        # Do you want the last Day or the last Friday in Month Data ?
        timeLastDayInMonth(tS)
        timeLastNdayInMonth(tS, nday = 5)

A third possibility is to create 'timeDate' objects from calendar atoms. You can specify values or vectors of equal length of integers denoting year, month, day, hour, minute and seconds. If every day has the same time stamp, you can just add an offset.

Examples:

        # Monthly calendar for Current Year
        getRmetricsOptions("currentYear")
        timeCalendar()

        # Daily 'timeDate' for January data from Tokyo local time 16:00
        timeCalendar(2008, m=1, d=1:31, h=16, zone="Tokyo", FinCenter="Zurich")

        # Or add16 hours in seconds ...
        timeCalendar(2008, m=1, d=1:31, zone="Tokyo", FinCenter="Zurich") + 16*3600

### 2. Operations on 'timeDate' Objects

Many operations can be performed on 'timeDate' objects. You can add and subtract, round and truncate, subset, coerce or transform them to other objects. These are only few options among many others.

Math Operations

Math operations can add and subtract dates and times, and perform logical operations on 'timeDate' objects.

Examples:

        # Date and Time Now:
        now = Sys.timeDate()

        # One Hour Later:
        now + 3600

        # Which date/time is earlier or later ?
        tC = timeCalendar()
        tR = tC + round(3600*rnorm(12))
        tR > tC

Lagging

You can generate suitable lagged and iterated differences:

`diff.timeDate` – Returns suitably lagged and iterated differences.

Examples:

        # Monthly Dates 2008 and January 2009:
        tC = c(timeCalendar(2008), timeCalendar(2009)[1])

        # Number of days in months and total 2008:
        diff(tC)
        sum(as.integer(diff(tC)))

Rounding and Truncating

Dates and times can be rounded or truncated. This is useful lower frequencies than seconds, for example hourly.

`round` – rounds objects of class 'timeDate',
`trunc` – truncates objects of class 'timeDate'.

Examples:

        # Round the Random Time Stamps to the Nearest Hour:
        tC = timeCalendar()
        tR = tC + round(3600*rnorm(12))
        tR
        round(tR, "h")

        # Truncate by Hour or to the Next Full Hour::
        trunc(tR, "h")
        trunc(tR + 3600, "h")

Subsetting

Subsetting a 'timeDate' is a very important issue in the management of dates and times. Rmetrics offers several functions which are useful in this context:

`"["` – Extracts or replaces subsets from 'timeDate' objects,
`window, cut` – extract a piece from a 'timeDate' object,

In this context it is also important to know the `start` and the `end` time stamp together with the total number of time stamps.

`start` – extracts the first entry of a 'timeDate' object,
`end` – extracts the last entry of a 'timeDate' object,
`length` – returns the length of a 'timeDate' object.

Examples:

        # Create Monthly Calendar for next year
        tC = timeCalendar(getRmetricsOptions("currentYear") + 1)
        tC

        # Start, end and length of 'timeDate' objects
        start(tC)
        end(tC)
        length(tC)

        # The first Quarter - Several Alternative Solutions:
        tC[1:3]
        tC[-(4:length(tC))]
        window(tC, start = tC[1], end = tC[3])
        cut(tC, from = tC[1], to = tC[3])
        tC[tC < tC[4]]

        # The Quarterly Series:
        tC[seq(3, 12, by = 3)]

Weekdays, weekends, business days, and holidays can be easily obtained with the following functions:

`isWeekday` – tests if a date is a weekday or not,
`isWeekend` – tests if a date is a weekend day or not,
`isBizday` – tests if a date is a business day or not,
`isHoliday` – tests if a date is a holiday day or not.

Examples:

        # A 'timeDate' Sequence around Easter 2008
        Easter(2008)
        tS <- timeSequence(Easter(2008, -14), Easter(2008, +14))
        tS

        # Subset weekdays and business days:
        tW <- tS[isWeekday(tS)]; tW
        dayOfWeek(tW)
        tB <- tS[isBizday(tS, holidayZURICH())]; tB
        dayOfWeek(tB)

The functions `blockStart` and `blockEnd` gives time stamps for equally sized blocks.

`blockStart` – Creates start dates for equally sized blocks,
`blockEnd` – Creates end dates for equally sized blocks.

Examples:

        # 'timeDate' object for the last 365 days:
        tS = timeSequence(length.out = 360)
        tS

        # Subset Pointers for blocks of exactly 30 days:
        blockStart(tS, 30)
        blockEnd(tS, 30)
        Sys.timeDate()

Coercions and Transformations

'timeDate' objects are not living in an isolated world. Coercions and transformations allow 'timeDate' objects to communicate with other formatted time stamps. Be aware that in most cases information can be lost if the other date.time classes do not support this functionality. There exist several methods to coerce and transform `timeDate` objects into other objects.

`as.timeDate` – Implements Use Method,
`as.timeDate.default` – default Method,
`as.timeDate.POSIXt` – returns a 'POSIX' object as 'timeDate' object,
`as.timeDate.Date` – returns a 'POSIX' object as 'timeDate' object.

`as.character.timeDate` – Returns a 'timeDate' object as 'character' string,
`as.double.timeDate` – returns a 'timeDate' object as 'numeric' object,
`as.data.frame.timeDate` – returns a 'timeDate' object as 'data.frame' object,
`as.POSIXct.timeDate` – returns a 'timeDate' object as 'POSIXct' object,
`as.POSIXlt.timeDate` – returns a 'timeDate' object as 'POSIXlt' object,
`as.Date.timeDate` – returns a 'timeDate' object as 'Date' object.

Users or maintainers of other date/time classes can add their own generic functions. For example `as.timeDate.zoo` and `as.zoo.timeDate`.

Concatenations and Reorderings

It might be sometimes useful to concatenate or reorder 'timeDate' objects. The generic functions to concatenate, replicate, sort, re-sample, unify and revert a 'timeDate' objects are :

`c` – Concatenates 'timeDate' objects,
`rep` – replicates a 'timeDate' object,
`sort` – sorts a 'timeDate' object,
`sample` – resamples a 'timeDate' object,
`unique` – makes a 'timeDate' object unique,
`rev` – reverts a 'timeDate' object.

NOTE: The function `c` of a 'timeDate' objects takes care of possible different financial centers specific to each object to be concatenated. In such cases, all time stamps will be transformed to the financial center of the first time stamp used in the concatenation:

Examples:

        # Concatenate the local time stamps to Zurich time ...
        ZH = timeDate("2008-01-01 16:00:00", zone = "GMT", FinCenter = "Zurich")
        NY = timeDate("2008-01-01 18:00:00", zone = "GMT", FinCenter = "NewYork")
        c(ZH, NY)
        c(NY, ZH)

        # Rordering:
        tC = timeCalendar(); tC
        tS = sample(tC); tS
        tO = sort(tS); tO
        tV = rev(tO); tV
        tU = unique(c(tS, tS)); tU

### 3. Daylight Saving Time and Financial Centers

Each financial center worldwide has a function which returns Daylight Saving Time Rules. Almost 400 prototypes are made available through the Olson time zone data base. The cities and regions can be listed using the command `listFinCenter`. The DST rules for specific financial center can be viewed by their name, e.g. `Zurich()`. Additional financial centers can be added by the user taking care of the format specification of the DST functions.

Setting Financial Centers

All time stamps are handled according to the time zone and daylight saving time rules specified by the center through the variable `myFinCenter`. This variable is set by default to `"GMT"` but can be changed to your local financial center or to any other financial center you want to use.

NOTE: By setting the financial center to a continent/city which lies outside of the time zone used by your computer does not change any time settings or environment variables used by your computer.

To change the name of a financial center from one setting to another just assign to the variable `myFinCenter` the desired name of the city:

Examples:

        # What is my current Financial Center ?
        getRmetricsOptions("myFinCenter")

        # Change to Zurich:
        setRmetricsOptions(myFinCenter = "Zurich")
        getRmetricsOptions("myFinCenter")

From now on, all dates and times are handled within the middle European time zone and the DST rules which are valid for Zurich.

List of Financial Centers

There are many other financial centers supported by Rmetrics. They can be displayed by the function `listFinCenter`. You can also display partial lists with wildcards and regular expressions:

Examples:

        # List all supported Financial Centers Worldwide:
        listFinCenter()

        # List European Financial Centers:
        listFinCenter("Europe/*")

DST Rules

For each financial center a function is available. It keeps the information of the time zones and the DST rules. The functions return a data.frame with 4Columns :

        Zurich offSet isdst TimeZone
        ...
        62  2008-03-30 01:00:00   7200     1     CEST
        63  2008-10-26 01:00:00   3600     0      CET
        ...

The first column describes when the time was changed, the second gives the offset to "GMT", the third returns the daylight savings time flag which is positive if in force, zero if not, and negative if unknown. The last column gives the name of the time zone. You can have a look at the function `Zurich()` :

Examples:

        # Show the DST Rules for Zurich:
        Zurich()

        # List European Financial Centers:
        listFinCenter("Europe/*")

### 3. Holidays and Holiday Calendars

It is non-trivial to implement function for business days, weekends and holidays. It is not difficult in an algorithmic sense, but it can become tedious to implement the rules of the calendar themselves, for example the date of Easter.

In the following section we briefly summarise the functions which can calculate dates of ecclesiastical and public holidays. With the help of these functions we can also create business and holiday calendars.

Special Dates:

The implemented functions can compute the last day in a given month and year, the dates in a month that is a n-day (e.g. n- = Sun) on or after a given date, the dates in a month that is a n-day on or before a specified date, the n-th occurrences of a n-day for a specified year/month vectors, or the last n-day for a specified year/month value or vector.

NOTE: n-days are numbered from 0 to 6 where 0 correspond to the Sunday and 6 to the Saturday.

`timeFirstDayInMonth` – Computes the first day in a given month and year,
`timeLastDayInMonth` – Computes the last day in a given month and year,
`timeFirstDayInQuarter` – Computes the first day in a given quarter and year,
`timeLastDayInQuarter` – Computes the last day in a given quarter and year,

`timeNdayOnOrAfter` – Computes date that is a "on-or-after" n-day,
`timeNdayOnOrBefore` –b Computes date that is a "on-or-before" n-day,

`timeNthNdayInMonth` – Computes n-th occurrence of a n-day in year/month,
`timeLastNdayInMonth` – Computes the last n-day in year/month.

Holidays:

Holidays may have two origins: ecclesiastical or public/federal. The ecclesiastical calendars of Christian churches are based on cycles of movable and immovable feasts. Christmas, December 25, is the principal immovable feast. Easter is the principal movable feast, and dates of most of the other movable feasts are determined with respect to Easter. However, the movable feasts of the Advent and Epiphany seasons are Sundays reckoned from Christmas and the Feast of the Epiphany, respectively.

Examples:

        # List Holidays available in Rmetrics
        listHolidays()

        # The date of Easter for the next 5 years:
        currentYear <- getRmetricsOptions("currentYear")
        Easter(currentYear:(currentYear+5))

Holiday Calendars:

`holidayZURICH` – Zurich Business Calendar,
`holidayNYSE` – NYSE Stock Exchange Holiday Calendar,
`holidayZURICH` – TSX Holiday Calendar.

We would like to thanks all Rmetrics users who gave us many additional information concerning local holidays.

### References

Bateman R., (2000); Time Functionality in the Standard C Library, Novell AppNotes, September 2000 Issue, 73–85.

Becker R.A., Chambers J.M., Wilks A.R. (1988); The New S Language, Wadsworth & Brooks/Cole.

ISO-8601, (1988); Data Elements and Interchange Formats - Information Interchange, Representation of Dates and Time, International Organization for Standardization, Reference Number ISO 8601, 14 pages.

James D.A., Pregibon D. (1992), Chronological Objects for Data Analysis, Reprint.

Ripley B.D., Hornik K. (2001); Date-Time Classes, R-News, Vol. 1/2 June 2001, 8–12.

Zivot, E., Wang J. (2003); Modeling Financial Time Series with S-Plus, Springer, New-York.

[Package timeDate version 3043.102 Index]