lag

Time-shift data in timetable

Syntax

TT2 = lag(TT1)

TT2 = lag(TT1,n)

TT2 = lag(TT1,dt)

Description

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.

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).

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

Shift Timetable Data

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  

Shift Timetable Data by Multiple Time Steps

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

Shift Timetable Data by Time Interval

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

TT1 — Input timetable

timetable

Input timetable.

n — Number of time steps to shift data in regular timetable

integer

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

dt — Time interval to shift data in regular timetable

duration | calendar duration

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

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2016b