| TimeDateClass {fCalendar} | R Documentation |
A collection and description of functions and methods
for managing date and time around the globe for any
financial center. The concept allows for dealing
with several time zones at the same time, day light
saving time and holiday calendars independently of the
date and time specifications of the operating system
implemented on a specific computer.
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, |
is.timeDate | Tests if the object is of class 'timeDate', |
timeCalendar | Creates 'timeDate' object from calendar atoms, |
timeSequence | Creates regularly spaced object of class 'timeDate', |
seq | A synonyme function for timeSequence, |
Sys.timeDate | Returns system time as an object of class 'timeDate'. |
The functions to represent 'timeDate' objects:
print.timeDate | Prints 'timeDate' Object, |
plot.timeDate | Plots with GMT 'timeDate' x-axis, |
points.timeDate | Adds points to a 'timeDate' plot, |
lines.timeDate | Adds lines to a 'timeDate' plot, |
summary.timeDate | Summarizes details of a 'timeDate' object, |
format.timeDate | Formats 'timeDate' as ISO conform character string, |
myFinCenter
rulesFinCenter(FinCenter = myFinCenter)
listFinCenter(pattern = "*")
timeDate(charvec = Sys.timeDate(), format = NULL, zone = myFinCenter,
FinCenter = myFinCenter)
timeCalendar(y = currentYear, m = 1:12, d = 1, h = NULL, min = NULL,
s = NULL, zone = myFinCenter, FinCenter = myFinCenter)
timeSequence(from = "2004-01-01", to = format(Sys.time(), "%Y-%m-%d"),
by = c("day", "year", "quarter", "month", "week", "hour", "min", "sec"),
length.out = NULL, format = "", zone = myFinCenter, FinCenter = myFinCenter)
Sys.timeDate(FinCenter = myFinCenter)
## S3 method for class 'timeDate':
seq(from, to, by = c("day", "year", "quarter", "month",
"week", "hour", "min", "sec"), length.out = NULL, ...)
is.timeDate(object)
## S3 method for class 'timeDate':
print(x, ...)
## S3 method for class 'timeDate':
plot(x, y, ...)
## S3 method for class 'timeDate':
summary(object, ...)
## S3 method for class 'timeDate':
format(x, ...)
currentYear
myUnits
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 |
[timeSequence] - starting date, required, and end date, optional. If supplied to must be after from, [seq] - cr in this case the from and to dates must be objects
of class timeDate.
|
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. |
length.out |
length.out integer, optional. Desired length of the sequence, if specified "to" will be ignored. |
method |
[modify] - a character string defining the modification method, one of "sort", "round", or "trunc".
|
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][plot] - an object of class timeDate.
|
y, m, d |
[timeCalendar] - calendar years (e.g. 1997), defaults are 1960, calendar months (1-12), defaults are 1, and calendar days (1-31), defaults are 1, [plot] - a numeric vector. |
zone |
the time zone or financial center where the data were recorded. |
... |
arguments passed to other methods. |
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.
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.
Mathematical Operations:
This is a collection of S3 methods for objects of class timeDate
to perform mathematical operations. Included are methods to extracts
or replace subsets from timeDate objects, to perform arithmetic
"+" and "-" operations, to group 'Ops' generic functions,
to return suitably lagged and iterated differences, to return differences
of two timeDate objects, to concatenate objects, to replicate
objects, to rounds objects, to truncates objects, to extract the first
or last entry of a vector, to sort the objects of the elements of a
date/time vector, and to revert timeDate vector objects.
Transformation of Objects:
This is a collection of S3 methods for objects of class timeDate
to transform those objects between different representations.
Included are methods to transform timeDate objects to character
strings, to data frames, to POSIXct or POSIXlt objects, to Julian
counts, to extract date/time atoms from calendar dates, and to
extract the months atom from a timeDate object.
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'.
is.timeDate
returns TRUE or FALSE depending on whether its
argument is of timeDate type or not.
print
prints the financial center and date and time vector for a
timeDate object.
summary
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
returns an ISO conform formatted character string.
originally, 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. With R Version 2.3.0 a major
update has been made adding many new generic functions and renaming
a few already existing functions, please be aware of this.
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 necessary 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.
Beside the examples given in the manual pages additional demo and test files are available with much more examples including also those from the book of Zivot and Wang (2003).
Diethelm Wuertz for the Rmetrics R-port.
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.
timeDateCoercion, timeDateSpecDates
We also 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.
## SOURCE("fCalendar.3A-TimeDateClass")
## myFinCenter -
myFinCenter
## - Character Vecor Strings:
dts = c("1989-09-28", "2001-01-15", "2004-08-30", "1990-02-09")
dts
tms = c( "23:12:55", "10:34:02", "08:30:00", "11:18:23")
tms
## timeDate -
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 -
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 -
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 -
# Note, ISO and American Formats are Auto-Detected
timeDate("2004-12-11", FinCenter = "GMT")
timeDate("12/11/2004", FinCenter = "GMT")
## print | summary | format -
tC = timeCalendar()
print(tC)
summary(tC)
format(tC)