Apply Function Over Specified Interval

Apply a specified function to data over intervals specified by INDEX. The intervals are defined as the observations from INDEX[k]+1 to INDEX[k+1], for k = 1:(length(INDEX)-1).

Usage

period.apply(x, INDEX, FUN, ...)

Arguments

x: The data that FUN will be applied to.
INDEX: A numeric vector of index breakpoint locations. The vector should begin with 0 and end with nrow(x).
FUN: A function to apply to each interval in x.
...: Additional arguments for FUN.

Value

An object with length(INDEX) - 1 observations, assuming INDEX starts with 0 and ends with nrow(x).

Details

Similar to the rest of the apply family, period.apply() calculates the specified function's value over a subset of data. The primary difference is that period.apply() applies the function to non-overlapping intervals of a vector or matrix.

Useful for applying functions over an entire data object by any non-overlapping intervals. For example, when INDEX is the result of a call to endpoints().

period.apply() checks that INDEX is sorted, unique, starts with 0, and ends with nrow(x). All those conditions are true of vectors returned by endpoints().

Note

When FUN = mean the results will contain one column for every column in the input, which is different from other math functions (e.g. median, sum, prod, sd, etc.).

FUN = mean works by column because the default method stats::mean previously worked by column for matrices and data.frames. R Core changed the behavior of mean to always return one column in order to be consistent with the other math functions. This broke some xts dependencies and mean.xts() was created to maintain the original behavior.

Using FUN = mean will print a message that describes this inconsistency. To avoid the message and confusion, use FUN = colMeans to calculate means by column and use FUN = function(x) mean to calculate one mean for all the data. Set options(xts.message.period.apply.mean = FALSE) to suppress this message.

Author

Jeffrey A. Ryan, Joshua M. Ulrich

Examples


zoo.data <- zoo(rnorm(31)+10,as.Date(13514:13744,origin="1970-01-01"))
ep <- endpoints(zoo.data,'weeks')
period.apply(zoo.data, INDEX=ep, FUN=function(x) colMeans(x))
#> 2007-01-07 2007-01-14 2007-01-21 2007-01-28 2007-02-04 2007-02-11 2007-02-18 
#>  10.077217   9.625527   9.578141  10.889268  10.018871   9.838435   9.730714 
#> 2007-02-25 2007-03-04 2007-03-11 2007-03-18 2007-03-25 2007-04-01 2007-04-08 
#>  10.367280  10.097980  10.205988   9.465840   9.717571  10.756848  10.081585 
#> 2007-04-15 2007-04-22 2007-04-29 2007-05-06 2007-05-13 2007-05-20 2007-05-27 
#>   9.777537   9.549109  10.787931  10.196389   9.793251   9.655943  10.000478 
#> 2007-06-03 2007-06-10 2007-06-17 2007-06-24 2007-07-01 2007-07-08 2007-07-15 
#>  10.569082   9.914698   9.563634   9.832579  10.760738  10.122047   9.910151 
#> 2007-07-22 2007-07-29 2007-08-05 2007-08-12 2007-08-19 
#>   9.691695  10.274592  10.306757  10.077217   9.625527 
period.apply(zoo.data, INDEX=ep, FUN=colMeans)                  #same
#> 2007-01-07 2007-01-14 2007-01-21 2007-01-28 2007-02-04 2007-02-11 2007-02-18 
#>  10.077217   9.625527   9.578141  10.889268  10.018871   9.838435   9.730714 
#> 2007-02-25 2007-03-04 2007-03-11 2007-03-18 2007-03-25 2007-04-01 2007-04-08 
#>  10.367280  10.097980  10.205988   9.465840   9.717571  10.756848  10.081585 
#> 2007-04-15 2007-04-22 2007-04-29 2007-05-06 2007-05-13 2007-05-20 2007-05-27 
#>   9.777537   9.549109  10.787931  10.196389   9.793251   9.655943  10.000478 
#> 2007-06-03 2007-06-10 2007-06-17 2007-06-24 2007-07-01 2007-07-08 2007-07-15 
#>  10.569082   9.914698   9.563634   9.832579  10.760738  10.122047   9.910151 
#> 2007-07-22 2007-07-29 2007-08-05 2007-08-12 2007-08-19 
#>   9.691695  10.274592  10.306757  10.077217   9.625527 

period.apply(letters,c(0,5,7,26), paste0)
#>      [,1]        
#> [1,] character,5 
#> [2,] character,2 
#> [3,] character,19