tsVAR

Create threshold-switching dynamic regression model

Description

The `tsVAR` function returns a `tsVAR` object that specifies the functional form of a threshold-switching dynamic regression model for the univariate or multivariate response process yt. The `tsVAR` object also stores the parameter values of the model.

A `tsVAR` object has two key components:

The components completely specify the model structure. The threshold transition levels, smooth transition function rates, and submodel parameters, such as the AR coefficients and innovation-distribution variance, are unknown and estimable unless you specify their values.

To estimate a model containing unknown parameter values, pass the model and data to `estimate`. To work with an estimated or fully specified `tsVAR` object, pass it to an object function.

Alternatively, to create a Markov-switching dynamic regression model, which has a switching mechanism governed by a discrete-time Markov chain, see `dtmc` and `msVAR`.

Creation

Syntax

``Mdl = tsVAR(tt,mdl)``
``Mdl = tsVAR(tt,mdl,Name,Value)``

Description

example

````Mdl = tsVAR(tt,mdl)` creates a threshold-switching dynamic regression model `Mdl` (a `tsVAR` object) that has the threshold transitions switching mechanism among states `tt` and the state-specific, stable dynamic regression submodels `mdl`.```

example

````Mdl = tsVAR(tt,mdl,Name,Value)` sets some properties using name-value argument syntax. For example, ```tsVAR(tt,mdl,Covariance=Sigma,SeriesNames=["GDP" "CPI"])``` generates all innovations from the covariance matrix `Sigma` and labels the submodel response series `"GDP"` and `"CPI"`, respectively.```

Input Arguments

expand all

Threshold transitions, with `NumStates` states, specified as a `threshold` object.

The states represented in `tt.StateNames` correspond to the states represented in the submodel vector `mdl`.

`tsVAR` stores `tt` in the Switch property.

State-specific dynamic regression submodels, specified as a length `mc.NumStates` vector of model objects individually constructed by `arima` or `varm`. All submodels must be of the same type (`arima` or `varm`) and have the same number of series.

Unlike other model estimation tools, `estimate` does not infer the size of submodel regression coefficient arrays during estimation. Therefore, you must specify the `Beta` property of each submodel appropriately. For example, to include and estimate three predictors of the regression component of univariate submodel `j`, set `mdl(j).Beta = NaN(3,1)`.

`tsVAR` processes and stores `mdl` in the property Submodels.

Properties

expand all

You can set the `Covariance` and `SeriesNames` properties when you create a model by using name-value argument syntax. MATLAB® derives the values of all other properties from inputs `tt` and `mdl`. You can modify only `SeriesNames` by using dot notation.

For example, create a threshold-switching model for a 2-D response series in which all submodels share the same unknown covariance matrix, and then label the first and second series `"GDP"` and `"CPI"`, respectively.

```Mdl = tsVAR(tt,mdl,Covariance=nan(2,2)); Mdl.SeriesNames = ["GDP" "CPI"];```

Threshold transitions for the switching mechanism among states, specified as a `threshold` object.

State-specific vector autoregression submodels, specified as a vector of `varm` objects of length `NumStates`.

`tsVAR` removes unsupported submodel components.

• For `arima` submodels, `tsVAR` does not support the moving average (MA), differencing, and seasonal components. If any submodel is a composite conditional mean and variance model (for example, its `Variance` property is a `garch` object), `tsVAR` issues an error.

• For `varm` submodels, `tsVAR` does not support the trend component.

`tsVAR` converts submodels specified as `arima` objects to 1-D `varm` objects.

Number of states, specified as a positive scalar.

Data Types: `double`

Number of time series, specified as a positive integer. `NumSeries` specifies the dimensionality of the response variable and innovation in all submodels.

Data Types: `double`

State labels, specified as a string vector of length `NumStates`.

Data Types: `string`

Unique series labels, specified as a string vector, cell array of character vectors, or a numeric vector of length `numSeries`. `tsVAR` stores the series names as a string vector.

Data Types: `string`

Model-wide innovations covariance, specified as a positive numeric scalar for univariate models or a `numSeries`-by-`numSeries` positive semidefinite matrix for multivariate models.

If `Covariance` is not an empty array (`[]`), object functions of `tsVAR` generate all innovations from `Covariance` and ignore submodel covariances.

