summary-index: Specialized sliding functions relative to an index

Description

These functions are specialized variants of the most common ways that slide_index() is generally used. Notably, slide_index_sum() can be used for rolling sums relative to an index (like a Date column), and slide_index_mean() can be used for rolling averages.

These specialized variants are much faster and more memory efficient than using an otherwise equivalent call constructed with slide_index_dbl() or slide_index_lgl(), especially with a very wide window.

Usage

slide_index_sum(
  x,
  i,
  ...,
  before = 0L,
  after = 0L,
  complete = FALSE,
  na_rm = FALSE
)
slide_index_prod(
  x,
  i,
  ...,
  before = 0L,
  after = 0L,
  complete = FALSE,
  na_rm = FALSE
)
slide_index_mean(
  x,
  i,
  ...,
  before = 0L,
  after = 0L,
  complete = FALSE,
  na_rm = FALSE
)
slide_index_min(
  x,
  i,
  ...,
  before = 0L,
  after = 0L,
  complete = FALSE,
  na_rm = FALSE
)
slide_index_max(
  x,
  i,
  ...,
  before = 0L,
  after = 0L,
  complete = FALSE,
  na_rm = FALSE
)
slide_index_all(
  x,
  i,
  ...,
  before = 0L,
  after = 0L,
  complete = FALSE,
  na_rm = FALSE
)
slide_index_any(
  x,
  i,
  ...,
  before = 0L,
  after = 0L,
  complete = FALSE,
  na_rm = FALSE
)

Value

A vector the same size as x containing the result of applying the summary function over the sliding windows.

For sliding sum, mean, prod, min, and max, a double vector will be returned.
For sliding any and all, a logical vector will be returned.

Arguments

x

[vector]

A vector to compute the sliding function on.

For sliding sum, mean, prod, min, and max, x will be cast to a double vector with vctrs::vec_cast().
For sliding any and all, x will be cast to a logical vector with vctrs::vec_cast().

i

[vector]

The index vector that determines the window sizes. It is fairly common to supply a date vector as the index, but not required.

There are 3 restrictions on the index:

The size of the index must match the size of .x, they will not be recycled to their common size.
The index must be an increasing vector, but duplicate values are allowed.
The index cannot have missing values.

...

These dots are for future extensions and must be empty.

before, after

[vector(1) / function / Inf]

If a vector of size 1, these represent the number of values before or after the current element of .i to include in the sliding window. Negative values are allowed, which allows you to "look forward" from the current element if used as the .before value, or "look backwards" if used as .after. Boundaries are computed from these elements as .i - .before and .i + .after. Any object that can be added or subtracted from .i with + and - can be used. For example, a lubridate period, such as lubridate::weeks().
If Inf, this selects all elements before or after the current element.
If a function, or a one-sided formula which can be coerced to a function, it is applied to .i to compute the boundaries. Note that this function will only be applied to the unique values of .i, so it should not rely on the original length of .i in any way. This is useful for applying a complex arithmetic operation that can't be expressed with a single - or + operation. One example would be to use lubridate::add_with_rollback() to avoid invalid dates at the end of the month.

The ranges that result from applying .before and .after have the same 3 restrictions as .i itself.

complete

[logical(1)]

Should the function be evaluated on complete windows only? If FALSE, the default, then partial computations will be allowed.

na_rm

[logical(1)]

Should missing values be removed from the computation?

Details

For more details about the implementation, see the help page of slide_sum().

Examples

Run this code

x <- c(1, 5, 3, 2, 6, 10)
i <- as.Date("2019-01-01") + c(0, 1, 3, 4, 6, 8)

# `slide_index_sum()` can be used for rolling sums relative to an index,
# allowing you to "respect gaps" in your series. Notice that the rolling
# sum in row 3 is only computed from `2019-01-04` and `2019-01-02` since
# `2019-01-01` is more than two days before the current date.
data.frame(
  i = i,
  x = x,
  roll = slide_index_sum(x, i, before = 2)
)

# `slide_index_mean()` can be used for rolling averages
slide_index_mean(x, i, before = 2)

# Only evaluate the sum on windows that have the potential to be complete
slide_index_sum(x, i, before = 2, after = 1, complete = TRUE)