lagmatrix

Create lagged time series data

Syntax

YLag = lagmatrix(Y,lags)

[YLag,TLag] = lagmatrix(Y,lags)

LagTbl = lagmatrix(Tbl,lags)

[___] = lagmatrix(___,Name=Value)

Description

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

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

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

[___] = lagmatrix(___,Name=Value) specifies options using one or more name-value arguments in addition to any of the input argument combinations in 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

Shift Matrix of Data

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

Return Time Base of Shifted Series

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 Table Variables

Since R2022a

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)

       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)

       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 Lagj or Leadj, 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)

       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  

Specify Presample and Postsample Data

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

Y — Time series data

numeric matrix

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

lags — Data shifts

integer | integer-valued vector

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

Tbl — Time series data

table | timetable

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.

Y0 — Presample data

NaN (default) | numeric matrix | table | timetable

Since R2022a

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)

YF — Postsample data to front fill led series

NaN (default) | numeric matrix | table | timetable

Since R2022a

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)

DataVariables — Variables in Tbl, Y0, and YF

all variables (default) | string vector | cell vector of character vectors | vector of integers | logical vector

Since R2022a

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

Shape — Part of shifted series to appear in outputs

"same" (default) | "full" | "valid" | character vector

Since R2022a

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

Value	Description
"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

YLag — Shifted time series variables

numeric matrix

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].$$

TLag — Common time base for the shifted series

numeric matrix

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

LagTbl — Shifted time series variables and common time base

table | timetable

Since R2022a

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

R2022a: lagmatrix accepts input data in tables and timetables, and returns results in tables

In addition to accepting input data in numeric arrays, lagmatrix accepts input data in tables and timetables. To choose which variables from the input table or timetable to lag, specify the DataVariables name-value argument.

R2022a: Specify presample, postsample, or output shape, and return time base

In addition to supporting input data in a table or timetable, lagmatrix enables you to optionally specify the following values by using name-value argument syntax:

• Y0 — Presample data, specified as a matrix, table, or timetable

• YF — Postsample data, specified as a matrix, table, or timetable

• Shape — Output shape specifying which part of the shifted series to return.

Also, lagmatrix returns the time base defined by the value of Shape, either in the second output position when you specify numeric data or as a variable in the output table when you specify data in a table or timetable.