# roll_lag: Fast rolling grouped lags and differences In timeplyr: Fast Tidy Tools for Date and Date-Time Manipulation

 roll_lag R Documentation

## Fast rolling grouped lags and differences

### Description

Inspired by 'collapse', `roll_lag` and `roll_diff` operate similarly to `flag` and `fdiff`.

### Usage

``````roll_lag(x, n = 1L, ...)

## Default S3 method:
roll_lag(x, n = 1L, g = NULL, fill = NULL, ...)

roll_diff(x, n = 1L, ...)

## Default S3 method:
roll_diff(x, n = 1L, g = NULL, fill = NULL, differences = 1L, ...)

diff_(
x,
n = 1L,
differences = 1L,
order = NULL,
run_lengths = NULL,
fill = NULL
)
``````

### Arguments

 `x` A vector or data frame. `n` Lag. This will be recycled to match the length of x and can be negative. `...` Arguments passed onto appropriate method. `g` Grouping vector. This can be a vector, data frame or `GRP` object. `fill` Value to fill the first `n` elements. `differences` Number indicating the number of times to recursively apply the differencing algorithm. If `length(n) == 1`, i.e the lag is a scalar integer, an optimised method is used which avoids recursion entirely. If `length(n) != 1` then simply recursion is used. `order` Optionally specify an ordering with which to apply the lags/differences. This is useful for example when applying lags chronologically using an unsorted time variable. `run_lengths` Optional integer vector of run lengths that defines the size of each lag run. For example, supplying `c(5, 5)` applies lags to the first 5 elements and then essentially resets the bounds and applies lags to the next 5 elements as if they were an entirely separate and standalone vector. This is particularly useful in conjunction with the order argument to perform a by-group lag.

### Details

While these may not be as fast the 'collapse' equivalents, they are adequately fast and efficient.
A key difference between `roll_lag` and `flag` is that `g` does not need to be sorted for the result to be correct.
Furthermore, a vector of lags can be supplied for a custom rolling lag. For time-based lags, see time_lag.

`roll_diff()` silently returns `NA` when there is integer overflow. Both `roll_lag()` and `roll_diff()` apply recursively to list elements.

### Value

A vector the same length as `x`.

### Examples

``````library(timeplyr)

x <- 1:10

roll_lag(x) # Lag
roll_diff(x) # Lag diff

# Using cheapr::lag_sequence()
# Differences lagged at 5, first 5 differences are compared to x[1]
roll_diff(x, cheapr::lag_sequence(length(x), 5, partial = TRUE))

# Like diff() but x/y instead of x-y
quotient <- function(x, n = 1L){
x / roll_lag(x, n)
}
# People often call this a growth rate
# but it's just a percentage difference
# See ?roll_growth_rate for growth rate calculations
quotient(1:10)

``````

timeplyr documentation built on June 22, 2024, 10:01 a.m.