If `Covariance` is `[]` (the default), object functions of `tsVAR` generate innovations from submodel covariances.

`estimate` does not support equality constraints on the innovations covariance. `estimate` ignores specified entries in `Covariance` or in submodel innovations covariances, and estimates all covariances instead.

Data Types: `double`

Notes

• `NaN`-valued elements in either the properties of `Switch` or the submodels of `Submodels` indicate unknown, estimable parameters. Specified elements, except submodel innovation variances, indicate equality constraints on parameters in model estimation.

• All unknown submodel parameters are state dependent.

Object Functions

 `estimate` Fit threshold-switching dynamic regression model to data `forecast` Forecast sample paths from threshold-switching dynamic regression model `simulate` Simulate sample paths of threshold-switching dynamic regression model `summarize` Summarize threshold-switching dynamic regression model estimation results

Examples

collapse all

Create a two-state TAR model for a 1-D response process. Specify all parameter values (this example uses arbitrary values).

Create Switching Mechanism

Create a discrete threshold transition at level 0. Label the regimes to reflect the state of the economy:

• When the threshold variable (currently unknown) is in $\left(-\infty ,0\right)$, the economy is in a recession.

• When the threshold variable is in $\left[0,\infty \right)$, the economy is expanding.

```t = 0; tt = threshold(t,StateNames=["Recession" "Expansion"])```
```tt = threshold with properties: Type: 'discrete' Levels: 0 Rates: [] StateNames: ["Recession" "Expansion"] NumStates: 2 ```

`tt` is a fully specified `threshold` object that describes the switching mechanism of the threshold-switching model.

Create State-Specific Models for Response Series

Assume the following univariate models describe the response process of the system:

• `Recession`: ${\mathit{y}}_{\mathit{t}}=-1+{0.1{\mathit{y}}_{\mathit{t}-1}+\epsilon }_{1,\mathit{t}},$ where ${\epsilon }_{1,\mathit{t}}\sim Ν\left(0,1\right)$.

• `Expansion`: ${\mathit{y}}_{\mathit{t}}={-1+0.3{\mathit{y}}_{\mathit{t}-1}+0.2{\mathit{y}}_{\mathit{t}-2}+\epsilon }_{2,\mathit{t}},$ where ${\epsilon }_{2,\mathit{t}}\sim Ν\left(0,4\right)$.

For each regime, use `arima` to create an AR model that describes the response process within the regime.

```c1 = -1; c2 = 1; ar1 = 0.1; ar2 = [0.3 0.2]; v1 = 1; v2 = 4; mdl1 = arima(Constant=c1,AR=ar1,Variance=v1, ... Description="Recession State Model")```
```mdl1 = arima with properties: Description: "Recession State Model" Distribution: Name = "Gaussian" P: 1 D: 0 Q: 0 Constant: -1 AR: {0.1} at lag [1] SAR: {} MA: {} SMA: {} Seasonality: 0 Beta: [1×0] Variance: 1 ARIMA(1,0,0) Model (Gaussian Distribution) ```
```mdl2 = arima(Constant=c2,AR=ar2,Variance=v2, ... Description="Expansion State Model")```
```mdl2 = arima with properties: Description: "Expansion State Model" Distribution: Name = "Gaussian" P: 2 D: 0 Q: 0 Constant: 1 AR: {0.3 0.2} at lags [1 2] SAR: {} MA: {} SMA: {} Seasonality: 0 Beta: [1×0] Variance: 4 ARIMA(2,0,0) Model (Gaussian Distribution) ```

`mdl1` and `mdl2` are fully specified `arima` objects.

Store the submodels in a vector with order corresponding to the regimes in `tt.StateNames`.

`mdl = [mdl1; mdl2];`

Create Threshold-Switching Model

Use `tsVAR` to create a TAR model from the switching mechanism `tt` and the state-specific submodels `mdl`.

`Mdl = tsVAR(tt,mdl)`
```Mdl = tsVAR with properties: Switch: [1x1 threshold] Submodels: [2x1 varm] NumStates: 2 NumSeries: 1 StateNames: ["Recession" "Expansion"] SeriesNames: "1" Covariance: [] ```
`Mdl.Submodels(2)`
```ans = varm with properties: Description: "AR-Stationary 1-Dimensional VAR(2) Model" SeriesNames: "Y1" NumSeries: 1 P: 2 Constant: 1 AR: {0.3 0.2} at lags [1 2] Trend: 0 Beta: [1×0 matrix] Covariance: 4 ```

