## Represent Time Series Models Using Econometrics Toolbox Objects

### Model Objects

Econometrics Toolbox™ includes a number of model objects used to represent a variety of discrete-time, time series models. The supported models are univariate or multivariate, linear or nonlinear, and standard or Bayesian. Model specification tests (see Specification Testing), economic theory, or your analysis goals can suggest a model, or set of models, for your data.

After preprocessing your data, running specification tests, and selecting a set of
candidate models, create the objects that best represent the models in MATLAB^{®} to proceed with your analysis. How you create an object depends on the
object type. In general, you create a model object by calling the object using
its name and providing values for the corresponding *model
parameters*. Models contain two main types of parameters:
*model infrastructure parameters*, such as model
dimensionality or number of lags, and *estimable parameters*,
such as coefficients and an error variance. Objects store the parameter values, and
other information, in model properties. You operate on models by passing
them and possibly other inputs, such as data, to object
functions.

The following tables contain the objects available with Econometrics Toolbox.

#### Univariate Linear Model Objects

This table contains the available objects that represent univariate linear models. You can create some models by using the Econometric Modeler app.

Model | Object | Econometric Modeler Support? |
---|---|---|

Integrated, autoregressive, moving average (ARIMA) model optionally containing exogenous predictor variables (ARIMAX) or seasonal components (SARIMA) | `arima` | Yes |

Regression model with ARIMA errors | `regARIMA` | Yes |

Generalized autoregressive conditional heteroscedasticity model (GARCH) | `garch` | Yes |

Exponential GARCH model | `egarch` | Yes |

Glosten-Jagannathan-Runkle model | `gjr` | Yes |

#### Multivariate Linear Model Objects

This table contains the available objects that represent multivariate linear models.

Description | Object | Econometric Modeler Support? |
---|---|---|

Vector autoregression model (VAR) optionally containing exogenous predictor variables (VARX) | `varm` | Yes |

Vector error-correction (VEC), or cointegrated VAR, model optionally containing exogenous predictor variables (VECX) | `vecm` | Yes |

#### Nonlinear Model Objects

Nonlinear models included with Econometrics Toolbox are nonlinear because at least one model parameter or coefficient is time-varying. Regime-switching and time-varying state-space models have this characteristic. This table contains the available objects that represent multivariate nonlinear models.

Description | Object | Notes | Econometric Modeler Support? |
---|---|---|---|

Discrete-state threshold-switching dynamic regression model | `tsVAR` | A `tsVAR` object is the composition of
`arima` or `varm` objects,
specifying the dynamic structure in each state, and a
`threshold` object, specifying the
switching mechanism ( see Other Models). | No |

Discrete-state Markov-switching dynamic regression model | `msVAR` | An `msVAR` object is the composition of
`arima` or `varm` objects,
specifying the dynamic structure in each state, and a
`dtmc` object, specifying the switching
mechanism ( see Other Models). | No |

Standard, continuous state-space model optionally containing exogenous predictor variables | `ssm` | You can specify coefficient matrices explicitly or implicitly by supplying a custom function | No |

Continuous state-space model with diffuse initial states optionally containing exogenous predictor variables | `dssm` | You can specify coefficient matrices explicitly or implicitly by supplying a custom function | No |

#### Bayesian Model Objects

Econometrics Toolbox includes objects that represent a Bayesian view of some of the available models. A Bayesian model object specifies the parametric form of the model and the prior distributions on the parameters.

**Bayesian Linear Regression Model Objects. **Bayesian linear regression model objects specify a linear regression model
for a univariate response variable and the joint prior distribution of the
regression coefficients and disturbance variance. In addition to standard
Bayesian linear regression, several objects implement Bayesian predictor
selection.

This table contains the available objects that represent Bayesian linear
regression models. To create a Bayesian linear regression model object, you
can call the object by name or use the `bayeslm`

function.

Description | Object | Econometric Modeler Support? |
---|---|---|

Normal-inverse-gamma conjugate prior model. The regression coefficients and disturbance variance are dependent random variables. | `conjugateblm` | No |

Normal-inverse-gamma semiconjugate prior model. The regression coefficients and disturbance variance are independent random variables. | `semiconjugateblm` | No |

Joint prior distribution is proportional to the inverse of the disturbance variance. | `diffuseblm` | No |

