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 the Generation of 'timeDate' objects are:

       'timeDate'      S4: Creates 'timeDate' object from a character vector,
       '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,
       'summary.timeDate'  Summarizes details of a '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,
       'format.timeDate'   Formats 'timeDate' as ISO conform character string,

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

     myUnits
     currentYear

     timeDate(charvec = Sys.timeDate(), format = NULL,
         zone = myFinCenter, FinCenter = myFinCenter)

     timeCalendar(y = currentYear, m = 1:12, d = 1,
         h = 0, min = 0, s = 0,
         zone = myFinCenter, FinCenter = myFinCenter)

     timeSequence(from, to = format(Sys.time(), "%Y-%m-%d"),
         by = c("day", "year", "quarter", "month", "week", "hour", "min", "sec"),
         length.out = NULL, format = NULL,
         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, ...)

     show.timeDate(object)

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

_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: [show][summary] - 
           an object of class 'timeDate'. 

       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. 

     *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 'POSIXct' 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 class '"timeDate"'
     object. 

     _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 conformly 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; some improvements: 
     Martin Maechler.

_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:

     ## timeDate -

        Sys.timeDate()           # direct
        timeDate(Sys.time())     # transformed from "POSIX(c)t"
        
        # Local Time in Zurich
        timeDate(Sys.time(), FinCenter = "Zurich")  

        # Character Vector Strings:
        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

        t1 <- timeDate(dts, format = "%Y-%m-%d", FinCenter = "GMT" )
        t1
        stopifnot(identical(t1, timeDate(dts, FinC = "GMT"))) # auto-format
        
        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), zone = "Europe/Zurich", FinCenter = "Europe/Zurich")
        
        timeDate(paste(dts, tms), format = "%Y-%m-%d %H:%M:%S",
                 zone = "GMT", FinCenter = "Europe/Zurich")

        ## non standard format:
        timeDate(paste(20:31, "03.2005", sep="."), format = "%d.%m.%Y")

        # Note, ISO and American Formats are Auto-Detected:
        timeDate("2004-12-31", FinCenter = "GMT")
        timeDate("12/11/2004", FinCenter = "GMT")
        timeDate("1/31/2004") # auto-detect American format

        ## from POSIX?t, and using NAs
        lsec <- as.POSIXlt(.leap.seconds) ; lsec[c(2,4:6)] <- NA
        timeDate(lsec)

        dtms <- paste(dts,tms)
        dtms[2:3] <- NA
        timeDate(dtms, FinCenter = "Europe/Zurich")# but in GMT


     ## timeCalendar -
        
        currentYear
        timeCalendar() # 12 months of current year
        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")

     ## print | summary | format -

        tC = timeCalendar()
        print(tC)
        summary(tC)
        format(tC)

