Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

## shift

Fast lead/lag for vectors and lists

### Description

`lead` or `lag` vectors, lists, data.frames or data.tables implemented in C for speed.

`bit64::integer64` is also supported.

### Usage

`shift(x, n=1L, fill=NA, type=c("lag", "lead", "shift"), give.names=FALSE)`

### Arguments

 `x` A vector, list, data.frame or data.table. `n` integer vector denoting the offset by which to lead or lag the input. To create multiple lead/lag vectors, provide multiple values to `n`; negative values of `n` will "flip" the value of `type`, i.e., `n=-1` and `type='lead'` is the same as `n=1` and `type='lag'`. `fill` Value to use for padding when the window goes beyond the input length. `type` default is `"lag"` (look "backwards"). The other possible values `"lead"` (look "forwards") and `"shift"` (behave same as `"lag"` except given names). `give.names` default is `FALSE` which returns an unnamed list. When `TRUE`, names are automatically generated corresponding to `type` and `n`. If answer is an atomic vector, then the argument is ignored.

### Details

`shift` accepts vectors, lists, data.frames or data.tables. It always returns a list except when the input is a `vector` and `length(n) == 1` in which case a `vector` is returned, for convenience. This is so that it can be used conveniently within data.table's syntax. For example, `DT[, (cols) := shift(.SD, 1L), by=id]` would lag every column of `.SD` by 1 for each group and `DT[, newcol := colA + shift(colB)]` would assign the sum of two vectors to `newcol`.

Argument `n` allows multiple values. For example, `DT[, (cols) := shift(.SD, 1:2), by=id]` would lag every column of `.SD` by `1` and `2` for each group. If `.SD` contained four columns, the first two elements of the list would correspond to `lag=1` and `lag=2` for the first column of `.SD`, the next two for second column of `.SD` and so on. Please see examples for more.

`shift` is designed mainly for use in data.tables along with `:=` or `set`. Therefore, it returns an unnamed list by default as assigning names for each group over and over can be quite time consuming with many groups. It may be useful to set names automatically in other cases, which can be done by setting `give.names` to `TRUE`.

### Value

A list containing the lead/lag of input `x`.

`data.table`

### Examples

```# on vectors, returns a vector as long as length(n) == 1, #1127
x = 1:5
# lag with n=1 and pad with NA (returns vector)
shift(x, n=1, fill=NA, type="lag")
# lag with n=1 and 2, and pad with 0 (returns list)
shift(x, n=1:2, fill=0, type="lag")
# getting a window by using positive and negative n:
shift(x, n = -1:1)
shift(x, n = -1:1, type = "shift", give.names = TRUE)

# on data.tables
DT = data.table(year=2010:2014, v1=runif(5), v2=1:5, v3=letters[1:5])
# lag columns 'v1,v2,v3' DT by 1 and fill with 0
cols = c("v1","v2","v3")
anscols = paste("lead", cols, sep="_")
DT[, (anscols) := shift(.SD, 1, 0, "lead"), .SDcols=cols]

# return a new data.table instead of updating
# with names automatically set
DT = data.table(year=2010:2014, v1=runif(5), v2=1:5, v3=letters[1:5])
DT[, shift(.SD, 1:2, NA, "lead", TRUE), .SDcols=2:4]

# lag/lead in the right order
DT = data.table(year=2010:2014, v1=runif(5), v2=1:5, v3=letters[1:5])
DT = DT[sample(nrow(DT))]
# add lag=1 for columns 'v1,v2,v3' in increasing order of 'year'
cols = c("v1","v2","v3")
anscols = paste("lag", cols, sep="_")
DT[order(year), (cols) := shift(.SD, 1, type="lag"), .SDcols=cols]
DT[order(year)]

# while grouping
DT = data.table(year=rep(2010:2011, each=3), v1=1:6)
DT[, c("lag1", "lag2") := shift(.SD, 1:2), by=year]

# on lists
ll = list(1:3, letters[4:1], runif(2))
shift(ll, 1, type="lead", give.names=TRUE)

# fill using first or last by group
DT = data.table(x=1:6, g=rep(1:2, each=3))
DT[ , shift(x, fill=x[1L]), by=g]
DT[ , shift(x, fill=x[.N], type="lead"), by=g]```

###### data.table

Extension of `data.frame`

v1.14.0
MPL-2.0 | file LICENSE
Authors
Matt Dowle [aut, cre], Arun Srinivasan [aut], Jan Gorecki [ctb], Michael Chirico [ctb], Pasha Stetsenko [ctb], Tom Short [ctb], Steve Lianoglou [ctb], Eduard Antonyan [ctb], Markus Bonsch [ctb], Hugh Parsonage [ctb], Scott Ritchie [ctb], Kun Ren [ctb], Xianying Tan [ctb], Rick Saporta [ctb], Otto Seiskari [ctb], Xianghui Dong [ctb], Michel Lang [ctb], Watal Iwasaki [ctb], Seth Wenchel [ctb], Karl Broman [ctb], Tobias Schmidt [ctb], David Arenburg [ctb], Ethan Smith [ctb], Francois Cocquemas [ctb], Matthieu Gomez [ctb], Philippe Chataignon [ctb], Nello Blaser [ctb], Dmitry Selivanov [ctb], Andrey Riabushenko [ctb], Cheng Lee [ctb], Declan Groves [ctb], Daniel Possenriede [ctb], Felipe Parages [ctb], Denes Toth [ctb], Mus Yaramaz-David [ctb], Ayappan Perumal [ctb], James Sams [ctb], Martin Morgan [ctb], Michael Quinn [ctb], @javrucebo [ctb], @marc-outins [ctb], Roy Storey [ctb], Manish Saraswat [ctb], Morgan Jacob [ctb], Michael Schubmehl [ctb], Davis Vaughan [ctb], Toby Hocking [ctb], Leonardo Silvestri [ctb], Tyson Barrett [ctb], Jim Hester [ctb], Anthony Damico [ctb], Sebastian Freundt [ctb], David Simons [ctb], Elliott Sales de Andrade [ctb], Cole Miller [ctb], Jens Peder Meldgaard [ctb], Vaclav Tlapak [ctb], Kevin Ushey [ctb], Dirk Eddelbuettel [ctb], Ben Schwen [ctb]
Initial release

## We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.