`lead`

or `lag`

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

`bit64::integer64`

is also supported.

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

x

A vector, list, data.frame or data.table.

n

Non-negative integer vector denoting the offset to lead or lag the input by. To create multiple lead/lag vectors, provide multiple values to `n`

.

fill

Value to pad by.

type

default is `"lag"`

. The other possible value is `"lead"`

.

give.names

default is `FALSE`

which returns an unnamed list. When `TRUE`

, names are automatically generated corresponding to `type`

and `n`

.

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

.

`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`

.

# NOT RUN { # 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") # 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") shift(ll, 1, type="lead", give.names=TRUE) shift(ll, 1:2, type="lead") # }