TimeSeriesData           package:fCalendar           R Documentation

_t_i_m_e_S_e_r_i_e_s _C_l_a_s_s, _F_u_n_c_t_i_o_n_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.           

     Functions and methods to modify 'timeSeries' objects:         

       'diff'    Takes differences from a 'timeSeries' object,
       'lag'     Lags a 'timeSeries' object,
       'merge'   Merges two 'timeSeries' objects,
       'rbinds'  Binds rows of two 'timeSeries' objects,
       'cumsum'  Returns the cumulated sum of a 'timeSeries' object,
       'lag'     Scales and centers a 'timeSeries' object.

     Functions and methods for classifying 'timeSeries' objects:

       'var'  Computes Variance from a 'timeSeries' object.

     Functions and methods for mathematical operations on 'timeSeries'
     objects:         

       'Ops.timeSeries'       S3: Arith method for a 'timeSeries' object,
       'abs'                  Returns absolute values of a 'timeSeries' object,
       'sqrt'                 Returns square root of a 'timeSeries' object,
       'exp'                  Returns the exponential values of a 'timeSeries' object,
       'log'                  Returns the logarithm of  a 'timeSeries' object,
       'sign'                 returns the signs of a 'timeSeries' object,
       'quantile.timeSeries'  Computes quantiles of a 'timeSeries' object.

     Functions and methods for subsetting 'timeSeries' objects: 

       '"["'       "[" method for a 'timeSeries' object,
       'cut'       Cuts a block from a 'timeSeries' object,
       'head'      Returns the head of a 'timeSeries' object,
       'tail'      Returns the tail of a 'timeSeries' object,
       'outliers'  Removes outliers from a 'timeSeries' object.

     Functions and methods for dimensional operations on 'timeSeries'
     objects: 

       'dim'         Returns the dimension of a 'timeSeries' object,
       'dimnames'    Returns the dimension names of a 'timeSeries' object,
       'colnames<-'  Assigns column names to a 'timeSeries' object,
       'rownames<-'  Assigns row names to a 'timeSeries' object,
       'is.array'    Allows that NCOL and NROW work properly.

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

     ## S3 method for class 'timeSeries':
     diff(x, lag = 1, diff = 1, trim = FALSE, pad = NA, ...)
     ## S3 method for class 'timeSeries':
     lag(x, k = 1, trim = FALSE, units = NULL, ...)
     ## S3 method for class 'timeSeries':
     merge(x, y, units = NULL, ...)
     ## S3 method for class 'timeSeries':
     rbind(x, y)
     ## S3 method for class 'timeSeries':
     cumsum(x)
     ## S3 method for class 'timeSeries':
     scale(x, center = TRUE, scale = TRUE)
     ## S3 method for class 'timeSeries':
     var(x, y = NULL, na.rm = FALSE, use)

     ## S3 method for class 'timeSeries':
     Ops(e1, e2)
     ## S3 method for class 'timeSeries':
     abs(x)
     ## S3 method for class 'timeSeries':
     sqrt(x)
     ## S3 method for class 'timeSeries':
     exp(x)
     ## S3 method for class 'timeSeries':
     log(x, base = exp(1))
     ## S3 method for class 'timeSeries':
     sign(x)
     ## S3 method for class 'timeSeries':
     quantile(x, probs = 0.95, ...)

     ## S3 method for class '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':
     cut(x, from, to, ...)
     ## S3 method for class 'timeSeries':
     head(x, n = 6, recordIDs = FALSE, ...)
     ## S3 method for class 'timeSeries':
     tail(x, n = 6, recordIDs = FALSE, ...)
     ## S3 method for class 'timeSeries':
     outlier(x, sd = 10, complement = TRUE, ...)

     ## S3 method for class 'timeSeries':
     dim(x)
     ## S3 method for class 'timeSeries':
     dimnames(x)
     colnames<-.timeSeries(x) <- value
     rownames<-.timeSeries(x) <- value
     ## S3 method for class 'timeSeries':
     is.array(x)

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

    base: [log] - 
           a positive number. The base with respect to which logarithms
          are computed. Defaults to 'e=exp(1)'. 

center, scale: [scale] - 
           either a logical value or a numeric vector of length equal
          to the number of columns of 'x'. 

complement: [outlierSeries] - 
           a logical flag, should the outler series or its complement
          be returns, by default 'TRUE' which returns the series free
          of outliers. 

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

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

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

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

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

       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. 

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

       n: [head][tail] - 
           an integer specifying the number of lines to be returned. 
          By default 'n=6'. 

   na.rm: [var] - 
           a logical flag. Should missing values be removed? By default
          'FALSE'. 

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

   probs: a numeric value or numeric vector of probabilities with
          values  in '[0,1]'. 

recordIDs: [head][tail] - 
           a logical value. Should the 'recordIDs' returned together
          with the data matrix and time series positions? 

      sd: [outlierSeries] - 
           a numeric value of standard deviations, e.g. 10 means that
          values larger or smaller tahn ten  times the standard
          deviation will be removed from the series. 

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

   units: [applySeries][lag][alignDailySeries][returnSeries][mergeSerie
          s] - 
           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. 
           [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. 

     use: [var] - 
           an optional character string giving a method for computing
          covariances in the presence of missing values. This must  be
          (an abbreviation of) one of the strings '"all.obs"',
          '"complete.obs"' or '"pairwise.complete.obs"'. 

   value: [colnames<-][rownames<-] - 
           a valid value for column names component of 'dimnames(x)'. 
          For a '"timeSeries"' object this is either 'NULL' or a 
          character vector of length the column dimension. Not, row
          names cannot be assigne for a '"timeSeries"' object, the
          function 'rownames()' will stop and return an error message. 

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

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

     ...: 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'
      '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'
      'lines'
      'points'
      '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.

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

     Diethelm Wuertz for the Rmetrics R-port.

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

     ## SOURCE("fCalendar.4B-TimeSeriesData")

     ## data - 
        # Create an artificial timeSeries object:
        myFinCenter <<- "GMT"
        charvec = timeCalendar()
        set.seed(4711)
        data = matrix(exp(cumsum(rnorm(12, sd = 0.1))))
        TS = timeSeries(data, charvec, units = "TS")
        TS
        par(ask = FALSE)
        plot(TS, type = "o", pch = 19)

     ## diff | scale - 
        # Difference and scale the timeSeries Object:
        scale(diff(TS, lag = 2, trim = TRUE))

     ## lag -
        # Lag the timeSeries Object:
        lag(TS, k = -1:1)
         
     ## merge -    
        # Merge two timeSeries Object:
        merge(TS, diff(log(TS), units = c("ts", "diffLog")))

     ## var -    
        # Variance of a timeSeries Object:
        var(returnSeries(TS, percentage = TRUE))
        
     ## Ops | +/- * ^ ...
        # Mathematical Operations:
        TS^2
        TS[2:4]
        OR = returnSeries(TS)
        OR
        OR > 0
        quantile(OR, probs = c(0.90, 0.95))

