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 
#>   9.590466  10.107768  10.077813   9.698109   9.731317   9.867458  10.374609 
#> 2007-02-25 2007-03-04 2007-03-11 2007-03-18 2007-03-25 2007-04-01 2007-04-08 
#>   9.639570   9.724078   9.942779  10.140559   9.709735  10.077217   9.431368 
#> 2007-04-15 2007-04-22 2007-04-29 2007-05-06 2007-05-13 2007-05-20 2007-05-27 
#>  10.115990  10.235857   9.662549   9.789400   9.595131  10.381935   9.601899 
#> 2007-06-03 2007-06-10 2007-06-17 2007-06-24 2007-07-01 2007-07-08 2007-07-15 
#>  10.205988   9.289243  10.408699   9.945288   9.712572   9.634762   9.689375 
#> 2007-07-22 2007-07-29 2007-08-05 2007-08-12 2007-08-19 
#>  10.499781   9.821003   9.793251   9.590466  10.107768 
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 
#>   9.590466  10.107768  10.077813   9.698109   9.731317   9.867458  10.374609 
#> 2007-02-25 2007-03-04 2007-03-11 2007-03-18 2007-03-25 2007-04-01 2007-04-08 
#>   9.639570   9.724078   9.942779  10.140559   9.709735  10.077217   9.431368 
#> 2007-04-15 2007-04-22 2007-04-29 2007-05-06 2007-05-13 2007-05-20 2007-05-27 
#>  10.115990  10.235857   9.662549   9.789400   9.595131  10.381935   9.601899 
#> 2007-06-03 2007-06-10 2007-06-17 2007-06-24 2007-07-01 2007-07-08 2007-07-15 
#>  10.205988   9.289243  10.408699   9.945288   9.712572   9.634762   9.689375 
#> 2007-07-22 2007-07-29 2007-08-05 2007-08-12 2007-08-19 
#>  10.499781   9.821003   9.793251   9.590466  10.107768 

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