`Mdl` is a fully specified `tsVAR` object representing a univariate two-state TAR model. `tsVAR` stores specified `arima` submodels as `varm` objects.

Because `Mdl` is fully specified, you can pass it to any `tsVAR` object function for further analysis (see Object Functions). Alternatively, you can specify the threshold model parameters in `Mdl.Switch` as initial values for the estimation procedure (see `estimate`).

Create a three-state STAR model with logistic transitions (LSTAR) for a 1-D response process. Specify all parameter values (this example uses arbitrary values).

Create smooth, logistic threshold transitions at levels `2` and `8`. Specify the following transition rates:

• `3.5`, when the system transitions from state 1 to state 2.

• `1.5`, when the system transitions from state 2 to state 3.

```t = [2 8]; r = [3.5 1.5]; tt = threshold(t,Type="logistic",Rates=r)```
```tt = threshold with properties: Type: 'logistic' Levels: [2 8] Rates: [3.5000 1.5000] StateNames: ["1" "2" "3"] NumStates: 3 ```

`tt` is a fully specified `threshold` object.

Assume the following univariate models describe the response process of the system:

• State 1: ${\mathit{y}}_{\mathit{t}}=-5+{\epsilon }_{1},$ where ${\epsilon }_{1}\sim Ν\left(0,0.{1}^{2}\right)$.

• State 2: ${\mathit{y}}_{\mathit{t}}={\epsilon }_{2},$ where ${\epsilon }_{2}\sim Ν\left(0,0.{2}^{2}\right)$.

• State 3: ${\mathit{y}}_{\mathit{t}}=5+{\epsilon }_{3},$ where ${\epsilon }_{3}\sim Ν\left(0,0.{3}^{2}\right)$.

```mdl1 = arima(Constant=-5,Variance=0.1); mdl2 = arima(Constant=0,Variance=0.2); mdl3 = arima(Constant=5,Variance=0.3); mdl = [mdl1,mdl2,mdl3];```

Create a STAR model from the switching mechanism `tt` and the state-specific submodels `mdl`.

`Mdl = tsVAR(tt,mdl)`
```Mdl = tsVAR with properties: Switch: [1x1 threshold] Submodels: [3x1 varm] NumStates: 3 NumSeries: 1 StateNames: ["1" "2" "3"] SeriesNames: "1" Covariance: [] ```

Mdl is a fully specified `tsVAR` object representing the STAR model.

Consider fitting to data a two-state exponential STAR model for a 1-D response process. Assume all parameters are unknown (includes transition mid-level $\mathit{t}$, rate $\mathit{r}$, and all dynamic model coefficients and variances $\theta$).

Create an exponential threshold transition. Specify unknown elements using `NaN`.

`tt = threshold(NaN,Type="exponential",Rates=NaN)`
```tt = threshold with properties: Type: 'exponential' Levels: NaN Rates: NaN StateNames: ["1" "2"] NumStates: 2 ```

`tt` is a partially specified `threshold` object. The mid-level `tt.Levels` and transition rate `tt.Rates` are unknown and estimable.

Create AR(1) and AR(2) models by using the shorthand syntax of `arima`.

```mdl1 = arima(1,0,0); mdl2 = arima(2,0,0);```

`mdl1` and `mdl2` are partially specified `arima` objects. `NaN`-valued properties correspond to unknown, estimable parameters.

Store the submodels in a vector.

`mdl = [mdl1; mdl2];`

Create a STAR model template from the switching mechanism `tt` and the state-specific submodels `mdl`.

`Mdl = tsVAR(tt,mdl)`
```Mdl = tsVAR with properties: Switch: [1x1 threshold] Submodels: [2x1 varm] NumStates: 2 NumSeries: 1 StateNames: ["1" "2"] SeriesNames: "1" Covariance: [] ```

`Mdl` is a partially specified `tsVAR` object representing a univariate two-state STAR model.

