Main Content

lag

Time-shift data in timetable

Description

example

TT2 = lag(TT1) shifts the data in each variable in TT1 forward in time by one time step. A shift forward in time is a lag. The row times of TT1 must be regular.

The timetables TT1 and TT2 have the same row times. When you shift the data in each variable forward, lag fills the first row of TT2 with missing data indicators.

example

TT2 = lag(TT1,n) shifts data by n time steps. n must be an integer. If n is positive, then lag shifts the data forward in time (a lag). If n is negative, then lag shifts the data backward in time (a lead).

example

TT2 = lag(TT1,dt) shifts data by dt, a time interval. dt is either a duration or a calendar duration. dt must be a multiple of the regular time step of TT1.

Examples

collapse all

Create a timetable with temperature data as the variable. Shift the data forward in time by one time step and compare it to the original timetable.

Time = datetime('2015-12-18 12:00:00') + days(1:5)';
Temp = [43 42.6 42.3 39.1 37.3]';
TT = timetable(Time,Temp)
TT=5×1 timetable
            Time            Temp
    ____________________    ____

    19-Dec-2015 12:00:00      43
    20-Dec-2015 12:00:00    42.6
    21-Dec-2015 12:00:00    42.3
    22-Dec-2015 12:00:00    39.1
    23-Dec-2015 12:00:00    37.3

TT2 = lag(TT)
TT2=5×1 timetable
            Time            Temp
    ____________________    ____

    19-Dec-2015 12:00:00     NaN
    20-Dec-2015 12:00:00      43
    21-Dec-2015 12:00:00    42.6
    22-Dec-2015 12:00:00    42.3
    23-Dec-2015 12:00:00    39.1

Synchronize the two timetables for comparison. Since the timetables already have the same row times, synchronize renames the variables and horizontally concatenates them.

synchronize(TT,TT2)
ans=5×2 timetable
            Time            Temp_TT    Temp_TT2
    ____________________    _______    ________

    19-Dec-2015 12:00:00       43         NaN  
    20-Dec-2015 12:00:00     42.6          43  
    21-Dec-2015 12:00:00     42.3        42.6  
    22-Dec-2015 12:00:00     39.1        42.3  
    23-Dec-2015 12:00:00     37.3        39.1  

Create a timetable with temperature data as the variable. Shift the data in time by multiple time steps.

Time = datetime('2015-12-18 12:00:00') + days(1:5)';
Temp = [43 42.6 42.3 39.1 37.3]';
TT = timetable(Time,Temp)
TT=5×1 timetable
            Time            Temp
    ____________________    ____

    19-Dec-2015 12:00:00      43
    20-Dec-2015 12:00:00    42.6
    21-Dec-2015 12:00:00    42.3
    22-Dec-2015 12:00:00    39.1
    23-Dec-2015 12:00:00    37.3

Shift the data forward two time steps.

TT2 = lag(TT,2)
TT2=5×1 timetable
            Time            Temp
    ____________________    ____

    19-Dec-2015 12:00:00     NaN
    20-Dec-2015 12:00:00     NaN
    21-Dec-2015 12:00:00      43
    22-Dec-2015 12:00:00    42.6
    23-Dec-2015 12:00:00    42.3

Shift the data backward by three time steps.

TT2 = lag(TT,-3)
TT2=5×1 timetable
            Time            Temp
    ____________________    ____

    19-Dec-2015 12:00:00    39.1
    20-Dec-2015 12:00:00    37.3
    21-Dec-2015 12:00:00     NaN
    22-Dec-2015 12:00:00     NaN
    23-Dec-2015 12:00:00     NaN

Create a timetable with temperature data as the variable. Shift the data in time by two calendar months.

Time = datetime('2015-12-01 12:00:00') + calmonths(1:5)';
Temp = [43 37 35 39 45]';
TT = timetable(Time,Temp)
TT=5×1 timetable
            Time            Temp
    ____________________    ____

    01-Jan-2016 12:00:00     43 
    01-Feb-2016 12:00:00     37 
    01-Mar-2016 12:00:00     35 
    01-Apr-2016 12:00:00     39 
    01-May-2016 12:00:00     45 

TT2 = lag(TT,calmonths(2))
TT2=5×1 timetable
            Time            Temp
    ____________________    ____

    01-Jan-2016 12:00:00    NaN 
    01-Feb-2016 12:00:00    NaN 
    01-Mar-2016 12:00:00     43 
    01-Apr-2016 12:00:00     37 
    01-May-2016 12:00:00     35 

Input Arguments

collapse all

Input timetable.

Number of time steps to shift the data in a regular timetable, specified as an integer.

Time interval to shift the data in a regular timetable, specified as a duration or calendar duration.

Extended Capabilities

Version History

Introduced in R2016b