timeDate-class           package:fCalendar           R Documentation

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

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

     The class 'timeDate' represents date and time objects.

_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 in most cases 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 in some
     cases operating system dependent and especially under MS Windows
     several  problems appeared over the time in the management of time
     zones and  day light saving times. Rmetrics overcomes 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 SPlus/FinMetrics may also be used within the
     R/Rmetrics 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 is your currency, 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/Rmetrics delivers with 
     such a date/time concept on every computer independent of the
     operating  systemin 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 (i.e. its length), the 'format'
     specification  slot and the 'FinCenter' slot which holds the name
     of the financial  center. By default this is the value 

     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:*

     Rmetrics has implemented several methods to represent 'timeDate'
     objects. For example, the  print method returns the date/time in
     square '"[]"' brackets  to distinguish 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:*

     Rmetrics supports methods to perform many mathematical operations.
     Included are methods  to extract or  to replace subsets from
     'timeDate' objects,  to perform arithmetic '"+"' and '"-"'
     operations,  to group 'Ops' generic functions, to return suitably
     lagged and iterated differences 'diff',  to return differences
     'difftimeDate' of two 'timeDate'  objects, to concatenate objects,
     to replicate objects,  to 'round' objects,  to truncate objects
     using 'trunc',  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, among other functions. 

     *Transformation of Objects:*

     Rmetrics has also functions to transform dat/time 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. One can extract
     date/time 'atoms' from calendar  dates, and the 'months' atoms
     from a 'timeDate'  object.

_O_b_j_e_c_t_s _f_r_o_m _t_h_e _C_l_a_s_s:

     Objects can be created for example by calls of the functions 
     'timeDate', 'timeCalender' and 'timeCalendar' among others.

_S_l_o_t_s:



     '_D_a_t_a': Object of class '"POSIXct"':  a vector of POSIXct dates
          and times always related to "GMT". 

     '_f_o_r_m_a_t': Object of class '"character"':  a character string
          denoting the format specification of  the input Data
          character vector.

     '_F_i_n_C_e_n_t_e_r': Object of class '"character"':  a character string
          with the the location of the financial center named as
          "continent/city", or just "city".


_M_e_t_h_o_d_s:



     _s_h_o_w 'signature(object = "timeDate")':  prints an object of class
          'timeDate'. 


_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 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 time zone to GMT
     cannot be unique, since date/time objects appear twice during the
     hour when DST changes and the isdt flag was not recorded. 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 supporting this facility.

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

     Also available is an automated format recognition, so the user has
     not longer specify the format string for the most common date/time
     formats.

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

     ## Examples for Objects of class 'timeDate':

     ## 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")
        dts
        tms = c(  "23:12:55",   "10:34:02",   "08:30:00",   "11:18:23")
        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)

