# 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
*y*_{t}. 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

### Description

sets some properties using name-value
argument syntax. For example, `Mdl`

= tsVAR(`tt`

,`mdl`

,`Name,Value`

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

`mdl`

— State-specific dynamic regression submodels

vector of `arima`

objects | vector of `varm`

objects

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

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"];

`Switch`

— Threshold transitions for switching mechanism among states

`threshold`

object

This property is read-only.

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

object.

`Submodels`

— State-specific vector autoregression submodels

vector of `varm`

objects

This property is read-only.

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.

`NumStates`

— Number of states

positive scalar

This property is read-only.

Number of states, specified as a positive scalar.

**Data Types: **`double`

`NumSeries`

— Number of time series

positive integer

This property is read-only.

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`

`StateNames`

— State labels

string vector

This property is read-only.

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

.

**Data Types: **`string`

`SeriesNames`

— Series labels

`string(1:numSeries)`

(default) | string vector | cell array of character vectors | numeric vector

Series labels, specified as a string vector, cell array of character vectors, or a numeric vector of length `numSeries`

. `tsVAR`

stores the series labels as a string vector.

**Data Types: **`string`

`Covariance`

— Model-wide innovations covariance

`[]`

(default) | positive numeric scalar | positive semidefinite matrix

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

### Create Fully Specified Univariate TAR Model

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 $[0,\infty )$, 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 {\rm N}\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 {\rm N}\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 Fully Specified Univariate STAR Model

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 {\rm N}\left(0,0.{1}^{2}\right)$.

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

State 3: ${\mathit{y}}_{\mathit{t}}=5+{\epsilon}_{3},$ where ${\epsilon}_{3}\sim {\rm N}\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.

### Create Partially Specified Univariate Model for Estimation

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 Fully Specified Multivariate Model

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

A model with state-specific innovations distributions

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.

### Create Fully Specified Model Containing Regression Component

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]

### Create Partially Specified Multivariate Model for Estimation

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.

### Specify Model Regression Component 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]

### Create Model Specifying Equality Constraints for Estimation

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.

## More About

### Threshold-Switching Dynamic Regression Model

A *Threshold-switching dynamic regression model*
of a univariate or multivariate response series *y _{t}*
is a nonlinear time series model that describes the dynamic behavior of the series in the
presence of structural breaks or regime changes. A collection of state-specific dynamic
regression submodels describes the dynamic behavior of

*y*within the regimes.

_{t}$${y}_{t}~\{\begin{array}{cc}{f}_{1}\left({y}_{t};{x}_{t},{\theta}_{1}\right)& ,{s}_{t}({z}_{t})=1\\ {f}_{2}\left({y}_{t};{x}_{t},{\theta}_{2}\right)& ,{s}_{t}({z}_{t})=2\\ \vdots & \vdots \\ {f}_{n+1}\left({y}_{t};{x}_{t},{\theta}_{n+1}\right)& ,{s}_{t}({z}_{t})=n+1\end{array},$$

where:

*n*+ 1 is the number of regimes (`NumStates`

).$${f}_{i}\left({y}_{t};{x}_{t},{\theta}_{i}\right)$$ is the regime

*i*dynamic regression model of*y*(_{t}`Submodels`

(*i*)). Submodels are either univariate (ARX) or multivariate (VARX). Such a collection of models yields a*threshold autoregressive model*(TAR).*z*is the univariate threshold variable._{t}*z*can be exogenous to the system or endogenous and delayed. If $${z}_{t}={y}_{k,t-d},$$ the system is a_{t}*self-exciting threshold autoregressive model*(SETAR) with unobserved delay*d*.*x*is a vector of observed exogenous variables at time_{t}*t*.*θ*is the regime_{i}*i*collection of parameters of the dynamic regression model, such as AR coefficients and the innovation variances.

The switching mechanism (`Switch`

) is governed by threshold
transitions and *z _{t}*. The state index variable

*s*(

_{t}*z*) is not random—observed values of the threshold variable

_{t}*z*determine the state of the system:

_{t}$${s}_{t}=\{\begin{array}{ll}1\hfill & ,{z}_{t}<{t}_{1}\hfill \\ 2\hfill & ,{t}_{1}\le {z}_{t}<{t}_{2}\hfill \\ \vdots \hfill & \vdots \hfill \\ n+1\hfill & ,{z}_{t}\ge {t}_{n}\hfill \end{array},$$

where *t _{j}* is the unobserved threshold mid-level

*j*(

`Switch.Levels(``j`

)

).
Threshold levels must be inferred from the data. A state transition occurs when
*z _{t}* crosses a transition mid-level. Transitions
can be discrete or smooth. Transitions of TAR models are discrete, which result in an abrupt
change in the submodel computing the response. An extension of the TAR model is to allow for
smooth transitions.

*Smooth transition autoregressive models*(STAR) create weighted combinations of submodel responses that change continuously with the value of

*z*, and state changes indicate a shift in the dominant submodel.

_{t}The smooth transition weights are determined by a transition function
*F*(*z _{t}*,

*t*,

_{j}*r*) (

_{j}`Switch.Type`

) and transition rate parameter
*r*(

_{j}`Switch.Rates`

), where 0
≤
*F*(

*z*,

_{t}*t*,

_{j}*r*) ≤ 1. Supported transition functions include the normal cdf, logistic (LSTAR), bounded exponential (ESTAR), and custom functions.

_{j}As a result, the general form of the threshold-switching autoregressive model is

$${y}_{t}={f}_{1}({y}_{t};{x}_{t},{\theta}_{1})+{\displaystyle \sum _{j=1}^{n}\left\{\left[{f}_{j+1}\left({y}_{t};{x}_{t},{\theta}_{j+1}\right)-{f}_{j}\left({y}_{t};{x}_{t},{\theta}_{j}\right)\right]F\left({z}_{t},{t}_{j},{r}_{j}\right)\right\}}.$$

In this general case, innovation covariances can switch with the submodel.

For STAR models, the formula assigns weights to all submodel means, regardless of the current state.

For TAR models, the formula assigns unit weight to the current state/submodel only.

With observations,

*F*(*z*,_{t}*t*,_{j}*r*) =_{j}`ttdata(tt,`

, where)`z`

is a vector of threshold variable data.`z`

When `Covariance`

is a nonempty array Σ, it is used to generate all
innovations, independent of the submodels. The model reduces to ([3],
Eqn. 3.6)

$${y}_{t}={\mu}_{1}+{\displaystyle \sum _{j=1}^{n}\left\{\left[{\mu}_{j+1}-{\mu}_{j}\right]F\left({z}_{t},{t}_{j},{r}_{j}\right)\right\}+{\epsilon}_{t}},$$

where:

$${\mu}_{j}=E\left({y}_{t}|{y}_{t-1},{x}_{t}\right),$$ which is the conditional mean of the response series

*y*in state_{t}*j*.*ε*is an iid Gaussian innovations series with covariance Σ._{t}

## Algorithms

A threshold variable *z _{t}*, 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**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

# Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)