# Create Threshold-Switching Dynamic Regression Models

This example shows how to create fully and partially specified threshold-switching dynamic regression models by using `tsVAR`.

The main components of a threshold-switching model are:

• A threshold transition object (`threshold`), which specifies the states and the switching mechanism among them.

• A vector of submodels, which describe the response in each state. Each submodel can be a univariate ARX (`arima`) or a multivariate VARX (`varm`) model; all submodels must contain the same response series.

### Create Fully Specified Univariate Model

A model is fully specified when all its parameters are set to known values. A model must be fully specified to, for example, simulate or forecast responses from it. The `tsVAR` function enables you to specify all parameter values, and the `estimate` function always returns a fully specified model.

Create and fully specify a simple univariate, three-state, mean-variance-switching smooth threshold autoregressive (STAR) model with the following characteristics:

• The threshold transitions are at mid-levels 2 and 8, the transition function is logistic, and the transition rate from state 1 to 2 is 3.5, and the rate from state 2 to 3 is 1.5.

• The state 1 submodel is ${\mathit{y}}_{1,\mathit{t}}=-5+{\epsilon }_{1,\mathit{t}}$, where ${\epsilon }_{1,\mathit{t}}\sim Ν\left(0,0.1\right)$.

• The state 2 submodel is ${\mathit{y}}_{2,\mathit{t}}={\epsilon }_{2,\mathit{t}}$, where ${\epsilon }_{2,\mathit{t}}\sim Ν\left(0,0.3\right)$.

• The state 3 submodel is ${\mathit{y}}_{3,\mathit{t}}=5+{\epsilon }_{3,\mathit{t}}$, where ${\epsilon }_{3,\mathit{t}}\sim Ν\left(0,0.5\right)$.

```ttLPS = threshold([2 8],Type="logistic",Rates=[3.5 1.5]); mdl1 = arima(Constant=-5,Variance=0.1); mdl2 = arima(Constant=0,Variance=0.3); mdl3 = arima(Constant=5,Variance=0.5); Mdl1 = tsVAR(ttLPS,[mdl1 mdl2 mdl3],SeriesNames="y")```
```Mdl1 = tsVAR with properties: Switch: [1x1 threshold] Submodels: [3x1 varm] NumStates: 3 NumSeries: 1 StateNames: ["1" "2" "3"] SeriesNames: "y" Covariance: [] ```
`Mdl1.Submodels(1)`
```ans = varm with properties: Description: "1-Dimensional VAR(0) Model" SeriesNames: "Y1" NumSeries: 1 P: 0 Constant: -5 AR: {} Trend: 0 Beta: [1×0 matrix] Covariance: 0.1 ```

Mdl1 is a fully specified `tsVAR` model object (no properties contain `NaN` entries). `tsVAR` converts the `arima` submodels to 1-D `varm` submodels of the same form. The default covariance (`Mdl1.Covariance`) is empty, which indicates that the software generates the innovations from the submodel covariance specification (`Mdl1.Submodels.Covariance`) of the current state. When you specify a non-empty value for the `Covariance` name-value argument, a model-wide covariance generates innovations independent of the current state.

### Create Fully Specified Multivariate Model

You can create a multivariate threshold-switching model in much the same way as a univariate model.

Create a bivariate, three-state STAR model with the following characteristics:

• The threshold transitions are at mid-levels 2 and 8, the transition function is logistic, and the transition rate from state 1 to 2 is 3.5, and the rate from state 2 to 3 is 1.5.

• The state 1 submodel is ${\mathit{y}}_{1,\mathit{t}}=\left[\begin{array}{c}1\\ -1\end{array}\right]+\left[\begin{array}{c}1\\ -1\end{array}\right]{\mathit{x}}_{1,\mathit{t}}+{\epsilon }_{1,\mathit{t}}$, where ${\mathit{x}}_{1,\mathit{t}}$ is a 1-D exogenous predictor series and ${\epsilon }_{1,\mathit{t}}\sim Ν\left(\left[\begin{array}{c}0\\ 0\end{array}\right],\left[\begin{array}{cc}1& -0.1\\ -0.1& 1\end{array}\right]\right)$.

