Main Content

LagOp

Create lag operator polynomial

Description

Create a p-degree, m-dimensional lag operator polynomial A(L) = A0 + A1L1 + A2L2 +...+ ApLp by specifying the coefficient matrices A0,…,Ap and, optionally, the corresponding lags. L is the lag (or backshift) operator such that Ljyt = ytj.

LagOp object functions enable you to work with specified polynomials. For example, you can filter time series data through a polynomial, determine whether one is stable, or combine multiple polynomials by performing polynomial algebra including addition, subtraction, multiplication, and division.

To fit a dynamic model containing lag operator polynomials to data, create the appropriate model object, and then fit it to the data. For univariate models, see arima and estimate; for multivariate models, see varm and estimate. For further analysis, you can create a LagOp object from the resulting estimated coefficients.

Creation

Description

example

A = LagOp(coefficients) creates a lag operator polynomial A with coefficients coefficients, and sets the Coefficients property.

example

A = LagOp(coefficients,Name,Value) specifies additional options using one or more name-value pair arguments. For example, LagOp(coefficients,'Lags',[0 4 8],'Tolerance',1e-10) associates the coefficients to lags 0, 4, and 8, and sets the lag inclusion tolerance to 1e-10.

Input Arguments

expand all

Lag operator polynomial coefficients, specified as a numeric vector, m-by-m square numeric matrix, or cell vector of m-by-m square numeric matrices.

ValuePolynomial Returned by LagOp
Numeric vector of length p + 1A p-degree, 1-D lag operator polynomial, where coefficient(j) is the coefficient of lag j – 1
m-by-m square numeric matrixA 0-degree, m-D lag operator polynomial, where coefficient is A0, the coefficient of lag 0
Length p + 1 cell vector of m-by-m square numeric matricesA p-degree m-D lag operator polynomial, where coefficient(j) is the coefficient matrix of lag j – 1

Example: LagOp(1:3) creates the polynomial A(L) = 1 + 2L1 + 3L2.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'Lags',[4 8],'Tolerance',1e-10 associates the coefficients to lags 4 and 8, and sets the coefficient magnitude tolerance to 1e-10.

Lags associated with the polynomial coefficients, specified as the comma-separated pair consisting of 'Lags' and a vector of unique, nonnegative integers. Lags must have numcoeff elements, where numcoeff is one of the following:

  • If coefficients is a numeric or cell vector, numcoeff = numel(coefficients). The coefficient of lag Lags(j) is coefficients(j).

  • If coefficients is a matrix, numcoeff = 1.

Example: 'Lags',[0 4 8 12]

Lag inclusion tolerance, specified as the comma-separated pair consisting of 'Tolerance' and a nonnegative numeric scalar.

Let c be the element of coefficient j with the largest magnitude. If cTolerance, LagOp removes coefficient j from the polynomial. Consequently, MATLAB® performs the following actions:

  • Remove the corresponding lag from the vector in the Lags property.

  • Replace the corresponding coefficient of the array in the Coefficients property with zeros(m).

  • If a removed lag is the final lag in the polynomial, MATLAB reduces the degree of the polynomial to the degree of the next largest lag present in the polynomial. For example, if MATLAB removes lags 3 and 4 from a degree 4 polynomial because their coefficient magnitudes are below Tolerance, the resulting polynomial has a degree of 2.

Example: 'Tolerance',1e-10

Properties

expand all

Lag operator polynomial coefficients, specified as a lag-indexed cell array of numeric scalars or m-by-m matrices. Coefficients{j} is the coefficient of lag j, where the integer j0. For example, A.Coefficients{0} stores the lag 0 coefficient of A.

The Lags property stores the indices of nonzero coefficients of Coefficients.

This property is read-only.

Polynomial degree p, specified as a nonnegative numeric scalar. Degree = max(Lags), the largest lag associated with a nonzero coefficient.

Data Types: double

This property is read-only.

Polynomial dimension m, specified as a positive numeric scalar. You can apply the polynomial A only to an m-D time series variable.

Data Types: double

This property is read-only.

Polynomial lags associated with nonzero coefficients, specified as a lag-indexed vector of nonnegative integers.

To work with the value of Lags, convert it to a standard MATLAB vector by entering the following code.

lags = A.Lags;

Data Types: double

Object Functions

filterApply lag operator polynomial to filter time series
isEqLagOpDetermine if two LagOp objects are same mathematical polynomial
isNonZeroFind lags associated with nonzero coefficients of LagOp objects
isStableDetermine stability of lag operator polynomial
minusLag operator polynomial subtraction
mldivideLag operator polynomial left division
mrdivideLag operator polynomial right division
mtimesLag operator polynomial multiplication
plusLag operator polynomial addition
reflectReflect lag operator polynomial coefficients around lag zero
toCellArrayConvert lag operator polynomial object to cell array

Examples

collapse all

Create a LagOp object that represents the lag operator polynomial

A(L)=1-0.6L+0.08L2.

A = LagOp([1 -0.6 0.08])
A = 
    1-D Lag Operator Polynomial:
    -----------------------------
        Coefficients: [1 -0.6 0.08]
                Lags: [0 1 2]
              Degree: 2
           Dimension: 1

Display the coefficient of lag 0.

a0 = A.Coefficients{0}
a0 = 1

