TimeDateClass {fCalendar}R Documentation

timeDate Class

Description

A collection and description of functions for managing date and time around the globe for any financial center. The concept allows for dealing with time zones, day light saving time and holiday calendars independent of the date and time specifications of the operating system implemented on your computer. This is an important issue especially for R running under Microsoft's Windows operating system.

IMPORTANT:
The timeDate and timeSeries classes are so far tested only under MS Windows XP operating system. Note, that your time zone environment variable must be set to "GMT". The reason for this is, that the functions work internally with "GMT" POSIX date and time objects whereas the Daylight Saving Time is added on top of this through the information in the Ical Calendar Library.

The functions for Financial Centers are:

rulesFinCenter Returns DST rules for a financial center,
listFinCenter Lists all supported financial centers.

The functions for the Generation of 'timeDate' Objects are:

timeDate S4: Creates 'timeDate' object from a character vector,
timeCalendar S4: Creates 'timeDate' object from calendar atoms,
timeSequence S4: Creates regularly spaced object of class 'timeDate',
Sys.timeDate Returns system time as an object of class 'timeDate'.

The functions for Special Monthly 'timeDate' Sequences are:

timeLastDayInMonth Computes the last day in a given month and year,
timeNdayOnOrAfter Computes date that is a "on-or-after" n-day,
timeNdayOnOrBefore Computes date that is a "on-or-before" n-day,
timeNthNdayInMonth Computes n-th ocurrance of a n-day in year/month,
timeLastNdayInMonth Computes the last n-day in year/month.

The functions for the Representation of 'timedate' Objects are:

is.timeDate Checks if the object is of class 'timeDate',
print.timeDate S3: Prints 'timeDate', 'FinCenter' and 'Data' Slot,
summary.timeDate S3: Summarizes details of a 'timeDate' object,
format.timeDate Formats 'timeDate' as ISO conform character string.

Additional Functions:

isWeekday Tests if a date is a weekday or not,
isWeekend Tests if a date falls on a weekend or not,
isBizday Tests if a date is a business day or not,
weekDay Returns the day of the week.

Usage

rulesFinCenter(FinCenter = myFinCenter)
listFinCenter(pattern = "*")

timeDate(charvec, format = NULL, zone = "GMT", FinCenter = myFinCenter) 
timeCalendar(y = currentYear, m = 1:12, d = NULL, h = NULL, min = NULL, 
    s = NULL, FinCenter = myFinCenter)
timeSequence(from = "2004-01-01", to = format(Sys.time(), "%Y-%m-%d"), 
        by = "day", length.out = NULL, format = "", FinCenter = myFinCenter)
Sys.timeDate(FinCenter = myFinCenter) 

timeLastDayInMonth(charvec, format = "%Y-%m-%d", 
        FinCenter = "GMT")
timeNdayOnOrAfter(charvec, nday = 1, format = "%Y-%m-%d", 
        FinCenter = "GMT")
timeNdayOnOrBefore(charvec, nday = 1, format = "%Y-%m-%d",   
        FinCenter = "GMT")
timeNthNdayInMonth(charvec, nday = 1, nth = 1, format = "%Y-%m-%d", 
    FinCenter = "GMT")
timeLastNdayInMonth(charvec, nday = 1, format = "%Y-%m-%d", 
        FinCenter = "GMT")

is.timeDate(object) 
## S3 method for class 'timeDate':
print(x, ...)
## S3 method for class 'timeDate':
summary(object, ...)
## S3 method for class 'timeDate':
format(x, ...)

isWeekday(x)
isWeekend(x)
isBizday(x, holidays = holiday.NYSE())
weekDay(x)

Arguments

by a character string, containing one of "sec", "min", "hour", "day", "week", "month" or "year". This can optionally be preceded by an integer and a space, or followed by "s".
charvec a character vector of dates and times.
FinCenter a character with the the location of the financial center named as "continent/city".
format the format specification of the input character vector.
from, to starting date, required, and end date, ptional. If supplied to must be after from.
h, min, s hours of the days (0-23), defaults are 0, minutes of the days (0-59), defaults are 0, and seconds of the days (0-59), defaults are 0.
holidays [isBizday] -
holiday dates from a holiday calendar. An object of class timeDate.
length.out length.out integer, optional. Desired length of the sequence, if specified "to" will be ignored.
nday an integer vector with entries ranging from 0 (Sunday) to 6 (Saturday).
nth an integer vector numbering the n-th occurence.
object [is.timeData][summary] -
an object of class timeDate.
pattern a pattern character string which can be recognized by the grep function. Wild cards are allowed.
x [isWeekday][isWeekend][isBizday][weekDay] -
an object of class timeDate.
[format][print] -
an object of class timeDate.
y, m, d calendar years (e.g. 1997), defaults are 1960, calendar months (1-12), defaults are 1, and calendar days (1-31), defaults are 1.
zone the time zone or financial center where the data were recorded.
... arguments passed to other methods.

