shift: Shift a Vector (i.e., lag/lead)

Description

shift shifts elements of a vector right (n < 0) for lags or left (n > 0) for leads replacing the undefined data with a user-defined value (e.g., NA). The number of elements shifted is equal to abs(n). It is assumed that x is already sorted by time such that the first element is earliest in time and the last element is the latest in time.

Usage

shift(x, n, undefined = NA)

Value

an atomic vector of the same length as x that is shifted. If

x and undefined are different typeofs, then the return will be coerced to the more complex typeof (i.e., complex to simple: character, double, integer, logical).

Arguments

x: atomic vector or list vector.
n: integer vector with length 1. Specifies the direction and magnitude of the shift. See details.
undefined: atomic vector with length 1 (probably makes sense to be the same typeof as x). Specifies what to insert for undefined values after the shifting takes place. See details.

Details

If n is negative, then shift inserts undefined into the first abs(n) elements of x, shifting all other values of x to the right abs(n) positions, and then dropping the last abs(n) elements of x to preserve the original length of x. If n is positive, then shift drops the first abs(n) elements of x, shifting all other values of x left abs(n) positions, and then inserts undefined into the last abs(n) elements of x to preserve the original length of x. If n is zero, then shift simply returns x.

It is recommended to use L when specifying n to prevent problems with floating point numbers. shift tries to circumvent this issue by a call to round within shift if n is not an integer; however that is not a complete fail safe. The problem is that as.integer(n) implicit in shift truncates rather than rounds.

Examples

Run this code

shift(x = attitude[[1]], n = -1L) # use L to prevent problems with floating point numbers
shift(x = attitude[[1]], n = -2L) # can specify any integer up to the length of `x`
shift(x = attitude[[1]], n = +1L) # can specify negative or positive integers
shift(x = attitude[[1]], n = +2L, undefined = -999) # user-specified indefined value
shift(x = setNames(object = letters, nm = LETTERS), n = 3L) # names are kept