`Mdl.Submodels(1)`
```ans = varm with properties: Description: "1-Dimensional VAR(1) Model" SeriesNames: "Y1" NumSeries: 1 P: 1 Constant: NaN AR: {NaN} at lag [1] Trend: 0 Beta: [1×0 matrix] Covariance: NaN ```
`Mdl.Submodels(2)`
```ans = varm with properties: Description: "1-Dimensional VAR(2) Model" SeriesNames: "Y1" NumSeries: 1 P: 2 Constant: NaN AR: {NaN NaN} at lags [1 2] Trend: 0 Beta: [1×0 matrix] Covariance: NaN ```

`tsVAR` converts the `arima` object submodels to 1-D `varm` object equivalents.

`Mdl` is prepared for estimation. You can pass `Mdl` to `estimate`, along with data and a fully specified threshold transition (`threshold` object) containing initial values for optimization.

Create the following two, three-state threshold-switching dynamic regression models for a 2-D response process:

1. A model with state-specific innovations distributions

2. A model with a model-wide innovation covariance

Specify all parameter values (this example uses arbitrary values).

Create Threshold Transitions

Create logistic threshold transitions at mid-levels `2` and `8` with rates `3.5` and `1.5`, respectively. Label the corresponding states `"Low"`, `"Med"`, and `"High"`.

```t = [2 8]; r = [3.5 1.5]; stateNames = ["Low" "Med" "High"]; tt = threshold(t,Type="logistic",Rates=[3.5 1.5],StateNames=stateNames)```
```tt = threshold with properties: Type: 'logistic' Levels: [2 8] Rates: [3.5000 1.5000] StateNames: ["Low" "Med" "High"] NumStates: 3 ```

`tt` is a fully specified `threshold` object.

Specify State-Specific Innovations Covariance Matrices

Assume the following VAR models describe the response processes of the system:

• State 1: ${y}_{t}=\left[\begin{array}{c}1\\ -1\end{array}\right]+{\epsilon }_{1,t},$ where ${\epsilon }_{1,t}\sim N\left(\left[\begin{array}{c}0\\ 0\end{array}\right],\left[\begin{array}{cc}1& -0.1\\ -0.1& 1\end{array}\right]\right).$

• State 2: ${y}_{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]{y}_{t-1}+{\epsilon }_{2,t},$ where ${\epsilon }_{2,t}\sim N\left(\left[\begin{array}{c}0\\ 0\end{array}\right],\left[\begin{array}{cc}2& -0.2\\ -0.2& 2\end{array}\right]\right).$

• State 3: ${y}_{t}=\left[\begin{array}{c}3\\ -3\end{array}\right]+\left[\begin{array}{cc}0.25& 0\\ 0& 0\end{array}\right]{y}_{t-1}+\left[\begin{array}{cc}0& 0\\ 0.25& 0\end{array}\right]{y}_{t-2}+{\epsilon }_{3,t},$ where ${\epsilon }_{3,t}\sim N\left(\left[\begin{array}{c}0\\ 0\end{array}\right],\left[\begin{array}{cc}3& -0.3\\ -0.3& 3\end{array}\right]\right).$

```% 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 % 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]; % VAR Submodels mdl1 = varm('Constant',C1,'AR',AR1,'Covariance',Sigma1); mdl2 = varm('Constant',C2,'AR',AR2,'Covariance',Sigma2); mdl3 = varm('Constant',C3,'AR',AR3,'Covariance',Sigma3);```

`mdl1`, `mdl2`, and `mdl3` are fully specified `varm` objects.

Store the submodels in a vector with order corresponding to the regimes in `tt.StateNames`.

`mdl = [mdl1; mdl2; mdl3];`

Create an LSTAR model from the switching mechanism `tt` and the state-specific submodels `mdl`. Label the series `Y1` and `Y2`.

`Mdl = tsVAR(tt,mdl,SeriesNames=["Y1" "Y2"])`
```Mdl = tsVAR with properties: Switch: [1x1 threshold] Submodels: [3x1 varm] NumStates: 3 NumSeries: 2 StateNames: ["Low" "Med" "High"] SeriesNames: ["Y1" "Y2"] Covariance: [] ```

`Mdl` is a fully specified `tsVAR` object representing a multivariate three-state LSTAR model. Because the `Covariance` property is empty (`[]`), the submodels have their own innovations covariance matrix.

Specify Model-Wide Innovations Covariance Matrix

Suppose that the innovations covariance matrix is invariant across states and has value $\left[\begin{array}{cc}2& -0.2\\ -0.2& 2\end{array}\right]$.

Create an LSTAR model like `Mdl` that has the model-wide innovations covariance matrix.

