TimeDateClass           package:fCalendar           R Documentation

_t_i_m_e_D_a_t_e _C_l_a_s_s

_D_e_s_c_r_i_p_t_i_o_n:

     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,

_U_s_a_g_e:

     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

_A_r_g_u_m_e_n_t_s:

      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. 

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     '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. 

_N_o_t_e:

     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).

_A_u_t_h_o_r(_s):

     Diethelm Wuertz for the Rmetrics R-port.

_R_e_f_e_r_e_n_c_e_s:

     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.

_S_e_e _A_l_s_o:

     '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'.

_E_x_a_m_p_l_e_s:

     ## 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)   

