period.apply: Apply Function Over Specified Interval

In joshuaulrich/xts: eXtensible Time Series

Apply Function Over Specified Interval

Description

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.

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().

Value

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

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(s)

Jeffrey A. Ryan, Joshua M. Ulrich

See Also

endpoints() apply.monthly()

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))
period.apply(zoo.data, INDEX=ep, FUN=colMeans)                  #same

period.apply(letters,c(0,5,7,26), paste0)

joshuaulrich/xts documentation built on Nov. 17, 2024, 6:37 a.m.