rollapply                package:zoo                R Documentation

_A_p_p_l_y _R_o_l_l_i_n_g _F_u_n_c_t_i_o_n_s

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

     A generic function for applying a function to rolling margins of
     an array.

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

     rollapply(data, width, FUN, ..., by = 1, ascending = TRUE, by.column = TRUE,
      na.pad = FALSE, align = c("center", "left", "right"))

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

    data: the data to be used (representing a series of observations).

   width: number of points per group.

     FUN: the function to be applied. In the case of functions like
          '+', '%*%', etc., the function name must be quoted.

     ...: optional arguments to 'FUN'.

      by: calculate FUN for trailing width points at every by-th time
          point.

ascending: logical. If TRUE then points are passed to 'FUN' in
          ascending order of time; otherwise, they are passed in
          descending order.

by.column: logical. If 'TRUE', 'FUN' is applied to each column
          separately.

  na.pad: logical. If 'TRUE'  then additional elements or rows of 'NA's
          are added so that  result has same number of elements or rows
          as 'data'.

   align: character specifying whether result should be left- or
          right-aligned or centered (default).

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

     Groups time points in successive sets of 'width' time points and 
     applies 'FUN' to the corresponding values.   If 'FUN' is 'mean',
     'max' or 'median' and 'by.column' is  'TRUE' and there are no
     extra arguments then special purpose code is used to enhance
     performance. See 'rollmean', 'rollmax' and 'rollmedian' for more
     details.

     Currently, there are methods for '"zoo"' and '"ts"' series.

     In previous versions, this function was called 'rapply'. It was
     renamed because from R 2.4.0 on, base R provides a different
     function 'rapply' for recursive (and not rolling) application of
     functions.

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

     A object of the same class as 'data' with the results of the
     rolling function.

_S_e_e _A_l_s_o:

     'rollmean'

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

     ## rolling mean
     z <- zoo(11:15, as.Date(31:35))
     rollapply(z, 2, mean)

     ## non-overlapping means
     z2 <- zoo(rnorm(6))
     rollapply(z2, 3, mean, by = 3)      # means of nonoverlapping groups of 3
     aggregate(z2, c(3,3,3,6,6,6), mean) # same

     ## optimized vs. customized versions
     rollapply(z2, 3, mean)   # uses rollmean which is optimized for mean
     rollmean(z2, 3)          # same
     rollapply(z2, 3, (mean)) # does not use rollmean

     ## rolling regression:
     ## set up multivariate zoo series with
     ## number of UK driver deaths and lags 1 and 12
     seat <- as.zoo(log(UKDriverDeaths))
     time(seat) <- as.yearmon(time(seat))
     seat <- merge(y = seat, y1 = lag(seat, k = -1),
       y12 = lag(seat, k = -12), all = FALSE)

     ## run a rolling regression with a 3-year time window
     ## (similar to a SARIMA(1,0,0)(1,0,0)_12 fitted by OLS)
     fm <- rollapply(seat, width = 36,
       FUN = function(z) coef(lm(y ~ y1 + y12, data = as.data.frame(z))),
       by.column = FALSE, align = "right")

     ## plot the changes in coefficients
     plot(fm)
     ## showing the shifts after the oil crisis in Oct 1973
     ## and after the seatbelt legislation change in Jan 1983

