TimeSeriesClass          package:fCalendar          R Documentation

_t_i_m_e_S_e_r_i_e_s _C_l_a_s_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.           

     Functions to generate and modify 'timeSeries' objects:         

       'timeSeries'       Creates a 'timeSeries' object from scratch,
       'readSeries'       Reads a 'timeSeries' from a spreadsheet file,
       'returnSeries'     Computes returns from a 'timeSeries' object,
       'durationSeries'   Computes durations from a 'timeSeries' object,
       'midquoteSeries'   Computes mid quotes from a 'timeSeries' object,
       'spreadSeries'     Computes spreads from a 'timeSeries' object,
       'applySeries'      Applies a function to margins of a 'timeSeries',
       'orderStatistics'  Computes order statistic of a 'timeSeries'.

     Data Slot and classification of 'timeSeries' objects: 

       'seriesData'      Extracts data slot from a 'timeSeries',
       'isUnivariate'    Tests if a 'timeSeries' object is univariate,
       'isMultivariate'  Tests if a 'timeSeries' object is multivariate.

     Functions to print and plot 'timeSeries' objects:      

       'print.timeSeries'    S3: Print method for a 'timeSeries' object,
       'summary.timeSeries'  S3: Summary method for a 'timeSeries' object,
       'plot.timeSeries'     S3: Plot method for a 'timeSeries' object,
       'lines.timeSeries'    S3: Lines method for a 'timeSeries' object,
       'points.timeSeries'   S3: Points method for a 'timeSeries' object.

     Special Functions for daily 'timeSeries' objects:  

       'dummyDailySeries'  Creates a dummy daily 'timeSeries' object,
       'alignDailySeries'  Aligns a daily 'timeSeries' to new positions,
       'ohlcDailyPlot'     Plots open high low close bar chart.

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

     timeSeries(data, charvec, units = NULL, format = NULL, zone = myFinCenter, 
         FinCenter = myFinCenter, recordIDs = data.frame(), title = NULL, 
         documentation = NULL, ...)   
     readSeries(file, header = TRUE, sep = ";", zone = myFinCenter, 
         FinCenter = myFinCenter, title = NULL, documentation = NULL, ...)
     returnSeries(x, type = c("continuous", "discrete"), percentage = FALSE, 
         trim = TRUE, digits = 4, units = NULL)  
     durationSeries(x, trim = FALSE, units = c("secs", "mins", "hours"))   
     midquoteSeries(x, which = c("Bid", "Ask"))
     spreadSeries(x, which = c("Bid", "Ask"), tickSize = NULL)
      
     applySeries(x, from = NULL, to = NULL, by = c("monthly", "quarterly"), 
         FUN = colAvgs, units = NULL, format = x@format, zone = x@FinCenter, 
         FinCenter = x@FinCenter, recordIDs = data.frame(), title = x@title,
         documentation = x@documentation, ...)
         
     orderStatistics(x)

     seriesData(object)
     isUnivariate(x)
     isMultivariate(x)

     ## S3 method for class 'timeSeries':
     print(x, recordIDs = FALSE, ...)
     ## S3 method for class 'timeSeries':
     summary(object, ...)
     ## S3 method for class 'timeSeries':
     plot(x, ...) 
     ## S3 method for class 'timeSeries':
     lines(x, ...)
     ## S3 method for class 'timeSeries':
     points(x, ...)

     dummyDailySeries(x = rnorm(365), units = "X", zone = myFinCenter, 
         FinCenter = myFinCenter)
     alignDailySeries(x, method = c("before", "after", "interp", "fillNA"), 
         include.weekends = FALSE, units = NULL, zone = myFinCenter, 
         FinCenter = myFinCenter)
     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:

      by: [applySeries] - 
           a character either '"monthly"' or '"quarterly"'. The default
          value is '"monthly"'. Only operative when both arguments
          'from' and 'to' have ther default values 'NULL'. In this case
          the function 'FUN' will be applied to monthly or quarterly
          periods. 

 charvec: a character vector of dates and times. 

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. 

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

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

    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".  

  header: a logical value indicating whether the file contains the
          names of the variables as its first line.  If missing, the
          value is determined from the file format: 'header' is set to
          'TRUE' if and only if the first row contains one fewer field
          than the number of columns. 

  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. 

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

tickSize: [spreadSeries] - 
           the default is NULL to simply compute price changes in
          original  price levels. If ticksize is supplied, the price
          changes will be  divided by the value of 'inTicksOfSize' to
          compute price changes in ticks. 

    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"'.  

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

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