`MdlCov = tsVAR(tt,mdl,SeriesNames=["Y1" "Y2"],Covariance=Sigma2)`
```MdlCov = tsVAR with properties: Switch: [1x1 threshold] Submodels: [3x1 varm] NumStates: 3 NumSeries: 2 StateNames: ["Low" "Med" "High"] SeriesNames: ["Y1" "Y2"] Covariance: [2x2 double] ```
`MdlCov.Covariance`
```ans = 2×2 2.0000 -0.2000 -0.2000 2.0000 ```

The `Covariance` property of `MdlCov` is nonempty, which means the innovations distribution of all submodels are equal.

Consider including regression components for exogenous variables in each submodel of the threshold-switching dynamic regression model in Create Fully Specified Multivariate Model.

Create logistic threshold transitions at mid-levels `2` and `8` with rates `3.5` and `1.5`, respectively. Label the corresponding states `"Low"`, `"Med"`, and `"High"`.

```t = [2 8]; r = [3.5 1.5]; stateNames = ["Low" "Med" "High"]; tt = threshold(t,Type="logistic",Rates=[3.5 1.5],StateNames=stateNames)```
```tt = threshold with properties: Type: 'logistic' Levels: [2 8] Rates: [3.5000 1.5000] StateNames: ["Low" "Med" "High"] NumStates: 3 ```

Assume the following VARX models describe the response processes of the system:

• State 1: ${y}_{t}=\left[\begin{array}{c}1\\ -1\end{array}\right]+\left[\begin{array}{c}1\\ -1\end{array}\right]{x}_{1,t}+{\epsilon }_{1,t},$ where ${\epsilon }_{1,t}\sim N\left(\left[\begin{array}{c}0\\ 0\end{array}\right],\left[\begin{array}{cc}1& -0.1\\ -0.1& 1\end{array}\right]\right).$

• State 2: ${y}_{t}=\left[\begin{array}{c}2\\ -2\end{array}\right]+\left[\begin{array}{cc}2& 2\\ -2& -2\end{array}\right]{x}_{2,t}+\left[\begin{array}{cc}0.5& 0.1\\ 0.5& 0.5\end{array}\right]{y}_{t-1}+{\epsilon }_{2,t},$ where ${\epsilon }_{2,t}\sim N\left(\left[\begin{array}{c}0\\ 0\end{array}\right],\left[\begin{array}{cc}2& -0.2\\ -0.2& 2\end{array}\right]\right).$

• State 3: ${y}_{t}=\left[\begin{array}{c}3\\ -3\end{array}\right]+\left[\begin{array}{ccc}3& 3& 3\\ -3& -3& -3\end{array}\right]{x}_{3,t}+\left[\begin{array}{cc}0.25& 0\\ 0& 0\end{array}\right]{y}_{t-1}+\left[\begin{array}{cc}0& 0\\ 0.25& 0\end{array}\right]{y}_{t-2}+{\epsilon }_{3,t},$ where ${\epsilon }_{3,t}\sim N\left(\left[\begin{array}{c}0\\ 0\end{array}\right],\left[\begin{array}{cc}3& -0.3\\ -0.3& 3\end{array}\right]\right).$

${\mathit{x}}_{1,\mathit{t}}$ represents a single exogenous variable, ${\mathit{x}}_{2,\mathit{t}}$ represents two exogenous variables, and ${\mathit{x}}_{3,\mathit{t}}$ represents three exogenous variables. Store the submodels in a vector.

```% Constants (numSeries x 1 vectors) C1 = [1; -1]; C2 = [2; -2]; C3 = [3; -3]; % 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 % Autoregression coefficients (numSeries x numSeries matrices) AR1 = {}; AR2 = {[0.5 0.1; 0.5 0.5]}; AR3 = {[0.25 0; 0 0] [0 0; 0.25 0]}; % 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]; % VARX 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); mdl = [mdl1; mdl2; mdl3];```

Create an LSTAR model from the switching mechanism `tt` and the state-specific submodels `mdl`. Label the series `Y1` and `Y2`.

