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

                                     
                                     *Math Operations with 'timeDate' Objects:*
        1  '[.timeDate'              Extracts, replaces subsets from 'timeDate' objects,
        2  '+.timeDate'              Performs arithmetic + ops on 'timeDate' objects,
        3  '-.timeDate'              Performs arithmetic - ops on 'timeDate' objects,
        4  'Ops.timeDate'            'Ops' generic functions for 'timeDate' objects,
        5  'diff.timeDate'           Returns suitably lagged and iterated differences,
        6  'difftimeDate'            Returns a difference of two 'timeDate' objects,
        7  'c.timeDate'              Concatenates objects of class 'timeDate',
        8  'rep.timeDate'            Replicates objects of class 'timeDate',
        9  'start.timeDate'          Extracts the first object of a 'timeDate' vector,
       10  'end.timeDate'            Extracts the last object of a 'timeDate' vector,
       11  'modify.timeDate'         Sorts, rounds or truncates a 'timeDate' object,
       12  'rev.timeDate'            Reverts  a 'timeDate' vector object.
                                     
                                     *Transformations of 'timeDate' Objects:*
        1  'as.character.timeDate'   Returns a 'timeDate' object as character string,
        2  'as.data.frame.timeDate'  Returns a 'timeDate' object as data frame,
        3  'as.POSIXct.timeDate'     Returns a 'timeDate' object as POSIXct object,
        4  'as.POSIXlt'              As POSIXlt, Use Method (Overwrite),
        5  'as.POSIXlt.default'      Default method for POSIXlt,
        6  'julian.timeDate'         Returns Julian day counts since 1970-01-01,
        7  'julian.POSIXt'           A Julian Patch,
        8  'atoms.timeDate'          Returns date/time atoms from a 'timeDate' object,
        9  'atoms'                   Extract atoms, Use Method,
       10  'atoms.default'           Default method for atoms,
       11  '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. 

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

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

     Diethelm Wuertz for this R-port.

_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"]

