TimeDateMethods           package:fBasics           R Documentation

_t_i_m_e_D_a_t_e _M_e_t_h_o_d_s

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

     A collection and description of methods for  objects of class
     'timeDate'. Included are S3  methods for mathematical operations
     and for  transformations between different representations  of
     date/time objects. 

     IMPORTANT: 
      The 'timeDate' and 'timeSeries' classes are so far tested only
     under MS Windows XP operating system. Note, that your time zone
     environment variable must be set to "GMT". The reason for this is,
     that the functions work internally with "GMT" POSIX date and time
     objects whereas the Daylight Saving Time is  added on top of this
     through the information in the Ical Calendar Library. 

     The methods for Math Operations with 'timeDate' Objects are:

       '[.timeDate'       Extracts, replaces subsets from 'timeDate' objects,
       '+.timeDate'       Performs arithmetic + ops on 'timeDate' objects,
       '-.timeDate'       Performs arithmetic - ops on 'timeDate' objects,
       'Ops.timeDate'     'Ops' generic functions for 'timeDate' objects,
       'diff.timeDate'    Returns suitably lagged and iterated differences,
       'difftimeDate'     Returns a difference of two 'timeDate' objects,
       'c.timeDate'       Concatenates objects of class 'timeDate',
       'rep.timeDate'     Replicates objects of class 'timeDate',
       'start.timeDate'   Extracts the first object of a 'timeDate' vector,
       'end.timeDate'     Extracts the last object of a 'timeDate' vector,
       'modify.timeDate'  Sorts, rounds or truncates a 'timeDate' object,
       'rev.timeDate'     Reverts  a 'timeDate' vector object.

     The methods for Transformations of 'timeDate' Objects are:

       'as.character.timeDate'   Returns a 'timeDate' object as character string,
       'as.data.frame.timeDate'  Returns a 'timeDate' object as data frame,
       'as.POSIXct.timeDate'     Returns a 'timeDate' object as POSIXct object,
       'as.POSIXlt'              As POSIXlt, Use Method (Overwrite),
       'as.POSIXlt.default'      Default method for POSIXlt,
       'julian.timeDate'         Returns Julian day counts since 1970-01-01,
       'julian.POSIXt'           A Julian Patch,
       'atoms.timeDate'          Returns date/time atoms from a 'timeDate' object,
       'atoms'                   Extract atoms, Use Method,
       'atoms.default'           Default method for atoms,
       'months.timeDate'         Extract months atom from a 'timeDate' object.

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

     \method{[}{timeDate}(x, ..., drop = TRUE)
     \method{+}{timeDate}(e1, e2)
     \method{-}{timeDate}(e1, e2)
     ## S3 method for class 'timeDate':
     Ops(e1, e2)
     ## S3 method for class 'timeDate':
     diff(x, lag = 1, differences = 1, ...)
     difftimeDate(time1, time2, 
             units = c("auto", "secs", "mins", "hours", "days", "weeks"))

     ## S3 method for class 'timeDate':
     c(..., recursive = FALSE)
     ## S3 method for class 'timeDate':
     rep(x, times, ...)
     ## S3 method for class 'timeDate':
     start(x, ...)
     ## S3 method for class 'timeDate':
     end(x, ...)
     ## S3 method for class 'timeDate':
     modify(x, method = c("sort", "round", "trunc", 
             units = c("secs", "mins", "hours", "days"))
     ## S3 method for class 'timeDate':
     rev(x)

     ## S3 method for class 'timeDate':
     as.character(x, ...)
     ## S3 method for class 'timeDate':
     as.data.frame(x, ...)
     ## S3 method for class 'timeDate':
     as.POSIXct(x, tz = "")
     ## S3 method for class 'timeDate':
     julian(x, ...)
     ## S3 method for class 'timeDate':
     atoms(x, ...)
     ## S3 method for class 'timeDate':
     months(x, abbreviate = NULL)

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

abbreviate: [months] - 
           currently not used. 

differences: [lag] - 
           an integer indicating the order of the difference. 

  e1, e2: ["+"][["-"]["Ops"] - 
           usually objects of class 'timeDate', in the case of addition
          and subtraction 'e2' may be of class 'numeric'. 

     lag: [lag] - 
           an integer indicating which lag to use.   

recursive: [c] - 
           a logical. If recursive  is set to 'TRUE', the function 
          recursively descends through lists combining all their
          elements  into a vector.  

time1, time2: [difftime] - 
           two objects objects of class 'timeDate'. 

   times: [rep] - 
           an optional non-negative integer. A vector giving the number
          of  times to repeat each element if of length 'length(x)', or
           to repeat the whole vector if of length '1'. 

      tz: inputs the time zone to POSIX objects, i.e. the time zone, 
          'zone', or financial center string, 'FinCenter',  as used by
          'timeDate' objects. 

   units: a character string denoting the date/time units in which the 
          results are desired. 

       x: an object of class 'timeDate'. 

     ...: arguments passed to other methods. 

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

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

     '"["' 
      returns a subset from a 'timeDate' object. 

     '"+"'
      '"-"' 
      the plus operator '"+"' performs arithmetic "+" operation on 
     'timeDate' objects, and  the minus operator '"-"' returns a
     'difftime' object if  both arguments 'e1' and 'e2' are 'timeDate'
     objects,  or returns a 'timeDate' object 'e2' seconds earlier than
      'e1'. 

     'Ops.timeDate' 
      returns the 'Ops' grouped object. 

     'diff'
      'difftimeDate' 
      For the first function, 'diff.timeDate', if 'x' is a vector  of
     length 'n' and 'differences=1', then the computed result  is equal
     to the successive differences 'x[(1+lag):n] - x[1:(n-lag)]'.  If
     'difference' is larger than one this algorithm is applied
     recursively to 'x'. Note that the returned value is a vector 
     which is shorter than 'x'. The second function, 'difftimeDate',
     takes a difference of two  'timeDate' objects and returns an
     object of class 'difftime'  with an attribute indicating the
     units. 

     'c'
      'rep' 
      'c' returns all its arguments to be coerced to a 'timeDate' 
     object which is the type of the returned value, and  'rep' returns
     a vector of repeated elements belonging to the  same class as 'x'. 

     'start'
      'end' 
      return from 'x' the earliest or latest entry as an object of 
     class 'timeDate', respectively. 

     'modify'
      'rev' 
      'modify' returns 'x' as a sorted, rounded or truncated  object of
     the same class, depending on the 'method' selection,  and 'rev'
     returns 'x' as a 'timeDate' object in reversed  order. 

     'as.character'
      'as.data.frame' 
      return a 'timeDate' object trnasformed into a character or a data
     frame formatted object. 

     'as.POSIXct' 
      return a 'timeDate' object trnasformed into a POSIX type
     formatted object. 

     'julian' 
      return a 'timeDate' object as a Julian count. 

     'atoms'
      'months.timeDate' 
      extrac from a 'timeDate' object the calendar atoms, i.e, the
     year, month, day, and optionally hour, minute and second. 

_N_o_t_e:

     These functions were written for Rmetrics users using R and
     Rmetrics under Microsoft's Windows XP operating system where timze
     zones,  daylight saving times and holiday calendars are
     insuffeciently  supported. The functions are untested for other
     system environments,  but may be used.

     Please, also be aware of the notes remarked in the help page
     describing the 'timeDate' class.

     IT IS IMPORTANT THAT YOU SET YOUR ENVIRONMENT VARIABLE TZ TO
     'GMT', OTHERWISE SOME OF THE 'TIMEDATE' FUNCTIONS WOULD NOT
     PROPERLY WORK!

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

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

     ## c -
        xmpBasics("\nStart: Create Character Vectors > ") 
        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
        
     ## "+/-" - 
        xmpBasics("\nStart: Add One Day to a Given timeDate Object > ")
        GMT = timeDate(dts, FinCenter = "GMT")
        ZUR = timeDate(dts, FinCenter = "Europe/Zurich")
        GMT + 24*3600
        ZUR[2] - ZUR[1]
       
     ## "[" - 
        xmpBasics("\nNext: Subsets from and Lops for timeDate Objects > ")
        GMT[GMT < GMT[2]]
        ZUR[ZUR < ZUR[3]] == ZUR[1:3]

     ## diff - 
        xmpBasics("\nNext: Suitably Lagged and Iterated Differences > ")
        diff(GMT)
        diff(GMT, lag = 2)
        diff(GMT, lag = 1, diff = 2)
        difftimeDate(GMT[1:2], GMT[-(1:2)])
        
     ## c | rep - 
        xmpBasics("\nNext: Concatenate and Replicate timeDate Objects > ") 
        c(GMT[1:2], ZUR[1:2])
        c(ZUR[1:2], GMT[1:2])
        rep(ZUR[2], times = 3)
        rep(ZUR[2:3], times = 2) 

     ## round | truncate -
        xmpBasics("\nNext: Round and Truncate timeDate Objects > ")
        modify(GMT, "round", "days")
        modify(ZUR, "round", "days")
        modify(GMT, "trunc", "days")
        modify(ZUR, "trunc", "days")

     ## start | end | sort - 
        xmpBasics("\nNext: Extract First/Last, Sort timeDate Objects > ")
        c(start(ZUR), end(ZUR))
        modify(ZUR, "sort") 

     ## as -
        xmpBasics("\nNext: Convert timeDate Objects to Other Objects > ")
        as.character(ZUR)
        as.data.frame(ZUR)
        as.POSIXct(ZUR)
        
     ## julian - 
        xmpBasics("\nNext: Julian Time in Days Since 1970-01-01 > ")
        julian(ZUR)  
        as.integer(julian(ZUR))
        julian(ZUR, "days")  
        as.integer(julian(ZUR, "days"))
         
     ## atoms - 
        xmpBasics("\nNext: Atoms from a timeDate Object > ")
        atoms(ZUR)
        atoms(ZUR)[,3]
        atoms(ZUR)[, "d"]