• The state 2 submodel is ${\mathit{y}}_{2,\mathit{t}}=\left[\begin{array}{c}2\\ -2\end{array}\right]+\left[\begin{array}{cc}0.5& 0.1\\ 0.5& 0.5\end{array}\right]{\mathit{y}}_{2,\mathit{t}-1}+\left[\begin{array}{cc}2& 2\\ -2& -2\end{array}\right]{\mathit{x}}_{2,\mathit{t}}+{\epsilon }_{2,\mathit{t}}$, where ${\mathit{x}}_{2,\mathit{t}}$ is a 2-D exogenous predictor series and ${\epsilon }_{2,\mathit{t}}\sim Ν\left(\left[\begin{array}{c}0\\ 0\end{array}\right],\left[\begin{array}{cc}2& -0.2\\ -0.2& 2\end{array}\right]\right)$.

• The state 3 submodel is ${\mathit{y}}_{3,\mathit{t}}=\left[\begin{array}{c}3\\ -3\end{array}\right]+\left[\begin{array}{cc}0.25& 0\\ 0& 0\end{array}\right]{\mathit{y}}_{3,\mathit{t}-1}+\left[\begin{array}{cc}0& 0\\ 0.25& 0\end{array}\right]{\mathit{y}}_{3,\mathit{t}-2}+\left[\begin{array}{ccc}3& 3& 3\\ -3& -3& -3\end{array}\right]{\mathit{x}}_{3,\mathit{t}}+{\epsilon }_{3,\mathit{t}}$, where ${\mathit{x}}_{3,\mathit{t}}$ is a 3-D exogenous predictor series and ${\epsilon }_{3,\mathit{t}}\sim Ν\left(\left[\begin{array}{c}0\\ 0\end{array}\right],\left[\begin{array}{cc}3& -0.3\\ -0.3& 3\end{array}\right]\right)$.

• States 1 through 3 have names `"Low"`, `"Med"`, and `"High"`.

```ttLPS = threshold([2 8],Type="logistic",Rates=[3.5 1.5], ... StateNames=["Low" "Med" "High"]); % Constants (numSeries x 1 vectors) C1 = [1;-1]; C2 = [2;-2]; C3 = [3;-3]; % Autoregression coefficients (numSeries x numSeries matrices) AR1 = {}; % 0 lags AR2 = {[0.5 0.1; 0.5 0.5]}; % 1 lag AR3 = {[0.25 0; 0 0], [0 0; 0.25 0]}; % 2 lags % Regression coefficients (numSeries x numRegressors matrices) Beta1 = [1;-1]; % 1 regressor Beta2 = [2 2;-2 -2]; % 2 regressors Beta3 = [3 3 3;-3 -3 -3]; % 3 regressors % Innovations covariances (numSeries x numSeries matrices) Sigma1 = [1 -0.1; -0.1 1]; Sigma2 = [2 -0.2; -0.2 2]; Sigma3 = [3 -0.3; -0.3 3]; % Submodels mdl1 = varm(Constant=C1,AR=AR1,Beta=Beta1,Covariance=Sigma1); mdl2 = varm(Constant=C2,AR=AR2,Beta=Beta2,Covariance=Sigma2); mdl3 = varm(Constant=C3,AR=AR3,Beta=Beta3,Covariance=Sigma3); Mdl2 = tsVAR(ttLPS,[mdl1 mdl2 mdl3],SeriesNames=["Y1" "Y2"])```
```Mdl2 = tsVAR with properties: Switch: [1x1 threshold] Submodels: [3x1 varm] NumStates: 3 NumSeries: 2 StateNames: ["Low" "Med" "High"] SeriesNames: ["Y1" "Y2"] Covariance: [] ```

### Create Partially Specified Model