Details

For the management of chronological objects under R three concepts are available: The first is the implementation of date and time in R's chron package neglecting locals, time zones and day light saving times. This approach is appropriate for economic time series. The second approach, available in R's base package implements the POSIX standard to date and time objects, named "POSIXt". Unfortunately, the representation of these objects is operating system dependent and especially under MS Windows several problems appear in the management of time zones and day light saving times. Here we present a solution to overcome these difficulties with POSIX objects and introduce a new S4 class of 'timeDate' objects which allow for powerful methods to represent dates and times in different financial centers around the world. Many of the basic functionalities of these objects are in common with S-Plus' timeDate objects and thus many of your privately written functions for FinMetrics may also be used within R's environment.

A major difference is the time zone concept which is replaced by the "Financial Center" concept. The FinCenter character variable specifies where you are living and at which financial center you are working. With the variable myFinCenter you can overwrite the default setting with your personal settings. With the specification of the FinCenter your system knows what rules rules for day light saving times should be applied, what is your holiday calendar, what are your interest rate conventions. (Not all specifications are already implemented.) Many other aspects can be easily accessed when a financial center is named. So we can distinguish between Frankfurt and Zurich, which both belong to the same time zone, but differed in DST changes in the eighties and have different holiday calendars. Futhermore, since the underlying time refers to "GMT" and DST rules and all other information is available in local (ASCII) databases, we are sure, that R delivers with such a date/time concept on every computer independent of the operating system in use, identical results.

Another important feature of the "timeDate" concept used here is the fact that we don't rely on American or European ways to write dates. We use consequently the ISO-8601 standard for date and time notations.

Financial Centers

There are two functions concerned with the financial centers. The first, rulesFinCenter, lists the daylight saving rules for a selected financial center, and the second, listFinCenter, lists all centers available in the database. There is no dependency on the POSIX implementation of your operating system because all time zone and day light saving time information is stored locally in ASCII files. It is important to say, that the TZ environment variable must set to "GMT" in your system environment that there are no conflicts with the POSIX time zone management.

Through the definition of financial centers it becomes possible to introduce in the future a specification structure for financial centers, which includes further information for a center like holiday calendars, currency and interest rate conventions or many others.

Generation of timeDate Objects

We have defined a 'timeDate' class which is in many aspects similar to the S-Plus class with the same name, but has also some important advantageous differeneces. The S4 class has four Slots, the Data slot which holds date and time as 'POSIXlt' objects in the standard ISO-8601 format, the Dim slot which gives the dimension of the data object, the format specification slot and the FinCenter slot which holds the name of the financial center.

Three functions allow to cgenerate date/time objects: timeDate from character vectors, timeCalendar from date and time atoms, and timeSequence from a "from/to" or from a "from/length" sequence specification. Note, time zone transformations are easily handled by by the timeDate functions which can also take timeDate and POSIXt objects as inputs, while transforming them between financial centers and/or time zones specified by the arguments zone and FinCenter. Finally the function Sys.timeDate returns current system time in form of a timeDate object.

Special Monthly timeDate Sequences

We have implemented five functions to generate special monthly sequences. These are functions to compute the last day in a given month and year, to compute the dates in a month that is a n-day on or after a given date, to compute the dates in a month that is a n-day on or before a specified date, to compute the n-th ocurrances of a n-day for a specified year/month vectors, and finally to compute the last n-day for a specified year/month value or vector. n-days are numbered from 0 to 6 where 0 correspond to the Sunday and 6 to the Saturday.

Tests and Representation of timeDate Objects:

We have implemented four methods to test and represent timeDate objects. The method is.timeDate checks if a given object is of class "timeDate". The print method returns the date/time in square "[]" brackets to dsitinguish the output from other date and time objects. On top of the date and time output the name of the FinCenter is printed. The summary method returns a printed report with information about the "timeDate" object. Finally, the format methods allows to transform objects into a ISO conform formatted character strings.

Value

rulesFinCenter
listFinCenter
the first function returns a printed list of DST rules, the second lists time zones available in the database.

timedate
timeCalendar
timeSequence
return a S4 object of class 'timeDate'.

Sys.timeDate
returns the system time as an object of class 'timeDate'.

timeLastDayInMonth
timeNdayOnOrAfter
timeNdayOnOrBefore
timeNthNdayInMonth
timeLastNdayInMonth
return timeDate objects on special dates. For the function timeLastDayInMonth the last day in a given month and year will be returned, for timeNdayOnOrAfter the date in the specified month that is a n-day on or after a given date, for timeNdayOnOrBefore the date that is a n-day on or before a given date, for timeNthNdayInMonth the nth ocurrance of a nday (nth = 1,...,5) in year, month, and for {timeLastNdayInMonth} the last nday in year, month.

