tsVAR

Create threshold-switching dynamic regression model

Since R2021b

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:

• Switching mechanism among states, represented by threshold transitions (threshold object)

• State-specific submodels, either autoregressive (ARX) or vector autoregression (VARX) models (arima or varm objects), which can contain exogenous regression 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

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.

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

tt — Threshold transitions

threshold object

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.

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 — Unique Series labels

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

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

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"
      SeriesName: "Y"
    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"
      SeriesName: "Y"
    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:

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.

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)"
      SeriesName: "Y"
    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_t within the regimes.

$$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\\ ⋮& ⋮\\ 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_t is the univariate threshold variable. z_t can be exogenous to the system or endogenous and delayed. If $$z_t=y_{k,t-d},$$ the system is a self-exciting threshold autoregressive model (SETAR) with unobserved delay d.

• x_t is a vector of observed exogenous variables at time t.

• θ_i is the regime 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_t) is not random—observed values of the threshold variable z_t determine the state of the system:

$$s_t=\{\begin{array}{ll}1\hfill & ,z_t<t_1\hfill \\ 2\hfill & ,t_1\le z_t<t_2\hfill \\ ⋮\hfill & ⋮\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_t, and state changes indicate a shift in the dominant submodel.

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_j) ≤ 1. Supported transition functions include the normal cdf, logistic (LSTAR), bounded exponential (ESTAR), and custom functions.

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,z), where z is a vector of threshold variable data.

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_t in state j.

• ε_t is an iid Gaussian innovations series with covariance Σ.

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