Joint prior distribution is specified by a random sample from the respective distributions. | `empiricalblm` | No |

Joint prior distribution is specified in a custom function that you write. | `customblm` | No |

Bayesian lasso regression | `lassoblm` | No |

Stochastic search variable selection (SSVS). The regression coefficients and disturbance variance are dependent random variables (the prior and posterior distributions are conjugate). | `mixconjugateblm` | No |

SSVS. The regression coefficients and disturbance variance are independent random variables (the prior and posterior distributions are semiconjugate). | `mixsemiconjugateblm` | No |

**Bayesian VAR Model. **Bayesian VAR model objects specify a VAR model for the multivariate
response variable and the joint prior distribution of the linear coefficient
matrices and innovations covariance matrix. This table contains the
available objects that represent Bayesian VAR models. To create a Bayesian
VAR model object, you can call the object by name or use the `bayesvarm`

function.

Description | Object | Econometric Modeler Support? |
---|---|---|

Normal conjugate prior on the coefficients and fixed covariance | `normalbvarm` | No |

Matrix-normal-inverse-Wishart conjugate prior model. The VAR coefficients and innovations covariance are dependent random variables. | `conjugatebvarm` | No |

Matrix-normal-inverse-Wishart semiconjugate prior model. The VAR coefficients and innovations covariance are independent random variables. | `semiconjugatebvarm` | No |

Joint prior distribution is proportional to the inverse of the determinant of the innovations covariance. | `diffusebvarm` | No |

Joint prior distribution is specified by a random sample from the respective distributions. | `empiricalbvarm` | No |

**Bayesian State-Space Model. **Bayesian state-space model objects specify a linear Gaussian state-space
model the multivariate response variable and the joint prior distribution of
the parameters. To create a Bayesian state-space model object, call the
`bssm`

function. Custom functions you write determine the
structure of the state-space model and the joint prior distribution of the
parameters.

#### Other Models

Econometrics Toolbox includes several objects that you cannot directly fit to data, but are useful for experimenting, characterizing, and visualizing dynamic systems. This table contains the available objects.

Description | Object | Estimation | Econometric Modeler Support? |
---|---|---|---|

Threshold transitions characterized by transition mid-levels and a transition type | `threshold` | Estimate threshold transitions of a threshold-switching
dynamic regression model `tsVAR` . | No |

Discrete-time Markov chain characterized by a transition matrix | `dtmc` | Estimate the transition matrix of a Markov-switching dynamic
regression model `msVAR` . | No |

Lag operator polynomial | `LagOp` | Not directly estimable | No |

### Model Properties

A model object holds all the information necessary for characterizing the model and performing operations, such as estimation and forecasting. This information is model dependent, but it can include the following quantities:

Parametric form of the model

Number of model parameters (e.g., the degree of the model)

Innovation distribution (Gaussian or Student’s

*t*)Amount of presample data needed to initialize the model

Such pieces of information are *properties* of
the model, which are stored as fields *within* the model object.
In this way, a model object resembles a MATLAB data structure (`struct`

array).

All model objects have properties according to the econometric models they represent. Each property has a predefined name, which you cannot change.

For example, `arima`

supports conditional mean models
(multiplicative and additive AR, MA, ARMA, ARIMA, and ARIMAX processes). Every
`arima`

model object has these properties, shown with their
corresponding names.

Property Name | Property Description |
---|---|

`Constant` | Model constant |

`AR` | Nonseasonal AR coefficients |

`MA` | Nonseasonal MA coefficients |

`SAR` | Seasonal AR coefficients (in a multiplicative model) |

`SMA` | Seasonal MA coefficients (in a multiplicative model) |

`D` | Degree of nonseasonal differencing |

`Seasonality` | Degree of seasonal differencing |

`Variance` | Variance of the innovation distribution |

`Distribution` | Parametric family of the innovation distribution |

`P` | Amount of presample data needed to initialize the AR component of the model |

`Q` | Amount of presample data needed to initialize the MA component of the model |

### Create Model Object

Create a model object by using its creation function and assigning values to model properties. Objects require values for model infrastructure parameters, either specified directly or inferred by other inputs. Estimable parameters can be specified or unspecified. The creation function assigns default values to any properties you do not, or cannot, specify.

**Tip**