`Mdl = tsVAR(tt,mdl,SeriesNames=["Y1" "Y2"])`
```Mdl = tsVAR with properties: Switch: [1x1 threshold] Submodels: [3x1 varm] NumStates: 3 NumSeries: 2 StateNames: ["Low" "Med" "High"] SeriesNames: ["Y1" "Y2"] Covariance: [] ```
`Mdl.Submodels(1)`
```ans = varm with properties: Description: "2-Dimensional VARX(0) Model with 1 Predictor" SeriesNames: "Y1" "Y2" NumSeries: 2 P: 0 Constant: [1 -1]' AR: {} Trend: [2×1 vector of zeros] Beta: [2×1 matrix] Covariance: [2×2 matrix] ```
`Mdl.Submodels(2)`
```ans = varm with properties: Description: "AR-Stationary 2-Dimensional VARX(1) Model with 2 Predictors" SeriesNames: "Y1" "Y2" NumSeries: 2 P: 1 Constant: [2 -2]' AR: {2×2 matrix} at lag [1] Trend: [2×1 vector of zeros] Beta: [2×2 matrix] Covariance: [2×2 matrix] ```
`Mdl.Submodels(3)`
```ans = varm with properties: Description: "AR-Stationary 2-Dimensional VARX(2) Model with 3 Predictors" SeriesNames: "Y1" "Y2" NumSeries: 2 P: 2 Constant: [3 -3]' AR: {2×2 matrices} at lags [1 2] Trend: [2×1 vector of zeros] Beta: [2×3 matrix] Covariance: [2×2 matrix] ```

Consider fitting to data a three-state TAR model for a 2-D response process. Assume all parameters are unknown (including the transition two mid-levels $\mathit{t}$ and all dynamic model coefficients and variances $\theta$).

Create discrete threshold transitions at two unknown levels. This specification imples a three-state model.

```t = [NaN NaN]; tt = threshold(t);```

`tt` is a partially specified `threshold` object. The transition mid-levels `tt.Levels` are completely unknown and estimable.

Create 2-D VAR(0), VAR(1), and VAR(2) models by using the shorthand syntax of `varm`. Store the models in a vector.

```mdl1 = varm(2,0); mdl2 = varm(2,1); mdl3 = varm(2,2); mdl = [mdl1 mdl2 mdl3]; mdl(2)```
```ans = varm with properties: Description: "2-Dimensional VAR(1) Model" SeriesNames: "Y1" "Y2" NumSeries: 2 P: 1 Constant: [2×1 vector of NaNs] AR: {2×2 matrix of NaNs} at lag [1] Trend: [2×1 vector of zeros] Beta: [2×0 matrix] Covariance: [2×2 matrix of NaNs] ```

`mdl` contains three state-specific `varm` model templates for estimation. `NaN` values in the properties indicate estimable parameters.

Create a threshold-switching model template from the switching mechanism `tt` and the state-specific submodels `mdl`.

`Mdl = tsVAR(tt,mdl)`
```Mdl = tsVAR with properties: Switch: [1x1 threshold] Submodels: [3x1 varm] NumStates: 3 NumSeries: 2 StateNames: ["1" "2" "3"] SeriesNames: ["1" "2"] Covariance: [] ```
`Mdl.Submodels(2)`
```ans = varm with properties: Description: "2-Dimensional VAR(1) Model" SeriesNames: "Y1" "Y2" NumSeries: 2 P: 1 Constant: [2×1 vector of NaNs] AR: {2×2 matrix of NaNs} at lag [1] Trend: [2×1 vector of zeros] Beta: [2×0 matrix] Covariance: [2×2 matrix of NaNs] ```

`Mdl` is a partially specified `tsVAR` model for estimation.

Consider estimating all submodel coefficients and innovations covariances, and the threshold levels, of the TAR model in Create Fully Specified Model Containing Regression Component.

Create logistic threshold transitions at two unknown (`NaN`) mid-levels and with two unknown rates. Label the corresponding states `"Low"`, `"Med"`, and `"High"`.

```stateNames = ["Low" "Med" "High"]; tt = threshold([NaN NaN],Type="logistic",Rates=[NaN NaN],StateNames=stateNames)```
```tt = threshold with properties: Type: 'logistic' Levels: [NaN NaN] Rates: [NaN NaN] StateNames: ["Low" "Med" "High"] NumStates: 3 ```

Specify the appropriate 2-D VAR model for each state by using thee shorthand syntax of `varm`, then use dot notation to specify a `numSeries`-by-`numRegressors` unknown, estimable exogenous regression coefficient matrix.

