# 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

### Syntax

``A = LagOp(coefficients)``
``A = LagOp(coefficients,Name,Value)``

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

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

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

 `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` Lag operator polynomial left division `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

collapse all

Create a `LagOp` object that represents the lag operator polynomial

`$A\left(L\right)=1-0.6L+0.08{L}^{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`.

Create a `LagOp` object that represents the lag operator polynomial

`$A\left(L\right)=1+0.25{L}^{4}+0.1{L}^{8}+0.05{L}^{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 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 ```

Create Multivariate Lag Operator Polynomial

Create the 2-D, degree 3 lag operator polynomial

`$A\left(L\right)=\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\left(L\right){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}}\text{\hspace{0.17em}}$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