TimeSeriesClass           package:fBasics           R Documentation

_t_i_m_e_S_e_r_i_e_s _C_l_a_s_s _a_n_d _M_e_t_h_o_d_s

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

     A collection and description of functions and methods  dealing
     with regular and irregular 'timeSeries' objects.  Dates and times
     are implemented as 'timeDate' objects.  Included are functions and
     methods for the generation  and representation of 'timeSeries'
     objects, and for  mathematical operations.           

     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 functions and methods for the Generation of 'timeSeries'
     Objects are:         

       'timeSeries'        Creates a 'timeSeries' object from scratch,
       'read.timeSeries'   Reads a 'timeSeries' from a spreadsheet,
       'as.timeSeries'     S3: Creates dummy 'time Series' from a 'matrix',
       'is.timeSeries'     S3: Tests for a 'timeSeries' object,
       'print.timeSeries'  S3: Print method for a 'timeSeries' object,
       'plot.timeSeries'   S3: Plot method for a 'timeSeries' object,
       'lines.timeSeries'  S3: Lines method for a 'timeSeries' object,
       'Ops.timeSeries'    S3: Arith method for a 'timeSeries' object,
       '[.timeSeries'      S3: "[" method for a 'timeSeries' object,
       'head.timeSeries'   S3: returns the head of a 'timeSeries' object,
       'tail.timeSeries'   S3: returns the tail of a 'timeSeries' object.

     The functions and methods for the Representation of 'timeSeries'
     Objects are:         

       'seriesData'                Extracts data slot from a 'timeSeries',
       'seriesPositions'           Extracts positions slot from a 'timeSeries',
       'start.timeSeries'          S3: Extracts start date of a 'timeSeries',
       'end.timeSeries'            S3: Extracts end date of a 'timeSeries',
       'as.vector.timeSeries'      S3: Converts a 'timeSeries' to a vector,
       'as.matrix.timeSeries'      S3: Converts a 'timeSeries' to a matrix,
       'as.data.frame.timeSeries'  S3: Converts a 'timeSeries' to a data.frame.

     The functions and methods for Math Operations of 'timeSeries'
     Objects are:         

       'applySeries'       Applies a function to margins of a 'timeSeries',
       'alignDailySeries'  Aligns a daily 'timeSeries' to new positions,
       'cutSeries'         Cuts out a piece from a 'timeSeries' object,
       'mergeSeries'       Merges a 'timeSeries' object with a 'matrix',
       'ohlcDailyPlot'     Plots openhighlowclose bar chart,
       'revSeries'         S3: rev method for a 'timeSeries' object,
       'diffSeries'        S3: diff method for a 'timeSeries' object,
       'lagSeries'         S3: lag method for a 'timeSeries' object,
       'returnSeries'      Computes returns from a 'timeSeries' object.

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

     timeSeries(data, charvec, units = NULL, format = "ISO", zone = "GMT", 
         FinCenter = myFinCenter, title = NULL, documentation = NULL, ...) 
     read.timeSeries(file, zone = "GMT", FinCenter = "", title = "", 
         documentation = "", sep = ";")
         
     as.timeSeries(x, dimnames = TRUE, format = "")
     is.timeSeries(object) 
     ## S3 method for class 'timeSeries':
     print(x, ...)
     ## S3 method for class 'timeSeries':
     plot(x, reference.grid = TRUE, lty = 1, ...) 
     ## S3 method for class 'timeSeries':
     lines(x, ...)
     ## S3 method for class 'timeSeries':
     Ops(e1, e2)
     \method{[}{timeSeries}(x, i = min(1, nrow(x@Data)):nrow(x@Data), 
         j = min(1, ncol(x@Data)):ncol(x@Data))
     ## S3 method for class 'timeSeries':
     head(x, ...)
     ## S3 method for class 'timeSeries':
     tail(x, ...)

     seriesData(object)
     seriesPositions(object)
     ## S3 method for class 'timeSeries':
     start(x, ...)
     ## S3 method for class 'timeSeries':
     end(x, ...)
     ## S3 method for class 'timeSeries':
     as.vector(x, mode = "any")
     ## S3 method for class 'timeSeries':
     as.matrix(x)
     ## S3 method for class 'timeSeries':
     as.data.frame(x, row.names = NULL, optional = NULL)

     applySeries(x, from = NULL, to = NULL, FUN = colAvgs, colNames = NULL, ...) 
     cutSeries(x, from, to)
     diffSeries(x, lag = 1, diff = 1, trim = FALSE, pad = NA)
     lagSeries(x, k = 1, trim = FALSE, colNames = NULL)
     mergeSeries(x, y, units = NULL)
     returnSeries(x, type = c("continuous", "discrete"), percentage = FALSE, 
         trim = TRUE, digits = 4)
     revSeries(x)
         
     alignDailySeries(x, method = c("before", "after", "interp", "fillNA"), 
         include.weekends = FALSE)
     ohlcDailyPlot(x, volume = TRUE, colOrder = c(1:5), units = 1e6, 
         xlab = c("Date", "Date"), ylab = c("Price", "Volume"), 
         main = c("O-H-L-C", "Volume"), grid.nx = 7, grid.lty = "solid", ...) 

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

 charvec: a character vector of dates and times. 

colNames: [applySeries][lag] - 
           a character string, which allows to overwrite the current
          column names of a 'timeSeries' object. By default  'NULL'
          which means that the column names are selected automatically. 

colOrder: [ohlcDailyPlot] - 
            an integer vector which gives the order of the prices and
          the volume in the input object. By default the following
          order of columns from 1 to 5 is assumed: Open, high, low,
          close, and volume. 

    data: a 'data.frame' or a 'matrix' object of numeric data. 

    diff: [diffSeries] - 
           an integer indicating the order of the difference. By
          default 1. 

  digits: [returnSeries] - 
           an integer value. The number of digits to be printed in the 
          output. 

dimnames: [as.timeSeries] - 
           a logical, if 'TRUE' the dimension names of the matrix are
          assigned to the time series object. 

documentation: optional documentation string, or a vector of character
          strings. 

  e1, e2: [Ops] - 
              two objects of class 'timeSeries'. 

    file: the filename of a spreadsheet data set from which to import
          the data records. 

FinCenter: a character with the the location of the  financial center
          named  as "continent/city".  

  format: the format specification of the input character vector, 
           [as.timeSeries] - 
           a character string with the format in POSIX notation to be
          passed  to the time series object. 

from, to: starting date and end date, 'to' must be after 'from'. 

     FUN: [applySeries] - 
           a function to use for aggregation, by default 'colAvgs'. 

grid.lty, grid.nx: [ohlcDailyPlot] - 
           The type of grid line and the number of grid lines used in
          the plot. 

    i, j: ["["] - 
            index arguments used for subsettings. 

include.weekends: [alignDailySeries] - 
           a logical value. Should weekend dates be included or removed
          from the series. 

       k: [lagSeries] - 
              an integer value. The number of lags (in units of
          observations). By default 1. 

     lag: [diffSeries] - 
           an integer indicating which lag to use. By default 1. 

     lty: [plot] - 
           an integer value, the typ of line to be drawn. By default 1,
          a solid line. 

    main: [ohlcDailyPlot] - 
           a character string to title the price and volume plot. 

  method: [alignDailySeries] - 
           the method to be used for the alignment. A character string,
          one of '"before"', use the data from the row whose position
          is just before the unmatched position, or '"after"', use the 
          data from the row whose position is just after the unmatched 
          position, or '"linear"', interpolate linearly between 
          '"before"' and '"after"'.  

    mode: [as.vector] - 
           A character string giving an atomic mode, or '"any"'. 

optional, row.names: [as.data.frame] - 
           both arguments are currently not used. 

  object: [is][seriesData][seriesPositions] -     an object of class
          'timeSeries'. 

     pad: [diffSeries] - 
           which value should get the padded values? By default 'NA'.
          Another choice often used would be zero. 

percentage: [returnSeries] - 
           a logical value. By default 'FALSE', if 'TRUE' the  series
          will be expressed in percentage changes. 

reference.grid: [plot] - 
               a logical value. Should a grid be added to the plot? By
          default 'TRUE'. 

     sep: [read.timeSeries] - 
           the field seperator used in the spreadsheet file to separate
           columns. 

   title: an optional title string, if not specified the inputs data 
          name is deparsed. 

    trim: [diffSeries][returnSeries] - 
           a logical value. By default 'TRUE', the first missing 
          observation in the return series will be removed.  

    type: [returnSeries] - 
           a character string specifying how to compute the returns.
          Valid  choices are: 'continuous' and 'discrete'. For the 
          default 'type="continuous"', the returns are calculated as 
          the logarithmic differences, otherwise if 'type="discrete"', 
          the returns are calculated as percentage changes.  

   units: an optional units string, 'NULL' defaults an empty string. 
           [mergeSeries] - 
           an integer string or vector which allows to rename the units
           in the units Slot of the 'timeSeries' object. 
           [ohlcDailyPlot] - 
           a numeric value, specifying in which multiples the volume
          should be referenced on the plot labels. By default 1e6, i.e.
          in units of 1 Million. 

  volume: [ohlcDailyPlot] - 
           a logigical value. Should a volume plot added to the OHLC
          Plot. By default 'TRUE'. 

       x: [as] - 
              a 'matrix' type object to be converted.
           [as.vector][as.matrix][as.data.frame] -
           [applySeries] - 
           [cut][end][mergeSeries][plot][print][rev][start] - 
           an object of class 'timeSeries'. 

xlab, ylab: [ohlcDailyPlot] - 
           two string vectors to name the x and y axis of the price and
          volume plot. 

       y: [mergeSeries] - 
              a 'matrix' type object to be merged with an object of
          class 'timeSeries'. Must have the same number of rows. 

    zone: the time zone or financial center where the data were
          recorded. 

     ...: arguments passed to other methods. 

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

     *Generation of Time Series Objects:* 

     We have defined a 'timeSeries' class which is in many aspects
     similar to the S-Plus class with the same name, but has also some
     important differeneces. The class has seven Slots, the 'Data' slot
     which holds  the time series data in matrix form, the 'position'
     slot which holds the time/date as a character vector, the 'format'
     and 'FinCenter' slots which are the same as for the 'timeDate'
     object, the 'units' slot which holds the column names of the data
     matrix, and a 'title' and a documentation' slot which hold
     descriptive character strings. Date and time is managed in the
     same way as for 'timeDate' objects.

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

     'timeSeries'
      'read.timeSeries'
      'as.timeSeries' 
      return a S4 object of class 'timeSeries'. 

     'seriesData'
      'seriesPositions' 
      extract the '@Data' and '@position' slots from a  'timeSeries'
     object. Thus, 'seriesData' returns an  object of class 'matrix',
     and 'seriesPositions' returns an object of class 'timeDate'. 

     'is.timeSeries' 
      returns 'TRUE' or 'FALSE' depending on whether its argument is of
     'timeSeries' type or not. 

     'aggregateSeries'
      'applySeries'
      'cutSeries'
      'mergeSeries'
      'returnSeries'
      'revSeries' 
      return a S4 object of class 'timeSeries'. 

     'end, start' 
      return a S4 object of class 'timedate'. These are the  start and
     end dates of a 'timeSeries' object. 

     'as.vector'
      'as.matrix'
      'as.data.frame' 
      these are methods which convert a S4 object of class 'timeSeries'
     either to a vector, a matrix or to a data frame. 

     'plot'
      'print' 
      plot and print methods for an object of class 'timeSeries'. Note
     that the plot function requires the packages 'its' and 'Hmisc'. 

_N_o_t_e:

     These functions were written for Rmetrics users using R and
     Rmetrics under Microsoft's Windows 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.

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

     ## data - 
        xmpBasics("\nStart: Load Microsoft Data > ")
        data(msft.dat)
        myFinCenter = "GMT"
        msft.dat[1:3, ]

     ## timeSeries -
        xmpBasics("\nNext: Create a timeSeries Object > ")
        close = msft.dat[, 5]
        ts = timeSeries(close, as.character(msft.dat[, 1]), format = "%m/%d/%Y", 
          units = "MSFT", zone = "GMT", FinCenter = "GMT")
        class(ts)
        ts[1:3,]
        c(start(ts), end(ts))
         
     ## cutSeries -    
        xmpBasics("\nNext: Cut out April Data from 2001 > ")
        ts.Apr01 = cutSeries(ts, "2001-04-01", "2001-04-30") 
        ts.Apr01

     ## returnSeries -  
        xmpBasics("\nNext: Compute Returns > ")
        # Compute Returns:
        args(returnSeries)
        # Continuous Returns:
        returnSeries(ts.Apr01)
        # Discrete Returns:
        returnSeries(ts.Apr01, type = "discrete")
        # Don't trim:
        returnSeries(ts.Apr01, trim = FALSE)
        # Use Percentage Values:
        returnSeries(ts.Apr01, percentage = TRUE, trim = FALSE)

     ## mergeSeries -    
        xmpBasics("\nNext: Merge Series with Returns > ")
        # Include last Day from March:
        ts.APR01 = cutSeries(ts, "2001-03-29", "2001-04-30") 
        ts.merged = mergeSeries(x = ts.APR01, 
          returnSeries(ts.APR01, trim = FALSE)@Data, units = c("MSFT", "Returns"))
        ts.merged
         
     ## alignDailySeries -     
        xmpBasics("\nNext: Align with NA > ")
        args(alignDailySeries)
        ts.ret = returnSeries(ts.APR01, trim = TRUE)
        GoodFriday(2001)   
        EasterMonday(2001) 
        alignDailySeries(ts.ret, method = "fillNA", include.weekends = FALSE)
        alignDailySeries(ts.ret, method = "fillNA", include.weekends = TRUE)
         
     ## alignDailySeries - 
        xmpBasics("\nNext: Interpolate > ")
        ts.ret
        alignDailySeries(ts.ret, method = "interp", include.weekend = FALSE)
        alignDailySeries(ts.ret, method = "interp", include.weekend = TRUE)

     ## applySeries -   
        xmpBasics("\nNext: Aggregate weekly > ")
        GoodFriday(2001)
        to = timeSequence(from = "2001-04-11", length.out = 3, 
          by = "weeks", format = "%Y-%m-%d", FinCenter = "GMT") 
        from = to - 6*24*3600
        data.frame(from, to)
        applySeries(ts.ret, from, to, FUN = sum)

