R: Slide

slide {slider} | R Documentation

## Slide

### Description

`slide()` iterates through `.x` using a sliding window, applying `.f` to each sub-window of `.x`.

### Usage

    slide(.x, .f, ..., .before = 0L, .after = 0L, .step = 1L, .complete = FALSE)

    slide_vec(
      .x,
      .f,
      ...,
      .before = 0L,
      .after = 0L,
      .step = 1L,
      .complete = FALSE,
      .ptype = NULL
    )

    slide_dbl(
      .x,
      .f,
      ...,
      .before = 0L,
      .after = 0L,
      .step = 1L,
      .complete = FALSE
    )

    slide_int(
      .x,
      .f,
      ...,
      .before = 0L,
      .after = 0L,
      .step = 1L,
      .complete = FALSE
    )

    slide_lgl(
      .x,
      .f,
      ...,
      .before = 0L,
      .after = 0L,
      .step = 1L,
      .complete = FALSE
    )

    slide_chr(
      .x,
      .f,
      ...,
      .before = 0L,
      .after = 0L,
      .step = 1L,
      .complete = FALSE
    )

    slide_dfr(
      .x,
      .f,
      ...,
      .before = 0L,
      .after = 0L,
      .step = 1L,
      .complete = FALSE,
      .names_to = NULL,
      .name_repair = c("unique", "universal", "check_unique")
    )

    slide_dfc(
      .x,
      .f,
      ...,
      .before = 0L,
      .after = 0L,
      .step = 1L,
      .complete = FALSE,
      .size = NULL,
      .name_repair = c("unique", "universal", "check_unique", "minimal")
    )

### Arguments