is.timeDate
returns TRUE or FALSE depending on whether its argument is of timeDate type or not.

isWeekday
isWeekend
isBizday
weekDay
The first thres functions return logical vectors indicating if a date is a weekday, a weekend day, or a business.day. The function weekDay returns a three letter character string with the names of the day of the week.

Print Method:
prints the financial center and date and time vector for a timeDate object.

Summary Method:
returns a summary report of the details of a timeDate object. This includes the starting and end date, the number of dates the format and financial center in use.

Format Method:
returns an ISO conform formatted character string.

Note

These functions were written for Rmetrics users using R and Rmetrics under Microsoft's Windows XP operating system where time zones, daylight saving times and holiday calendars are not or insuffeciently supported. The functions are untested for other system environments, but may be used.

The usage of the Ical Library and the introduction of the FinCenter concept was originally develloped for R Version 1.5. The timeDate and timeSeries objects were added for R Version 1.8.1. Minor changes were made to adapt the functions for R Version 1.9.1. As a consequence, newer concepts like the Date objects were not yet considered and included in this collection of date and time concepts.

Note, the date/time conversion from an arbitry timezone to GMT cannot be unique, since date/time objects appear twice during the hour when DST changes. A bookkeeping which takes care if DST is effective or not is not yet included. However, in most applications this is not important since the markets are closed on weekends, especially at times when DST usually changes. It is planned for the future to implement the DST change properly.

The ISO-8601 midnight standard has been implemented. Note, that for example "2005-01-01 24:00:00" is a valid date/time string.

IT IS IMPORTANT THAT YOU SET YOUR ENVIRONMENT VARIABLE TZ TO 'GMT', OTHERWISE SOME OF THE 'TIMEDATE' FUNCTIONS WOULD NOT PROPERLY WORK!

Beside the examples given in the manual pages additional demo files are available with much more examples including also those from the book of Zivot and Wang.

Author(s)

Diethelm Wuertz for the Rmetrics R-port.

References

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

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.

See Also

We recommend to inspect the help pages for the POSIX time and date class, ?Dates, and the help pages from the contributed R packages chron and date.

Examples

## SOURCE("fBasics.A0-SPlusCompatibility")
## SOURCE("fBasics.E1-TimeDateClass")
## SOURCE("fBasics.Z1-BasicsTools")

## c -
   xmpBasics("\nStart: Create Character Vectors > ") 
   dts = c("1989-09-28", "2001-01-15", "2004-08-30", "1990-02-09")
   tms = c(  "23:12:55",   "10:34:02",   "08:30:00",   "11:18:23")
   dts; tms
   
## timeDate -
   xmpBasics("\nNext: Construct timeDate Object from Character Vector > ") 
   timeDate(dts, format = "%Y-%m-%d", FinCenter = "GMT" )
   timeDate(dts, format = "%Y-%m-%d", FinCenter = "Europe/Zurich") 
   timeDate(paste(dts, tms), format = "%Y-%m-%d %H:%M:%S", 
     zone = "GMT", FinCenter = "GMT")
   timeDate(paste(dts, tms), format = "%Y-%m-%d %H:%M:%S", 
     zone = "Europe/Zurich", FinCenter = "Europe/Zurich")
   timeDate(paste(dts, tms), format = "%Y-%m-%d %H:%M:%S", 
     zone = "GMT", FinCenter = "Europe/Zurich") 
    
## timeCalendar - 
   xmpBasics("\nNext: Create a timeDate Object From Calendar Atoms > ")
   timeCalendar( m = c(9, 1, 8, 2), d = c(28, 15, 30, 9), 
     y = c(1989, 2001, 2004, 1990), FinCenter = "GMT") 
   timeCalendar(m = c(9, 1, 8, 2), d = c(28, 15, 30, 9), 
     y = c(1989, 2001, 2004, 1990), FinCenter = "Europe/Zurich")
   timeCalendar(h = c(9, 14), min = c(15, 23)) 
  
## timeSequence - 
   xmpBasics("\nNext: Create a Regularly Spaced timeDate Objects > ")
   timeSequence(from = "2004-03-12", to = "2004-04-11", 
        format = "%Y-%m-%d", FinCenter = "GMT")  
   timeSequence(from = "2004-03-12", to = "2004-04-11", 
        format = "%Y-%m-%d", FinCenter = "Europe/Zurich")
   
## timeDate - 
   xmpBasics("\nNext: Note, ISO and American Formats are Auto-Detected > ")
   timeDate("2004-12-11", FinCenter = "GMT")    
   timeDate("12/11/2004", FinCenter = "GMT")    

[Package fCalendar version 201.10060 Index]