Compute lagged or leading values

Source: R/lead-lag.R

Find the "previous" (lag()) or "next" (lead()) values in a vector. Useful for comparing values behind of or ahead of the current values.

lag(x, n = 1L, default = NA, order_by = NULL, ...)

lead(x, n = 1L, default = NA, order_by = NULL, ...)

Arguments

x

Vector of values
n

Positive integer of length 1, giving the number of positions to lead or lag by
default

Value used for non-existent rows. Defaults to NA.
order_by

Override the default ordering to use another vector or column
...

Needed for compatibility with lag generic.

Examples

lag(1:5)

#> [1] NA  1  2  3  4
lead(1:5)

#> [1]  2  3  4  5 NA

x <- 1:5
tibble(behind = lag(x), x, ahead = lead(x))

#> # A tibble: 5 x 3
#>   behind     x ahead
#>    <int> <int> <int>
#> 1     NA     1     2
#> 2      1     2     3
#> 3      2     3     4
#> 4      3     4     5
#> 5      4     5    NA

# If you want to look more rows behind or ahead, use `n`
lag(1:5, n = 1)

#> [1] NA  1  2  3  4
lag(1:5, n = 2)

#> [1] NA NA  1  2  3

lead(1:5, n = 1)

#> [1]  2  3  4  5 NA
lead(1:5, n = 2)

#> [1]  3  4  5 NA NA

# If you want to define a value for non-existing rows, use `default`
lag(1:5)

#> [1] NA  1  2  3  4
lag(1:5, default = 0)

#> [1] 0 1 2 3 4

lead(1:5)

#> [1]  2  3  4  5 NA
lead(1:5, default = 6)

#> [1] 2 3 4 5 6

# If data are not already ordered, use `order_by`
scrambled <- slice_sample(tibble(year = 2000:2005, value = (0:5) ^ 2), prop = 1)

wrong <- mutate(scrambled, previous_year_value = lag(value))
arrange(wrong, year)

#> # A tibble: 6 x 3
#>    year value previous_year_value
#>   <int> <dbl>               <dbl>
#> 1  2000     0                   9
#> 2  2001     1                  16
#> 3  2002     4                   1
#> 4  2003     9                  25
#> 5  2004    16                   0
#> 6  2005    25                  NA

right <- mutate(scrambled, previous_year_value = lag(value, order_by = year))
arrange(right, year)

#> # A tibble: 6 x 3
#>    year value previous_year_value
#>   <int> <dbl>               <dbl>
#> 1  2000     0                  NA
#> 2  2001     1                   0
#> 3  2002     4                   1
#> 4  2003     9                   4
#> 5  2004    16                   9
#> 6  2005    25                  16