It is good practice to be aware of the default property values for any model you create.

You can *fully specify* a model by specifying all parameter
values, or *partially specify* a model by providing only values
of the required, model infrastructure parameters and optionally some estimable
parameters. In most cases, an estimable parameter is configured for estimation when
its value is `NaN`

, which is the default value for estimable
parameters for most models. Some objects accept a custom function specifying the
model form. Most objects support parameter estimation.

For example, to create a model object representing a particular ARIMA model, use
the `arima`

function and specify at least the autoregressive and
moving average polynomial degrees and the degree of nonseasonal integration. The
function creates the model object of the corresponding type (`arima`

)
in the MATLAB workspace, as shown in the figure.

You can work with model objects as you would with any other variable in MATLAB. For example, you can assign the object variable a name, view it in the MATLAB Workspace, and display its value in the Command Window by typing its name.

When a model object exists in the workspace, double-click its name in the
Workspace window to open the Variable Editor. The Variable Editor shows all model
properties and their names. This image shows a workspace containing an
`arima`

model named `Mdl`

.

Each property name is assigned a value. You can access or reassign writable
properties by using dot notation, for example, ```
Mdl.Constant =
NaN;
```

In addition to having a predefined name, each model property has a predefined data
type. When assigning or modifying a property’s value, the assignment must be
consistent with the property data type. For example, the `arima`

properties have these data types.

Property Name | Property Data Type |
---|---|

`Constant` | Scalar |

`AR` | Cell array |

`MA` | Cell array |

`SAR` | Cell array |

`SMA` | Cell array |

`D` | Nonnegative integer |

`Seasonality` | Nonnegative integer |

`Variance` | Positive scalar |

`Distribution` | `struct` array |

`P` | Nonnegative integer (you cannot specify) |

`Q` | Nonnegative integer (you cannot specify) |

#### Specify an AR(2) Model

To illustrate assigning property values, consider specifying the AR(2) model

$${y}_{t}=0.8{y}_{t-1}-0.2{y}_{t-2}+{\epsilon}_{t},$$

where the innovations are independent and identically distributed normal random variables with mean 0 and variance 0.2. Because the equation is a conditional mean model, use `arima`

to create an object that represents the model. Assign values to model properties by using name-value pair arguments.

This model has two AR coefficients, 0.8 and -0.2. Assign these values to the property `AR`

as a cell array, `{0.8,-0.2}`

. Assign the value `0.2`

to `Variance`

, and `0`

to `Constant`

. You do not need to assign a value to `Distribution`

because the default innovation distribution is `'Gaussian'`

. There are no MA terms, seasonal terms, or degrees of integration, so do not assign values to these properties. You cannot specify values for the properties `P`

and `Q`

.

In summary, specify the model as follows:

Mdl = arima('AR',{0.8,-0.2},'Variance',0.2,'Constant',0)

Mdl = arima with properties: Description: "ARIMA(2,0,0) Model (Gaussian Distribution)" SeriesName: "Y" Distribution: Name = "Gaussian" P: 2 D: 0 Q: 0 Constant: 0 AR: {0.8 -0.2} at lags [1 2] SAR: {} MA: {} SMA: {} Seasonality: 0 Beta: [1×0] Variance: 0.2

The output displays the value of the created model, `Mdl`

. Notice that the property `Seasonality`

is not in the output. `Seasonality`

only displays for models with seasonal integration. The property is still present, however, as seen in the Variable Editor.

`Mdl`

has values for every `arima`

property, even though the specification included only three. `arima`

assigns default values for the unspecified properties. The values of `SAR`

, `MA`

, and `SMA`

are empty cell arrays because the model has no seasonal or MA terms. The values of `D`

and `Seasonality`

are `0`

because there is no nonseasonal or seasonal differencing. `arima`

sets:

`P`

equal to`2`

, the number of presample observations needed to initialize an AR(2) model.`Q`

equal to`0`

because there is no MA component to the model (i.e., no presample innovations are needed).

#### Specify a GARCH(1,1) Model

As another illustration, consider specifying the GARCH(1,1) model

$${y}_{t}={\epsilon}_{t},$$

where

$$\begin{array}{rcl}{\epsilon}_{t}& =& {\sigma}_{t}{z}_{t}\\ {\sigma}_{t}^{2}& =& \kappa +{\gamma}_{1}{\sigma}_{t-1}^{2}+{\alpha}_{1}{\epsilon}_{t-1}^{2}\end{array}$$

