# lag

Time-shift data in timetable

## Syntax

``TT2 = lag(TT1)``
``TT2 = lag(TT1,n)``
``TT2 = lag(TT1,dt)``

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

## Version History

Introduced in R2016b