`lag`

Shifts the data of a timetable down by a number of rows, keeping the times.

Category: Language Fundamentals > Data Types

Syntax

TT2 = lag(TT)

Shifts the data by one row; the first row becomes missing.

TT2 = lag(TT, k)

Shifts by k rows. A negative k shifts upward (a lead).

Description

After lag(TT), the value on row n is the value that TT had on row n - 1. That lines up each observation with the previous one, which is convenient for computing differences or testing a variable against its own past. The row times are not touched, only the data move.

Input arguments

TT: A timetable.
k: Integer number of rows, or a duration for a regular timetable. The default is 1.

Output arguments

TT2: A timetable with the same row times. The rows that have no source value are filled with the missing value of each variable, such as NaN.

Example

Previous value and next value

tt = timetable(seconds([0;1;2]), [10;20;30], 'VariableNames', {'v'});
lag(tt)
lag(tt, -1)

Output

ans = 3×1 timetable

    Time      v 
    _____    ___

    0 sec    NaN
    1 sec     10
    2 sec     20
ans = 3×1 timetable

    Time      v 
    _____    ___

    0 sec     20
    1 sec     30
    2 sec    NaN

lag