recordIDs: a data frame which can be used for record identification
          information. 
           [print] - 
           a logical value. Should the 'recordIDs' printed together
          with the data matrix and time series positions? 

     sep: [readSeries] - 
           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: [applySeries][lag][allignDailySeries][returnSeries][mergeSeri
          es] - 
           an optional 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. 
           [durationSeries] - 
           a character value or vector which allows to set the  units
          in which the durations are measured. By default durations are
          measured in seconds.  
           [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'. 

   which: [midquoteSeries][spreadSeries] - 
           a vector with two character strings naming the column names
          of the time series from which to compute the mid quotes and
          spreads. By default these are bid and ask prices with column
          names 'c("Bid", "Ask")'. 

       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. 

    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 differences. 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'
      'readSeries'
      'returnSeries'
      'applySeries' 
      return a S4 object of class 'timeSeries'. 

     'orderStatistics' 
      returns ... 

     'seriesData'

      extracts the '@Data' slot from a 'timeSeries' object.  Thus,
     'seriesData' returns an object of class 'matrix'. 

     'isUnivariate'
      'isMultivariate'

      returns ... 

     'plot'
      'lines'
      'points'
      'print' 
      plot and print methods for an object of class 'timeSeries'. 

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

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

     Diethelm Wuertz for the Rmetrics R-port.

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

     ## SOURCE("fCalendar.4A-TimeSeriesClass")

     ## data - Data Frame:
        # Microsoft Data:
        MSFT.df = data.frame(matrix(c(
        20010326, 57.1250, 57.5000, 55.5625, 56.0625,  31559300,
        20010327, 56.0625, 58.5625, 55.8750, 58.2500,  47567800,
        20010328, 57.3750, 57.9375, 55.3750, 55.5625,  39340800,
        20010329, 55.3750, 57.1875, 54.5625, 55.3750,  43492500,
        20010330, 55.7500, 56.1875, 53.8750, 54.6875,  45600800,
        20010402, 54.8125, 56.9375, 54.6250, 55.8125,  37962000,
        20010403, 55.3125, 55.3125, 52.7500, 53.3750,  47093800,
        20010404, 53.3750, 55.0000, 51.0625, 51.9375,  52023300,
        20010405, 53.7500, 57.3750, 53.5000, 56.7500,  56682000,
        20010406, 56.3750, 57.1875, 55.0625, 56.1875,  46311000,
        20010409, 56.5700, 57.4200, 55.6600, 57.1500,  28147800,
        20010410, 57.9500, 60.0900, 57.7800, 59.6800,  54599700,
        20010411, 60.6500, 61.5000, 59.7000, 60.0400,  54939800,
        20010412, 59.5600, 62.3100, 59.3500, 62.1800,  43760000,
        20010416, 61.4000, 61.5800, 60.1200, 60.7900,  32928700,
        20010417, 60.5200, 62.1100, 60.0400, 61.4800,  42574600,
        20010418, 63.3900, 66.3100, 63.0000, 65.4300,  78348200,
        20010419, 65.8100, 69.0000, 65.7500, 68.0400,  79687800,
        20010420, 70.3000, 71.1000, 68.5000, 69.0000,  96459800,
        20010423, 68.1100, 68.4700, 66.9000, 68.2500,  46085600,
        20010424, 68.2000, 69.9300, 67.1400, 67.5500,  44588300,
        20010425, 67.5700, 69.7900, 67.2500, 69.6900,  38372000,
        20010426, 70.0700, 71.0000, 68.2500, 69.1300,  59368800,
        20010427, 69.5300, 69.6800, 66.2100, 67.1200,  60786200,
        20010430, 68.5300, 69.0600, 67.6800, 67.7500,  37184100,
        20010501, 67.6600, 70.3000, 67.6000, 70.1700,  41851400,
        20010502, 71.0000, 71.1500, 69.3500, 69.7600,  46432200,
        20010503, 69.2500, 70.1800, 68.1400, 68.5300,  33136700,
        20010504, 68.0000, 71.0500, 67.9600, 70.7500,  59769200,
        20010507, 70.8300, 72.1500, 70.7000, 71.3800,  54678100), 
        byrow = TRUE, ncol = 6))
        colnames(MSFT.df) = c("YYMMDD", "Open", "High", "Low", "Close", "Volume")

        # Load Microsoft Data:
        myFinCenter <<- "GMT"
        MSFT = as.timeSeries(MSFT.df)
        head(MSFT)

     ## timeSeries - Conversion:
        # Create a timeSeries Objec - The Direct Way ...
        Close = MSFT[, 5]
        head(Close)
        # From Scratch ...
        data = as.matrix(MSFT[, 4])
        charvec = rownames(MSFT)
        Close = timeSeries(data, charvec, units = "Close")
        head(Close)
        c(start(Close), end(Close))
         
     ## Cut Series -    
        # Cut out April Data from 2001:
        tsApril01 = cut(Close, "2001-04-01", "2001-04-30") 
        tsApril01

     ## Return Series -  
        # Compute Returns:
        args(returnSeries)
        # Continuous Returns:
        returnSeries(tsApril01)
        # Discrete Returns:
        returnSeries(tsApril01, type = "discrete")
        # Don't trim:
        returnSeries(tsApril01, trim = FALSE)
        # Use Percentage Values:
        returnSeries(tsApril01, percentage = TRUE, trim = FALSE)
         
     ## Align Daily Series -     
        # Align with NA:
        args(alignDailySeries)
        tsRet = returnSeries(tsApril01, trim = TRUE)
        GoodFriday(2001)   
        EasterMonday(2001) 
        alignDailySeries(tsRet, method = "fillNA", include.weekends = FALSE)
        alignDailySeries(tsRet, method = "fillNA", include.weekends = TRUE)
         
     ## alignDailySeries - 
        # Interpolate:
        tsRet
        alignDailySeries(tsRet, method = "interp", include.weekend = FALSE)
        alignDailySeries(tsRet, method = "interp", include.weekend = TRUE)

     ## applySeries -   
        # Aggregate weekly:
        GoodFriday(2001)
        to = timeSequence(from = "2001-04-11", length.out = 3, by = "week") 
        from = to - 6*24*3600
        from
        to
        applySeries(tsRet, from, to, FUN = sum)