`.x` | `[vector]` The vector to iterate over and apply `.f` to.
`.f` | `[function / formula]` If a function, it is used as is. If a formula, e.g. `~ .x + 2`, it is converted to a function. There are three ways to refer to the arguments: For a single argument function, use `.` For a two argument function, use `.x` and `.y` For more arguments, use `..1`, `..2`, `..3` etc This syntax allows you to create very compact anonymous functions.
`...` | Additional arguments passed on to the mapped function.
`.before, .after` | `[integer(1) / Inf]` The number of values before or after the current element to include in the sliding window. Set to `Inf` to select all elements before or after the current element. 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`.
`.step` | `[positive integer(1)]` The number of elements to shift the window forward between function calls.
`.complete` | `[logical(1)]` Should `.f` be evaluated on complete windows only? If `FALSE`, the default, then partial computations will be allowed.
`.ptype` | `[vector(0) / NULL]` A prototype corresponding to the type of the output. If `NULL`, the default, the output type is determined by computing the common type across the results of the calls to `.f`. If supplied, the result of each call to `.f` will be cast to that type, and the final output will have that type. If `getOption("vctrs.no_guessing")` is `TRUE`, the `.ptype` must be supplied. This is a way to make production code demand fixed types.
`.names_to` | Optionally, the name of a column where the names of `...` arguments are copied. These names are useful to identify which row comes from which input. If supplied and `...` is not named, an integer column is used to identify the rows.
`.name_repair` | One of `"unique"`, `"universal"`, or `"check_unique"`. See `vec_as_names()` for the meaning of these options. With `vec_rbind()`, the repair function is applied to all inputs separately. This is because `vec_rbind()` needs to align their columns before binding the rows, and thus needs all inputs to have unique names. On the other hand, `vec_cbind()` applies the repair function after all inputs have been concatenated together in a final data frame. Hence `vec_cbind()` allows the more permissive minimal names repair.
`.size` | If, `NULL`, the default, will determine the number of rows in `vec_cbind()` output by using the standard recycling rules. Alternatively, specify the desired number of rows, and any inputs of length 1 will be recycled appropriately.

### Details

Unlike `lapply()` or `purrr::map()`, which construct calls like

    .f(.x[[i]], ...)

the equivalent with `slide()` looks like

    .f(vctrs::vec_slice(.x, i), ...)

which is approximately

    .f(.x[i], ...)

except in the case of data frames or arrays, which are iterated over row-wise.

If `.x` has names, then the output will preserve those names.

Using `vctrs::vec_cast()`, the output of `.f` will be automatically cast to the type required by the variant of `slide_*()` being used.

### Value

A vector fulfilling the following invariants:

#### `slide()`

- `vec_size(slide(.x)) == vec_size(.x)`

- `vec_ptype(slide(.x)) == list()`

#### `slide_vec()` and `slide_*()` variants

- `vec_size(slide_vec(.x)) == vec_size(.x)`

- `vec_size(slide_vec(.x)[[1]]) == 1L`

- `vec_ptype(slide_vec(.x, .ptype = ptype)) == ptype`

### See Also

`slide2()`, `slide_index()`, `hop()`

### Examples

    # The defaults work similarly to `map()`
    slide(1:5, ~.x)

    # Use `.before`, `.after`, and `.step` to control the window
    slide(1:5, ~.x, .before = 1)

    # This can be used for rolling means
    slide_dbl(rnorm(5), mean, .before = 2)

    # Or more flexible rolling operations
    slide(rnorm(5), ~ .x - mean(.x), .before = 2)

    # `.after` allows you to "align to the left" rather than the right
    slide(1:5, ~.x, .after = 2)

    # And a mixture of `.before` and `.after`
    # allows you complete control over the exact alignment.
    # Below, "center alignment" is used.
    slide(1:5, ~.x, .before = 1, .after = 1)

    # The `.step` controls how the window is shifted along `.x`,
    # allowing you to "skip" iterations if you only need a less granular result
    slide(1:10, ~.x, .before = 2, .step = 3)

    # `.complete` controls whether or not partial results are computed.
    # By default, they are, but setting `.complete = TRUE` restricts
    # `slide()` to only evaluate the function where a complete window exists.
    slide(1:5, ~.x, .before = 2, .after = 1)
    slide(1:5, ~.x, .before = 2, .after = 1, .complete = TRUE)

    # ---------------------------------------------------------------------------
    # Data frames

    # Data frames are iterated over rowwise
    mtcars_rowwise <- slide(mtcars, ~.x)
    mtcars_rowwise[1:3]

    # This means that any column name is easily accessible
    slide_dbl(mtcars, ~.x$mpg + .x$cyl)

    # More advanced rowwise iteration is available as well by using the
    # other arguments
    mtcars_rowwise_window <- slide(mtcars, ~.x, .before = 1, .after = 1)
    mtcars_rowwise_window[1:3]

    # ---------------------------------------------------------------------------
    # Cumulative sliding

    # Using the special cased value, `Inf`, you can ask `slide()` to pin the
    # start of the sliding window to the first element, effectively creating
    # a cumulative window
    slide(1:5, ~.x, .before = Inf)

    # Same with `.after`, this creates a window where you start with all of the
    # elements, but decrease the total number over each iteration
    slide(1:5, ~.x, .after = Inf)

    # ---------------------------------------------------------------------------
    # Negative `.before` / `.after`

    # `.before` is allowed to be negative, allowing you to "look forward" in
    # your vector. Note that `abs(.before) <= .after` must hold if `.before` is
    # negative. In this example, we look forward to elements in locations 2 and 3
    # but place the result in position 1 in the output.
    slide(1:5, ~.x, .before = -1, .after = 2)

    # `.after` can be negative as well to "look backwards"
    slide(1:5, ~.x, .before = 2, .after = -1)

    # ---------------------------------------------------------------------------
    # Removing padding

    # If you are looking for a way to remove the `NA` values from something like
    # this, then it doesn't exist as a built in option.
    x <- rnorm(10)
    slide_dbl(x, mean, .before = 3, .step = 2, .complete = TRUE)

    # Adding an option to `slide_dbl()` to remove the `NA` values would destroy
    # its size stability. Instead, you can use a combination of `slide_dfr()`
    # to get the start/stop indices with `hop_index_vec()`.
    i <- seq_along(x)
    idx <- slide_dfr(
      i,
      ~data.frame(start = .x[1], stop = .x[length(.x)]),
      .before = 3,
      .step = 2,
      .complete = TRUE
    )

    idx

    hop_index_vec(x, i, idx$start, idx$stop, mean, .ptype = double())

[Package slider version 0.1.2 Index]