Package of calendar, date, time tools and utilities for Rmetrics.
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 Rmetrics has added 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
Date and time stamps are represented by an S4 object of class 'timeDate'.
1 2 3 4 5 6 7
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
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
Sys.timeDate – returns the current date and time as a
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
# 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
NOTE: Rmetrics always uses the midnight standard on dates and
times. You can see it with
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
to, or when
from is missing, by setting
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
# 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.
1 2 3 4 5 6 7 8 9 10 11
# 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
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 can add and subtract dates and times,
and perform logical operations on 'timeDate' objects.
1 2 3 4 5 6 7 8 9 10 11 12
You can generate suitable lagged and iterated differences:
diff.timeDate – Returns suitably lagged and iterated differences.
1 2 3 4 5 6 7 8
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'.
1 2 3 4 5 6 7 8 9 10 11
Subsetting a 'timeDate' is a very important issue in the management of
dates and times. Rmetrics offers several functions which are useful in
"[" – 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
end time stamp together with the total number of
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
# 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, end = tC) cut(tC, from = tC, to = tC) tC[tC < tC] # 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.
1 2 3 4 5 6 7 8 9 10 11 12
time stamps for equally sized blocks.
blockStart – Creates start dates for equally sized blocks,
blockEnd – Creates end dates for equally sized blocks.
1 2 3 4 5 6 7 8 9 10
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
objects into other objects.
as.timeDate – Implements Use Method,
as.timeDate.default – default Method,
as.timeDate.POSIXt – returns a 'POSIX' object as 'timeDate'
as.timeDate.Date – returns a 'POSIX' object as 'timeDate'
as.character.timeDate – Returns a 'timeDate' object as
as.double.timeDate – returns a 'timeDate' object as 'numeric'
as.data.frame.timeDate – returns a 'timeDate' object as
as.POSIXct.timeDate – returns a 'timeDate' object as 'POSIXct'
as.POSIXlt.timeDate – returns a 'timeDate' object as 'POSIXlt'
as.Date.timeDate – returns a 'timeDate' object as 'Date'
Users or maintainers of other date/time classes can add their own
generic functions. For example
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14
# 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
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
listFinCenter. The DST rules for specific
financial center can be viewed by their name, e.g.
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
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:
1 2 3 4 5 6 7 8
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:
1 2 3 4 5 6 7
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 :
1 2 3 4 5 6
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
1 2 3 4 5 6
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.
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
timeLastDayInMonth – Computes the last day in a given month
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"
timeNdayOnOrBefore –b Computes date that is a "on-or-before"
timeNthNdayInMonth – Computes n-th occurrence of a n-day in
timeLastNdayInMonth – Computes the last n-day in
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.
1 2 3 4 5 6 7 8
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.
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.