# lagmatrix

Create lagged time series data

## Syntax

``YLag = lagmatrix(Y,lags)``
``[YLag,TLag] = lagmatrix(Y,lags)``
``LagTbl = lagmatrix(Tbl,lags)``
``[___] = lagmatrix(___,Name=Value)``

## Description

example

````YLag = lagmatrix(Y,lags)` shifts the input regular series `Y` in time by the lags (positive) or leads (negative) in `lags`, and returns the matrix of shifted series `YLag`.```

example

````[YLag,TLag] = lagmatrix(Y,lags)` also returns a vector `TLag` representing the common time base for the shifted series relative to the original time base of 1, 2, 3, …, `numObs`.```

example

````LagTbl = lagmatrix(Tbl,lags)` shifts all variables in the input table of timetable `Tbl`, which represent regular time series, and returns the table or timetable of shifted series `LagTbl`. To select different variables in `Tbl` to shift, use the `DataVariables` name-value argument.```

example

````[___] = lagmatrix(___,Name=Value)` uses additional options specified by one or more name-value arguments, using any input-argument combination in the previous syntaxes. `lagmatrix` returns the output-argument combination for the corresponding input arguments. For example, `lagmatrix(Tbl,1,Y0=zeros(1,5),DataVariables=1:5)` lags, by one period, the first five variables in the input table `Tbl` and sets the presample of each series to 0.```

## Examples

collapse all

Create a bivariate time series matrix `X` with five observations each.

`Y = [1 -1; 2 -2 ;3 -3 ;4 -4 ;5 -5]`
```Y = 5×2 1 -1 2 -2 3 -3 4 -4 5 -5 ```

Create a shifted matrix, which is composed of the original X and its first two lags.

```lags = [0 1 2]; XLag = lagmatrix(Y,lags)```
```XLag = 5×6 1 -1 NaN NaN NaN NaN 2 -2 1 -1 NaN NaN 3 -3 2 -2 1 -1 4 -4 3 -3 2 -2 5 -5 4 -4 3 -3 ```

`XLAG` is a 5-by-6 matrix:

• The first two columns contain the original data (lag 0).

• Columns 3 and 4 contain the data lagged by one unit.

• Columns 5 and 6 contain the data lagged by two units.

By default, `lagmatrix` returns only values corresponding to the time base of the original data, and the function fills unknown presample values using `NaN`s.

Create a bivariate time series matrix `X` with five observations each.

`Y = [1 -1; 2 -2 ;3 -3 ;4 -4 ;5 -5]`
```Y = 5×2 1 -1 2 -2 3 -3 4 -4 5 -5 ```

Create a shifted matrix, which is composed of the original X and its first two lags. Return the time base of the shift series.

```lags = [0 1 2]; [XLag,TLag] = lagmatrix(Y,lags);```

By default, `lagmatrix` returns the time base of the input data.

Shift multiple time series, which are variables in tables, using the default options of `lagmatrix`.

Load data of yearly Canadian inflation and interest rates `Data_Canada.mat`, which contains five series in the table `DataTable`.

`load Data_Canada`

Create a timetable from the table of data.

```dates = datetime(dates,12,31); TT = table2timetable(DataTable,RowTimes=dates); TT.Observations = []; tail(TT)```
```ans=8×5 timetable Time INF_C INF_G INT_S INT_M INT_L ___________ _______ _______ ______ ______ ______ 31-Dec-1987 4.2723 4.608 8.1692 9.4158 9.9267 31-Dec-1988 3.9439 4.5256 9.4158 9.7717 10.227 31-Dec-1989 4.8743 4.7258 12.016 10.203 9.9217 31-Dec-1990 4.6547 3.1015 12.805 11.193 10.812 31-Dec-1991 5.4633 2.8614 8.8301 9.1625 9.8067 31-Dec-1992 1.4946 1.2281 6.5088 7.4317 8.7717 31-Dec-1993 1.8246 1.0473 4.9268 6.4583 7.8767 31-Dec-1994 0.18511 0.60929 5.4168 7.7867 8.58 ```