A model is partially specified when it contains at least one unknown parameter. A partially specified model represents a model template for estimation. The model template specifies structural parameters that are not estimable (for example, the number of states, transition function type, and the number of submodel-specific lags), the unknown, estimable parameters (NaN-valued entries corresponding to threshold mid-levels, transition rates, submodel coefficients, and innovations variance), and known parameters held fixed at their values during estimation. Before you can use a partially specified model, you must fit it to data by using `estimate`. The `tsVAR` function enables you to specify mandatory structural parameter values, equality constraints on parameters, and which parameters are unknown and estimable.

Create a partially specified model with the same structure as `Mdl1`. In other words, set all estimable parameters of `Mdl1` to `NaN`. Use the short-hand syntax of `arima` to create the submodels.

```ttLPS1 = threshold([NaN NaN],Type="logistic",Rates=[NaN NaN]); mdl = arima(0,0,0); % Constant-only ARIMA model Mdl3 = tsVAR(ttLPS1,[mdl mdl mdl],SeriesNames="y"); Mdl3.Switch```
```ans = threshold with properties: Type: 'logistic' Levels: [NaN NaN] Rates: [NaN NaN] StateNames: ["1" "2" "3"] NumStates: 3 ```
`Mdl3.Submodels(1)`
```ans = varm with properties: Description: "1-Dimensional VAR(0) Model" SeriesNames: "Y1" NumSeries: 1 P: 0 Constant: NaN AR: {} Trend: 0 Beta: [1×0 matrix] Covariance: NaN ```

`Mdl3` is partially specified `tsVAR` object. `NaN` entries in `Mdl3.Switch` and `Mdl3.Submodels` correspond to estimable parameters.

`estimate` treats any specified parameters as equality constraints during estimation. Therefore, you can experiment with particular values or set values that have economic significance while `estimate` fits the others. Also, you can estimate a model-wide covariance by using the `Covariance` name-value argument.

Suppose the threshold mid-levels of `Mdl3` are 2 and 8, and all submodels have a common, unknown covariance. Create a model that has the constraints.

```ttLPS2 = threshold([2 8],Type="logistic",Rates=[NaN NaN]); Mdl4 = tsVAR(ttLPS2,[mdl mdl mdl],SeriesNames="y",Covariance=NaN)```
```Mdl4 = tsVAR with properties: Switch: [1x1 threshold] Submodels: [3x1 varm] NumStates: 3 NumSeries: 1 StateNames: ["1" "2" "3"] SeriesNames: "y" Covariance: NaN ```
`Mdl4.Switch`
```ans = threshold with properties: Type: 'logistic' Levels: [2 8] Rates: [NaN NaN] StateNames: ["1" "2" "3"] NumStates: 3 ```
`Mdl4.Submodels(1)`
```ans = varm with properties: Description: "1-Dimensional VAR(0) Model" SeriesNames: "Y1" NumSeries: 1 P: 0 Constant: NaN AR: {} Trend: 0 Beta: [1×0 matrix] Covariance: NaN ```

When you pass `Mdl4` to `estimate` with data, the function fits the transition rates, model constants, and model-wide covariance. When `Mdl4.Covariance` is nonempty, the software ignores all submodel covariance specifications.

### Threshold Variable Specification

To this point, although a specified `tsVAR` object contains information about the threshold transitions of its threshold variable, it is agnostic of the threshold variable itself. However, when you operate on a `tsVAR` object using `estimate`, `simulate`, or `forecast`, you can specify the threshold variable type, either `"endogenous"` (the default) or `"exogenous"`, by using the `Type` name-value argument.

The threshold variable of a self-exciting threshold autoregressive (SETAR) model is one of the response variables, specified by the `Index` name-value argument. The `Delay` name-value argument specifies the lag of the variable at which the software determines whether to switch states. The following pseudocode illustrates simulating a 10 observation path of a univariate SETAR model `Mdl` with a delay of 4.

```y = simulate(Mdl,10,Delay=4); ```

A model with an exogenous threshold variable additionally requires threshold variable data, which you can specify by using the `Z` name-value argument. The following pseudocode illustrates simulating a 10 observation path of a univariate TAR model `Mdl`, which uses the exogenous data in `z` to determine whether to switch states.

```y = simulate(Mdl,10,Type="exogenous",Z=z); ```