polars.Series.shift

Series.shift(
    n: int = 1,
    *,
    fill_value: IntoExpr | None = None,
) → Series

Shift values by the given number of indices.

Parameters:

n

Number of indices to shift forward. If a negative value is passed, values are shifted in the opposite direction instead.

fill_value

Fill the resulting null values with this value. Accepts scalar expression input. Non-expression inputs are parsed as literals.

Notes

This method is similar to the LAG operation in SQL when the value for n is positive. With a negative value for n, it is similar to LEAD.

Examples

By default, values are shifted forward by one index.

>>> s = pl.Series([1, 2, 3, 4])
>>> s.shift()
shape: (4,)
Series: '' [i64]
[
    null
    1
    2
    3
]

Pass a negative value to shift in the opposite direction instead.

>>> s.shift(-2)
shape: (4,)
Series: '' [i64]
[
    3
    4
    null
    null
]

Specify fill_value to fill the resulting null values.

>>> s.shift(-2, fill_value=100)
shape: (4,)
Series: '' [i64]
[
    3
    4
    100
    100
]