Create timetable containing all series lagged by one year, the series themselves, and the series led by a year.

```lags = [1 0 -1]; LagTT = lagmatrix(TT,lags); head(LagTT)```
```ans=8×15 timetable Time Lag1INF_C Lag1INF_G Lag1INT_S Lag1INT_M Lag1INT_L Lag0INF_C Lag0INF_G Lag0INT_S Lag0INT_M Lag0INT_L Lead1INF_C Lead1INF_G Lead1INT_S Lead1INT_M Lead1INT_L ___________ _________ _________ _________ _________ _________ _________ _________ _________ _________ _________ __________ __________ __________ __________ __________ 31-Dec-1954 NaN NaN NaN NaN NaN 0.6606 1.4468 1.4658 2.6683 3.255 0.077402 0.76162 1.5533 2.7908 3.1892 31-Dec-1955 0.6606 1.4468 1.4658 2.6683 3.255 0.077402 0.76162 1.5533 2.7908 3.1892 1.4218 3.0433 2.9025 3.7575 3.6058 31-Dec-1956 0.077402 0.76162 1.5533 2.7908 3.1892 1.4218 3.0433 2.9025 3.7575 3.6058 3.1546 2.3148 3.7775 4.565 4.125 31-Dec-1957 1.4218 3.0433 2.9025 3.7575 3.6058 3.1546 2.3148 3.7775 4.565 4.125 2.4828 1.3636 2.2925 3.4692 4.115 31-Dec-1958 3.1546 2.3148 3.7775 4.565 4.125 2.4828 1.3636 2.2925 3.4692 4.115 1.183 2.0722 4.805 4.9383 5.0492 31-Dec-1959 2.4828 1.3636 2.2925 3.4692 4.115 1.183 2.0722 4.805 4.9383 5.0492 1.2396 1.2139 3.3242 4.5192 5.1892 31-Dec-1960 1.183 2.0722 4.805 4.9383 5.0492 1.2396 1.2139 3.3242 4.5192 5.1892 1.0156 0.46074 2.8342 4.375 5.0583 31-Dec-1961 1.2396 1.2139 3.3242 4.5192 5.1892 1.0156 0.46074 2.8342 4.375 5.0583 1.1088 1.3737 4.0125 4.6 5.1008 ```

`LagTT` is a timetable containing the shifted series. `lagmatrix` appends each variable of the input timetable by `Lag``j` or `Lead``j`, depending on whether the series is a lag or lead, with `j` indicating the number of shifting units.

By default, `lagmatrix` shifts all variables in the input table. You can choose a subset of variables to shift by using the `DataVariables` name-value argument. For example, shift only the inflation rate series.

```LagTTINF = lagmatrix(TT,lags,DataVariables=["INF_C" "INF_G"]); head(LagTTINF)```
```ans=8×6 timetable Time Lag1INF_C Lag1INF_G Lag0INF_C Lag0INF_G Lead1INF_C Lead1INF_G ___________ _________ _________ _________ _________ __________ __________ 31-Dec-1954 NaN NaN 0.6606 1.4468 0.077402 0.76162 31-Dec-1955 0.6606 1.4468 0.077402 0.76162 1.4218 3.0433 31-Dec-1956 0.077402 0.76162 1.4218 3.0433 3.1546 2.3148 31-Dec-1957 1.4218 3.0433 3.1546 2.3148 2.4828 1.3636 31-Dec-1958 3.1546 2.3148 2.4828 1.3636 1.183 2.0722 31-Dec-1959 2.4828 1.3636 1.183 2.0722 1.2396 1.2139 31-Dec-1960 1.183 2.0722 1.2396 1.2139 1.0156 0.46074 31-Dec-1961 1.2396 1.2139 1.0156 0.46074 1.1088 1.3737 ```