Assign a nonzero coefficient to the third lag:

A.Coefficients{3} = 0.5
A = 
    1-D Lag Operator Polynomial:
    -----------------------------
        Coefficients: [1 -0.6 0.08 0.5]
                Lags: [0 1 2 3]
              Degree: 3
           Dimension: 1

The polynomial degree increases to 3.

Create a LagOp object that represents the lag operator polynomial

A(L)=1+0.25L4+0.1L8+0.05L12.

nonzeroCoeffs = [1 0.25 0.1 0.05];
lags = [0 4 8 12];
A = LagOp(nonzeroCoeffs,'Lags',lags)
A = 
    1-D Lag Operator Polynomial:
    -----------------------------
        Coefficients: [1 0.25 0.1 0.05]
                Lags: [0 4 8 12]
              Degree: 12
           Dimension: 1

Extract the coefficients from the lag operator polynomial, and display all coefficients from lags 0 through 12.

allCoeffs = toCellArray(A);         % Extract coefficients
allCoeffs = cell2mat(allCoeffs');
allLags = 0:A.Degree;               % Prepare lags for display

table(allCoeffs,'RowNames',"Lag " + string(allLags))
ans=13×1 table
              allCoeffs
              _________

    Lag 0          1   
    Lag 1          0   
    Lag 2          0   
    Lag 3          0   
    Lag 4       0.25   
    Lag 5          0   
    Lag 6          0   
    Lag 7          0   
    Lag 8        0.1   
    Lag 9          0   
    Lag 10         0   
    Lag 11         0   
    Lag 12      0.05   

Create a LagOp object that represents the lag operator polynomial

A(L)=[0.50001000-0.5]+[10.250.1-0.51-0.50.15-0.21]L4.

Phi0 = [0.5 0   0;... 
        0   1   0;...
        0   0   -0.5];

Phi4 = [1       0.25    0.1;...
        -0.5    1       -0.5;...
        0.15    -0.2    1];

Phi = {Phi0 Phi4};
lags = [0 4];

A = LagOp(Phi,'Lags',lags)
A = 
    3-D Lag Operator Polynomial:
    -----------------------------
        Coefficients: [Lag-Indexed Cell Array with 2 Non-Zero Coefficients]
                Lags: [0 4]
              Degree: 4
           Dimension: 3

Create Multivariate Lag Operator Polynomial

Create the 2-D, degree 3 lag operator polynomial

A(L)=[0.50.25-0.10.4]L+[0.050.025-0.010.04]L3.

m = 2;
A0 = eye(m);
A1 = [0.5 0.25; -0.1 0.4];
A3 = 0.1*A1;
Coeffs = {A0 A1 A3};
lags = [0 1 3];

A = LagOp(Coeffs,'Lags',lags)
A = 
    2-D Lag Operator Polynomial:
    -----------------------------
        Coefficients: [Lag-Indexed Cell Array with 3 Non-Zero Coefficients]
                Lags: [0 1 3]
              Degree: 3
           Dimension: 2

Determine Polynomial Stability

A lag operator polynomial is stable if the magnitudes of all eigenvalues of its characteristic polynomial are less than 1.

Determine whether the polynomial is stable, and return the eigenvalues of its characteristic polynomial.

[tf,evals] = isStable(A)
tf = logical
   1

evals = 6×1 complex

  -0.5820 + 0.1330i
  -0.5820 - 0.1330i
   0.0821 + 0.2824i
   0.0821 - 0.2824i
   0.0499 + 0.2655i
   0.0499 - 0.2655i

Invert Polynomial

Compute the inverse of A(L) by right dividing the 2-by-2 identity matrix by A(L).

Ainv = mrdivide(eye(A.Dimension),A)
Ainv = 
    2-D Lag Operator Polynomial:
    -----------------------------
        Coefficients: [Lag-Indexed Cell Array with 10 Non-Zero Coefficients]
                Lags: [0 1 2 3 4 5 6 7 8 9]
              Degree: 9
           Dimension: 2

Ainv is a LagOp object representing the inverse of A(L), a degree 9 lag operator polynomial. In theory, the inverse of a lag operator polynomial is of infinite degree, but the mrdivide coefficient-magnitude tolerances truncate the polynomial.

Multiply A(L) and its inverse.

checkinv = Ainv*A
checkinv = 
    2-D Lag Operator Polynomial:
    -----------------------------
        Coefficients: [Lag-Indexed Cell Array with 4 Non-Zero Coefficients]
                Lags: [0 10 11 12]
              Degree: 12
           Dimension: 2

Because the inverse computation returns the truncated theoretical inverse, the product checkinv contains lags representing the remainder. You can decrease the mrdivide coefficient-magnitude tolerances to obtain an inverse polynomial that is more precise.

Filter Time Series

Produce the 2-D time series yt=A(L)et=A0et+A1et-1+A2et-2+A3et-3 by filtering the 2-D series of 100 random standard Gaussian deviates etthrough the polynomial.

T = 100;
e = randn(T,m);
y = filter(A,e);
plot((A.Degree + 1):T,y)
title('Filtered Series')

y is a 97-by-2 matrix representing yt. y has p fewer observations than e because filter requires the first p observations of e to initialize the dynamic series when producing y(1:4,:).

Introduced in R2010a