Assume $${z}_{t}$$ follows a standard normal distribution.

This model has one GARCH coefficient (corresponding to the lagged variance term) and one ARCH coefficient (corresponding to the lagged squared innovation term), both with unknown values. To specify this model, enter:

Mdl = garch('GARCH',NaN,'ARCH',NaN)

Mdl = garch with properties: Description: "GARCH(1,1) Conditional Variance Model (Gaussian Distribution)" SeriesName: "Y" Distribution: Name = "Gaussian" P: 1 Q: 1 Constant: NaN GARCH: {NaN} at lag [1] ARCH: {NaN} at lag [1] Offset: 0

The default value for the constant term is also `NaN`

. Parameters with `NaN`

values need to be estimated or otherwise specified before you can forecast or simulate the model. There is also a shorthand syntax to create a default GARCH(1,1) model:

Mdl = garch(1,1)

Mdl = garch with properties: Description: "GARCH(1,1) Conditional Variance Model (Gaussian Distribution)" SeriesName: "Y" Distribution: Name = "Gaussian" P: 1 Q: 1 Constant: NaN GARCH: {NaN} at lag [1] ARCH: {NaN} at lag [1] Offset: 0

The shorthand syntax returns a GARCH model with one GARCH coefficient and one ARCH coefficient, with default `NaN`

values.

### Retrieve Model Properties

The property values in an existing model are retrievable. Working with models resembles working with `struct`

arrays because you can access model properties using dot notation. That is, type the model name, then the property name, separated by `'.'`

(a period).

For example, consider the `arima`

model with this AR(2) specification:

Mdl = arima('AR',{0.8,-0.2},'Variance',0.2,'Constant',0);

To display the value of the property `AR`

for the created model, enter:

arCoefficients = Mdl.AR

`arCoefficients=`*1×2 cell array*
{[0.8000]} {[-0.2000]}

`AR`

is a cell array, so you must use cell-array syntax. The coefficient cell arrays are lag-indexed, so entering

secondARCoefficient = Mdl.AR{2}

secondARCoefficient = -0.2000

returns the coefficient at lag 2. You can also assign any property value to a new variable:

ar = Mdl.AR

`ar=`*1×2 cell array*
{[0.8000]} {[-0.2000]}

### Modify Model Properties

You can also modify model properties using dot notation. For example, consider this AR(2) specification:

Mdl = arima('AR',{0.8,-0.2},'Variance',0.2,'Constant',0)

Mdl = arima with properties: Description: "ARIMA(2,0,0) Model (Gaussian Distribution)" SeriesName: "Y" Distribution: Name = "Gaussian" P: 2 D: 0 Q: 0 Constant: 0 AR: {0.8 -0.2} at lags [1 2] SAR: {} MA: {} SMA: {} Seasonality: 0 Beta: [1×0] Variance: 0.2

The created model has the default Gaussian innovation distribution. Change the innovation distribution to a Student's *t* distribution with eight degrees of freedom. The data type for `Distribution`

is a `struct`

array.

Mdl.Distribution = struct('Name','t','DoF',8)

Mdl = arima with properties: Description: "ARIMA(2,0,0) Model (t Distribution)" SeriesName: "Y" Distribution: Name = "t", DoF = 8 P: 2 D: 0 Q: 0 Constant: 0 AR: {0.8 -0.2} at lags [1 2] SAR: {} MA: {} SMA: {} Seasonality: 0 Beta: [1×0] Variance: 0.2

The variable `Mdl`

is updated accordingly.

### Object Functions

Object functions are functions that accept model objects as inputs and perform an operation on the model and other inputs. In Econometrics Toolbox, these functions, which represent steps in an econometrics analysis workflow, accept most objects included in the toolbox:

`estimate`

`forecast`

`simulate`

Models that you can fit to data have these three methods in common, but the model objects in the toolbox can have other object functions.

Object functions can distinguish between model objects (e.g., an
`arima`

model vs. a `garch`

model). That is,
some object functions accept different optional inputs and return different outputs
depending on the type of model that is input.

Find object function reference pages for a specific model by entering, for
example, `doc arima/estimate`

.