• State 1: VARX(0) mode1 with one regressor

• State 2: VARX(1) model with two regressors

• State 3: VARX(2) model with three regressors

Store the submodels in a vector.

```mdl1 = varm(2,0); mdl1.Beta = nan(2,1); % numSeries-by-numRegressors mdl2 = varm(2,1); mdl2.Beta = nan(2,2); mdl3 = varm(2,2); mdl3.Beta = nan(2,3); mdl = [mdl1; mdl2; mdl3];```

Create an estimable LSTAR model from the switching mechanism `tt` and the state-specific submodels `mdl`. Label the series `Y1` and `Y2`.

`Mdl = tsVAR(tt,mdl,SeriesNames=["Y1" "Y2"])`
```Mdl = tsVAR with properties: Switch: [1x1 threshold] Submodels: [3x1 varm] NumStates: 3 NumSeries: 2 StateNames: ["Low" "Med" "High"] SeriesNames: ["Y1" "Y2"] Covariance: [] ```
`Mdl.Submodels(2)`
```ans = varm with properties: Description: "2-Dimensional VARX(1) Model with 2 Predictors" SeriesNames: "Y1" "Y2" NumSeries: 2 P: 1 Constant: [2×1 vector of NaNs] AR: {2×2 matrix of NaNs} at lag [1] Trend: [2×1 vector of zeros] Beta: [2×2 matrix of NaNs] Covariance: [2×2 matrix of NaNs] ```

The `estimate` function generally supports constraints on any parameter to a known constant. Also, you can specify a model-wide innovations covariance by setting the `Covariance` property of `tsVAR`.

Consider estimating a univariate threshold-switching model with the following characteristics:

• A threshold transition is known to occur at 0.

• The transition function is the normal cdf with unknown rate.

• States 1 and 2 are constant models. The constants are unknown.

• The innovations process is invariant among states, but the variance is unknown.

Create the described threshold transition.

```t = 0; tt = threshold(t,Type="normal",Rates=NaN)```
```tt = threshold with properties: Type: 'normal' Levels: 0 Rates: NaN StateNames: ["1" "2"] NumStates: 2 ```

`tt` is a partially specified `threshold` object. Only the transition function rate `tt.Rates` is unknown and estimable.

Create the described submodels by using the shorthand syntax of `arima`. Store the submodels in a vector.

```mdl1 = arima(0,0,0); mdl2 = arima(0,0,0)```
```mdl2 = arima with properties: Description: "ARIMA(0,0,0) Model (Gaussian Distribution)" Distribution: Name = "Gaussian" P: 0 D: 0 Q: 0 Constant: NaN AR: {} SAR: {} MA: {} SMA: {} Seasonality: 0 Beta: [1×0] Variance: NaN ```
`mdl = [mdl1 mdl2];`

`mdl1` and `mdl2` are partially specified `arima` objects representing constant-only linear models. Each model constant is unknown and estimable.

Create a threshold-switching model from the specified threshold transitions and submodels. Specify and unknown, estimable model-wide innovations covariance matrix.

`Mdl = tsVAR(tt,mdl,Covariance=NaN)`
```Mdl = tsVAR with properties: Switch: [1x1 threshold] Submodels: [2x1 varm] NumStates: 2 NumSeries: 1 StateNames: ["1" "2"] SeriesNames: "1" Covariance: NaN ```

`Mdl` is a partially specified tsVAR object configured for estimation. Because Mdl.Covariance is nonempty, MATLAB ignores any specified submodel innovations variances.

expand all

Algorithms

A threshold variable zt, which triggers transitions between states, is not required to create `Mdl`. Specify exogenous or endogenous threshold variable data, and its characteristics, when you pass `Mdl` to an object function.

References

[1] Enders, Walter. Applied Econometric Time Series. New York: John Wiley & Sons, Inc., 2009.

[2] Teräsvirta, Tima. "Modelling Economic Relationships with Smooth Transition Regressions." In A. Ullahand and D.E.A. Giles (eds.), Handbook of Applied Economic Statistics, 507–552. New York: Marcel Dekker, 1998.

[3] van Dijk, Dick. Smooth Transition Models: Extensions and Outlier Robust Inference. Rotterdam, Netherlands: Tinbergen Institute Research Series, 1999.

Version History

Introduced in R2021b