LagOp

Create lag operator polynomial

Description

Create a p-degree, m-dimensional lag operator polynomial A(L) = A₀ + A₁L¹ + A₂L² +...+ A_pL^p by specifying the coefficient matrices A₀,…,A_p and, optionally, the corresponding lags. L is the lag (or backshift) operator such that L^jy_t = y_t–j.

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

Syntax

A = LagOp(coefficients)

A = LagOp(coefficients,Name,Value)

Description

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

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

coefficients — Lag operator polynomial coefficients

numeric vector | square numeric matrix | cell vector of square numeric matrices

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.

Value	Polynomial Returned by LagOp
Numeric vector of length p + 1	A p-degree, 1-D lag operator polynomial, where coefficient(j) is the coefficient of lag j – 1
m-by-m square numeric matrix	A 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 matrices	A 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 + 2L¹ + 3L².

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: 'Lags',[4 8],'Tolerance',1e-10 associates the coefficients to lags 4 and 8, and sets the coefficient magnitude tolerance to 1e-10.

Lags — Lags associated with polynomial coefficients

vector of unique, nonnegative integers

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]

Tolerance — Lag inclusion tolerance

1e–12 (default) | nonnegative numeric scalar

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 c ≤ Tolerance, 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

Coefficients — Lag operator polynomial coefficients

lag-indexed cell array of numeric scalars | lag-indexed cell array of numeric matrices

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 j ≥ 0. For example, A.Coefficients{0} stores the lag 0 coefficient of A.

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

Degree — Polynomial degree p

Read-only: nonnegative numeric scalar

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

Dimension — Polynomial dimension m

Read-only: positive numeric scalar

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

Lags — Polynomial lags associated with nonzero coefficients

Read-only: lag-indexed vector of nonnegative integers

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

filter	Apply lag operator polynomial to filter time series
isEqLagOp	Determine if two LagOp objects are same mathematical polynomial
isNonZero	Find lags associated with nonzero coefficients of LagOp objects
isStable	Determine stability of lag operator polynomial
minus	Lag operator polynomial subtraction
mldivide	Apply left division to lag operator polynomials
mrdivide	Lag operator polynomial right division
mtimes	Lag operator polynomial multiplication
plus	Lag operator polynomial addition
reflect	Reflect lag operator polynomial coefficients around lag zero
toCellArray	Convert lag operator polynomial object to cell array

Examples

Create and Modify Univariate Lag Operator Polynomial

Create a LagOp object that represents the lag operator polynomial

$$A(L)=1-0.6L+0.08L^2.$$

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.

Specify Polynomial Lags

Create a LagOp object that represents the lag operator polynomial

$$A(L)=1+0.25L^4+0.1L^8+0.05L^{12}.$$

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 Multivariate Lag Operator Polynomial

Create a LagOp object that represents the lag operator polynomial

$$A\left(L\right)=\left[\begin{array}{ccc}0.5& 0& 0\\ 0& 1& 0\\ 0& 0& -0.5\end{array}\right]+\left[\begin{array}{ccc}1& 0.25& 0.1\\ -0.5& 1& -0.5\\ 0.15& -0.2& 1\end{array}\right]L^4.$$

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

Work with Lag Operator Polynomials

Create Multivariate Lag Operator Polynomial

Create the 2-D, degree 3 lag operator polynomial

$$A(L)=\left[\begin{array}{cc}1& 0\\ 0& 1\end{array}\right]+\left[\begin{array}{cc}0.5& 0.25\\ -0.1& 0.4\end{array}\right]L+\left[\begin{array}{cc}0.05& 0.025\\ -0.01& 0.04\end{array}\right]L^3.$$

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 $\mathit{A}\left(\mathit{L}\right)$ by right dividing the 2-by-2 identity matrix by $\mathit{A}\left(\mathit{L}\right)$.

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 $\mathit{A}\left(\mathit{L}\right)$, 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 $\mathit{A}\left(\mathit{L}\right)$ 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 $$y_t=A(L)e_t=A_0{e}_t+A_1{e}_{t-1}+A_2{e}_{t-2}+A_3{e}_{t-3}$$ by filtering the 2-D series of 100 random standard Gaussian deviates ${\mathit{e}}_{\mathit{t}}$through 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 ${\mathit{y}}_{\mathit{t}}.$ 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,:).

Version History

Introduced in R2010a