Create a vector of univariate time series data.

`y = [0.1 0.4 -0.2 0.1 0.2]';`

Create vectors representing presample and postsample data.

`y0 = [0.50; 0.75]*y(1)`
```y0 = 2×1 0.0500 0.0750 ```
`yF = [0.75; 0.50]*y(end)`
```yF = 2×1 0.1500 0.1000 ```

Shift the series by two units in both directions. Specify the presample and postsample data, and return a matrix containing shifted series for the entire time base.

```lags = [2 0 -2]; [YLag,TLag] = lagmatrix(y,lags,Y0=y0,YF=yF)```
```YLag = 5×3 0.0500 0.1000 -0.2000 0.0750 0.4000 0.1000 0.1000 -0.2000 0.2000 0.4000 0.1000 0.1500 -0.2000 0.2000 0.1000 ```
```TLag = 5×1 1 2 3 4 5 ```

Because the presample and postsample have enough observations to cover the time base of the input data, the shifted series `YLag` is completely specified (it does not contain `NaN` entries).

Shift the series in the same way, but return a matrix containing shifted series for the entire time base by specifying `"full"` for the `Shape` name-value argument.

`[YLagFull,TLagFull] = lagmatrix(y,lags,Y0=y0,YF=yF,Shape="full")`
```YLagFull = 9×3 NaN 0.0500 0.1000 NaN 0.0750 0.4000 0.0500 0.1000 -0.2000 0.0750 0.4000 0.1000 0.1000 -0.2000 0.2000 0.4000 0.1000 0.1500 -0.2000 0.2000 0.1000 0.1000 0.1500 NaN 0.2000 0.1000 NaN ```
```TLagFull = 9×1 -1 0 1 2 3 4 5 6 7 ```

Because the presample and postsample do not contain enough observations to cover the full time base, which includes presample through postsample times, `lagmatrix` fills unknown sample units using `NaN` values.

## Input Arguments

collapse all

Time series data, specified as a `numObs`-by-`numVars` numeric matrix. Each column of `Y` corresponds to a variable, and each row corresponds to an observation.

Data Types: `double`

Data shifts, specified as an integer or integer-valued vector of length `numShifts`.

• Lags are positive integers, which shift the input series forward over the time base.

• Leads are negative integers, which shift the input series backward over the time base.

`lagmatrix` applies each specified shift in `lags`, in order, to each input series.

Shifts of regular time series have units of one time step.

Data Types: `double`

Time series data, specified as a table or timetable with `numObs` rows. Each row of `Tbl` is an observation.

If `Tbl` is a timetable, it must represent a sample with a regular datetime time step (see `isregular`).

Specify `numVars` variables to filter by using the `DataVariables` argument. The selected variables must be numeric.

### Name-Value Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Example: `lagmatrix(Tbl,1,Y0=zeros(1,5),DataVariables=1:5)` lags, by one period, the first 5 variables in the input table `Tbl` and sets the presample of each series to 0.

Presample data to backward fill lagged series, specified as a matrix with `numVars` columns, or a table or timetable. For a table or timetable, the `DataVariables` name-value argument selects the variables in `Y0` to shift.

`Y0` must have the same data type as the input data.

Timetables must have regular sample times preceding times in `Tbl`.

`lagmatrix` fills required presample values from the end of `Y0`.

Example: `Y0=zeros(size(Y,2),2)`

Postsample data to frontward fill led series, specified as a matrix with `numVars` columns, or a table or timetable. For a table or timetable, the `DataVariables` name-value argument selects the variables in `YF` to shift. The default for postsample data is NaN.

`YF` must have the same data type as the input data.

Timetables must have regular sample times following times in `Tbl`.

`lagmatrix` fills required postsample values from the beginning of `YF`.

Example: `YF=ones(size(Y,2),3)`

Variables in `Tbl`, `Y0`, and `YF`, from which `lagmatrix` creates shifted time series data, specified as a string vector or cell vector of character vectors containing variable names in `Tbl.Properties.VariableNames`, or an integer or logical vector representing the indices of names. The selected variables must be numeric.

Example: `DataVariables=["GDP" "CPI"]`

Example: `DataVariables=[true true false false]` or `DataVariables=[1 2]` selects the first and second table variables.

Data Types: `double` | `logical` | `char` | `cell` | `string`

Part of the shifted series to appear in the outputs, specified as a value in this table.

ValueDescription
`"full"`Outputs contain all values in the input time series data and all specified presample `Y0` or postsample `Yf` values on an expanded time base.
`"same"`Outputs contain only values on the original time base.
`"valid"`Outputs contain values for times at which all series have specified (non-`NaN`) values.

To illustrate the shape of the output shifted time series for each value of `Shape`, suppose the input time series data is a 2-D series with `numObs` = T observations $\left[\begin{array}{cc}{y}_{1,t}& {y}_{2,t}\end{array}\right],$ and `lags` is `[1 0 -1]`. The output shifted series is one of the three T-by-6 matrix arrays in this figure.

Example: `Shape="full"`

Data Types: `char` | `string`

## Output Arguments

collapse all

Shifted time series variables in `Y`, returned as a numeric matrix. `lagmatrix` returns `YLag` when you supply the input `Y`.

Columns are, in order, all series in `Y` shifted by the `lags(1)`, all series in `Y` shifted by the `lags(2)`, …, all series in `Y` shifted by `lags(end)`. Rows depend on the value of the `Shape` name-value argument.

For example, suppose `Y` is the 2-D time series of `numObs` = T observations $\left[\begin{array}{cc}{y}_{1,t}& {y}_{2,t}\end{array}\right],$ `lags` is `[1 0 -1]`, and `Shape` if `"full"`. `YLag` is the T-by-6 matrix

`$\left[\begin{array}{cccccc}NaN& NaN& NaN& NaN& {y}_{1,1}& {y}_{2,1}\\ NaN& NaN& {y}_{1,1}& {y}_{2,1}& {y}_{1,2}& {y}_{2,2}\\ {y}_{1,1}& {y}_{2,1}& {y}_{1,2}& {y}_{2,2}& {y}_{1,3}& {y}_{2,3}\\ ⋮& ⋮& ⋮& ⋮& ⋮& ⋮\\ {y}_{1,T-2}& {y}_{2,T-2}& {y}_{1,T-1}& {y}_{2,T-1}& {y}_{1,T}& {y}_{2,T}\\ {y}_{1,T-1}& {y}_{2,T-1}& {y}_{1,T}& {y}_{2,T}& NaN& NaN\\ {y}_{1,T}& {y}_{2,T}& NaN& NaN& NaN& NaN\end{array}\right].$`

Common time base for the shifted series relative to the original time base of `1`, `2`, `3`, …, `numObs`, returned as a vector of length equal to the number of observations in `YLag`. `lagmatrix` returns `TLag` when you supply the input `Y`.

Series with lags (`lags` > 0) have higher indices; series with leads (`lags` < 0) have lower indices. For example, the value of `TLag` for the example in the `YLag` output description is the column vector with entries `0:(T+1)`.

Shifted time series variables and common time base, returned as a table or timetable, the same data type as `Tbl`. `lagmatrix` returns `LagTbl` when you supply the input `Tbl`.

`LagTbl` contains the outputs `YLag` and `TLag`. The following conditions apply:

• Each lagged variable of `LagTbl` has a label `Lagjvarname`, where `varname` is the corresponding variable name in `DataVariables` and `j` is lag `j` in `lags`.

• Each lead variable has a label `Leadjvarname`, where `j` is lead `j` in `lags`.

• If `LagTbl` is a table, the variable labeled `TLag` contains `TLag`.

• If `LagTbl` is a timetable, the `Time` variable contains `TLag`.

## Version History

Introduced before R2006a