summarize

Summarize threshold-switching dynamic regression model estimation results

Since R2021b

Syntax

summarize(Mdl)

summarize(Mdl,state)

results = summarize(___)

Description

summarize(Mdl) displays a summary of the threshold-switching dynamic regression model Mdl.

• If Mdl is an estimated model returned by estimate, then summarize displays estimation results to the MATLAB^® Command Window. The display includes:

  • A model description

  • Estimated threshold transitions

  • Fit statistics, which include the effective sample size, number of estimated submodel parameters and constraints, loglikelihood, and information criteria (AIC and BIC)

  • A table of submodel estimates and inferences, which includes coefficient estimates with standard errors, t-statistics, and p-values

• If Mdl is an unestimated threshold-switching model returned by tsVAR, summarize prints the standard object display (the same display that tsVAR prints during model creation).

summarize(Mdl,state) displays only summary information for the submodel with name state.

results = summarize(___) returns one of the following variables using any of the input argument combinations in the previous syntaxes.

• If Mdl is an estimated threshold-switching model, results is a table containing the submodel estimates and inferences.

• If Mdl is an unestimated model, results is a tsVAR object that is equal to Mdl.

summarize does not print to the Command Window

Examples

Fit SETAR Model to Simulated Data

Assess estimation accuracy using simulated data from a known data-generating process (DGP). This example uses arbitrary parameter values.

Create Model for DGP

Create a discrete threshold transition at mid-level 1.

ttDGP = threshold(1)

ttDGP = 
  threshold with properties:

          Type: 'discrete'
        Levels: 1
         Rates: []
    StateNames: ["1"    "2"]
     NumStates: 2

ttDGP is a threshold object representing the state-switching mechanism of the DGP.

Create the following fully specified self-exciting TAR (SETAR) model for the DGP.

• State 1: ${\mathit{y}}_{\mathit{t}}={\epsilon }_{\mathit{t}}$.

• State 2: ${\mathit{y}}_{\mathit{t}}=2+{\epsilon }_{\mathit{t}}$.

• ${\epsilon }_{\mathit{t}}\sim {\rm N}\left(0,1\right)$.

Specify the submodels by using arima.

mdl1DGP = arima(Constant=0);
mdl2DGP = arima(Constant=2);
mdlDGP = [mdl1DGP mdl2DGP];

Because the innovations distribution is invariant across states, the tsVAR software ignores the value of the submodel innovations variance (Variance property).

Create a threshold-switching model for the DGP. Specify the model-wide innovations variance.

MdlDGP = tsVAR(ttDGP,mdlDGP,Covariance=1);

MdlDGP is a tsVAR object representing the DGP.

Simulate Response Paths from DGP

Generate a random response path of length 100 from the DGP. By default, simulate assumes a SETAR model with delay $\mathit{d}=1$. In other words, the threshold variable is ${\mathit{y}}_{\mathit{t}-1}$.

rng(1) % For reproducibiliy
y = simulate(MdlDGP,100);

y is a 100-by-1 vector of representing the simulated response path.

Create Model for Estimation

Create a partially specified threshold-switching model that has the same structure as the data-generating process, but specify the transition mid-level, submodel coefficients, and model-wide constant as unknown for estimation.

tt = threshold(NaN);
mdl1 = arima('Constant',NaN);
mdl2 = arima('Constant',NaN);
Mdl = tsVAR(tt,[mdl1,mdl2],'Covariance',NaN);

Mdl is a partially specified tsVAR object representing a template for estimation. NaN-valued elements of the Switch and Submodels properties indicate estimable parameters.

Mdl is agnostic of the threshold variable; tsVAR object functions enable you to specify threshold variable characteristics or data.

Create Threshold Transitions Containing Initial Values

The estimation procedure requires initial values for all estimable threshold transition parameters.

Fully specify a threshold transition that has the same structure as tt, but set the mid-level to 0.

tt0 = threshold(0);

tt0 is a fully specified threshold object.

Estimate Model

Fit the model to the simulated path. By default, the model is self-exciting and the delay of the threshold variable is $\mathit{d}=1$.

EstMdl = estimate(Mdl,tt0,y)

EstMdl = 
  tsVAR with properties:

         Switch: [1x1 threshold]
      Submodels: [2x1 varm]
      NumStates: 2
      NumSeries: 1
     StateNames: ["1"    "2"]
    SeriesNames: "1"
     Covariance: 1.0225

EstMdl is a fully specified tsVAR object representing the estimated SETAR model.

Display an estimation summary of the submodels.

summarize(EstMdl)

Description
1-Dimensional tsVAR Model with 2 Submodels

Switch
Transition Type: discrete
Estimated Levels: 1.128

Fit
Effective Sample Size: 99 
Number of Estimated Parameters: 2 
Number of Constrained Parameters: 0 
LogLikelihood: -141.574 
AIC: 287.149 
BIC: 292.339 

Submodels
                           Estimate    StandardError    TStatistic      PValue  
                           ________    _____________    __________    __________

    State 1 Constant(1)    -0.12774       0.13241        -0.96474        0.33467
    State 2 Constant(1)      2.1774       0.16829          12.939     2.7264e-38

The estimates are close to their true values.

Plot the estimated switching mechanism with the threshold data, which is the response data.

figure
ttplot(EstMdl.Switch,'Data',y)

Display Estimation Summary for One State

Create the following fully specified SETAR model for the DGP.

• State 1: $$\left[\begin{array}{c}{y}_{1,t}\\ y_{2,t}\end{array}\right]=\left[\begin{array}{c}-1\\ -4\end{array}\right]+\left[\begin{array}{cc}-0.5& 0.1\\ 0.2& -0.75\end{array}\right]\left[\begin{array}{c}{y}_{1,t-1}\\ y_{2,t-1}\end{array}\right]+\left[\begin{array}{c}{\epsilon }_{1,t}\\ {\epsilon }_{2,t}\end{array}\right]$$.

• State 2: $$\left[\begin{array}{c}{y}_{1,t}\\ y_{2,t}\end{array}\right]=\left[\begin{array}{c}1\\ 4\end{array}\right]+\left[\begin{array}{c}{\epsilon }_{1,t}\\ {\epsilon }_{2,t}\end{array}\right]$$.

• State 3:$$\left[\begin{array}{c}{y}_{1,t}\\ y_{2,t}\end{array}\right]=\left[\begin{array}{c}1\\ 4\end{array}\right]+\left[\begin{array}{cc}0.5& 0.1\\ 0.2& 0.75\end{array}\right]\left[\begin{array}{c}{y}_{1,t-1}\\ y_{2,t-1}\end{array}\right]+\left[\begin{array}{c}{\epsilon }_{1,t}\\ {\epsilon }_{2,t}\end{array}\right]$$.

• $$\left[\begin{array}{c}{\epsilon }_{1,t}\\ {\epsilon }_{2,t}\end{array}\right]\sim N_2(\left[\begin{array}{c}0\\ 0\end{array}\right],\left[\begin{array}{cc}2& -1\\ -1& 1\end{array}\right])$$.

• The system is in state 1 when ${\mathit{y}}_{2,\mathit{t}-4}<-3$, the system is in state 2 when $-3\le {\mathit{y}}_{2,\mathit{t}-4}<3$, and the system is in state 3 otherwise.

t = [-3 3];
ttDGP = threshold(t);
constant1 = [-1; -4];
constant2 = [1; 4];
constant3 = [1; 4];
AR1 = [-0.5 0.1; 0.2 -0.75];
AR3 = [0.5 0.1; 0.2 0.75];
Sigma = [2 -1; -1 1];
mdl1DGP = varm(Constant=constant1,AR={AR1});
mdl2DGP = varm(Constant=constant2);
mdl3DGP = varm(Constant=constant3,AR={AR3});
mdlDGP = [mdl1DGP; mdl2DGP; mdl3DGP];
MdlDGP = tsVAR(ttDGP,mdlDGP,Covariance=Sigma);

DIsplay a summary of the unestimated DGP.

summarize(MdlDGP)

Mdl = 
  tsVAR with properties:

         Switch: [1x1 threshold]
      Submodels: [3x1 varm]
      NumStates: 3
      NumSeries: 2
     StateNames: ["1"    "2"    "3"]
    SeriesNames: ["1"    "2"]
     Covariance: [2x2 double]

summarize prints an object display.

Generate a random response path of length 500 from the DGP. Specify that second response variable with a delay of 4 as the threshold variable.

rng(10) % For reproducibiliy
y = simulate(MdlDGP,500,Index=2,Delay=4);

Create a partially specified threshold-switching model that has the same structure as the DGP, but specify the transition mid-level, submodel coefficients, and model-wide covariance as unknown for estimation.

tt = threshold([NaN; NaN]);
mdlar = varm(2,1);
mdlc = varm(2,0);
Mdl = tsVAR(tt,[mdlar; mdlc; mdlar],Covariance=nan(2));

Fully specify a threshold transition that has the same structure as tt, but set the mid-levels to -1 and 1.

t0 = [-1 1];
tt0 = threshold(t0);

Fit the threshold-switching model to the simulated series. Specify the threshold variable ${\mathit{y}}_{2,\mathit{t}-4}$. Plot the loglikelihood after each iteration of the threshold search algorithm.

EstMdl = estimate(Mdl,tt0,y,IterationPlot=true,Index=2,Delay=4);

The plot displays the evolution of the loglikelihood as the estimation procedure searches for optimal levels. The procedure terminates when one of the stopping criteria is satisfied.

Display an estimation summary for state 3 only.

summarize(EstMdl,3)

Description
2-Dimensional VAR Submodel, State 3

Submodel
                           Estimate    StandardError    TStatistic      PValue  
                           ________    _____________    __________    __________

    State 3 Constant(1)     1.0621       0.095701         11.098      1.2802e-28
    State 3 Constant(2)     3.8707       0.068772         56.284               0
    State 3 AR{1}(1,1)     0.47396       0.058016         8.1694      3.0997e-16
    State 3 AR{1}(2,1)     0.23013       0.041691         5.5199      3.3927e-08
    State 3 AR{1}(1,2)     0.10561       0.018233         5.7924      6.9371e-09
    State 3 AR{1}(2,2)      0.7568       0.013102         57.761               0

Return Estimation Summary Table

Create a discrete threshold transition at mid-level 1.

ttDGP = threshold(1)

ttDGP = 
  threshold with properties:

          Type: 'discrete'
        Levels: 1
         Rates: []
    StateNames: ["1"    "2"]
     NumStates: 2

Create the following fully specified self-exciting TAR (SETAR) model for the DGP.

• State 1: ${\mathit{y}}_{\mathit{t}}={\epsilon }_{\mathit{t}}$.

• State 2: ${\mathit{y}}_{\mathit{t}}=2+{\epsilon }_{\mathit{t}}.$

• ${\epsilon }_{\mathit{t}}\sim {\rm N}\left(0,1\right)$.

Specify the submodels by using arima.

mdl1DGP = arima(Constant=0);
mdl2DGP = arima(Constant=2);
mdlDGP = [mdl1DGP mdl2DGP];

Create a threshold-switching model for the DGP. Specify the model-wide innovations variance.

MdlDGP = tsVAR(ttDGP,mdlDGP,Covariance=1);

Generate a random response path of length 100 from the DGP. By default, simulate assumes a SETAR model with delay $\mathit{d}$ = 1. In other words, the threshold variable is ${\mathit{y}}_{\mathit{t}-1}$.

rng(1) % For reproducibiliy
y = simulate(MdlDGP,100);

Create a partially specified threshold-switching model that has the same structure as the data-generating process, but specify the transition mid-level, submodel coefficients, and model-wide constant as unknown for estimation.

tt = threshold(NaN);
mdl1 = arima('Constant',NaN);
mdl2 = arima('Constant',NaN);
Mdl = tsVAR(tt,[mdl1,mdl2],'Covariance',NaN);

Fully specify a threshold transition that has the same structure as tt, but set the mid-level to 0.

tt0 = threshold(0);

Fit the model to the simulated path. By default, the model is self-exciting and the delay of the threshold variable is $\mathit{d}=1$.

EstMdl = estimate(Mdl,tt0,y);

Return an estimation summary table.

results = summarize(EstMdl)

results=2×4 table
                           Estimate    StandardError    TStatistic      PValue  
                           ________    _____________    __________    __________

    State 1 Constant(1)    -0.12774       0.13241        -0.96474        0.33467
    State 2 Constant(1)      2.1774       0.16829          12.939     2.7264e-38

results is a table containing estimates and inferences for all submodel coefficients.

Identify significant coefficient estimates.

results.Properties.RowNames(results.PValue < 0.05)

ans = 1x1 cell array
    {'State 2 Constant(1)'}

Input Arguments

Mdl — Threshold-switching dynamic regression model

tsVAR object

Threshold-switching dynamic regression model, specified as a tsVAR object returned by estimate or tsVAR.

state — State to summarize

integer in 1:Mdl.NumStates (default) | state name in Mdl.StateNames

State to summarize, specified as an integer in 1:Mdl.NumStates or a state name in Mdl.StateNames.

The default summarizes all states.

Example: summarize(Mdl,3) summarizes the third state in Mdl.

Example: summarize(Mdl,"Recession") summarizes the state labeled "Recession" in Mdl.

Data Types: double | char | string

Output Arguments

results — Model summary

table | tsVAR object

Model summary, returned as a table or tsVAR object.

• If Mdl is an estimated threshold-switching model returned by estimate, results is a table of summary information for the submodel parameter estimates. Each row corresponds to a submodel coefficient. Columns correspond to the estimate (Estimate), standard error (StandardError), t-statistic (TStatistic), and the p-value (PValue).

  When the summary includes all states (the default), results.Properties stores the following fit statistics:

  Field	Description
  Description	Model summary description (character vector)
  EffectiveSampleSize	Effective sample size (numeric scalar)
  NumEstimatedParameters	Number of estimated parameters (numeric scalar)
  NumConstraints	Number of equality constraints (numeric scalar)
  LogLikelihood	Optimized loglikelihood value (numeric scalar)
  AIC	Akaike information criterion (numeric scalar)
  BIC	Bayesian information criterion (numeric scalar)

• If Mdl is an unestimated model, results is a tsVAR object that is equal to Mdl.

Note

When results is a table, it contains only submodel parameter estimates:

• Mdl.Switch contains estimates of threshold transitions.

• Threshold-switching models can have one or more residual covariance matrices. When Mdl has a model-wide covariance, Mdl.Covariance contains the estimated residual covariance. Otherwise, Mdl.Submodels(j).Covariance contains the estimated residual covariance of state j. For details, see tsVAR.

Algorithms

estimate searches over levels and rates for estimated threshold transitions while solving a conditional least-squares problem for submodel parameters, as described in [2]. The standard errors, loglikelihood, and information criteria are conditional on optimal parameter values in the estimated threshold transitions Mdl.Switch. In particular, standard errors do not account for variation in estimated levels and rates.

References

[1] 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.

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

Version History

Introduced in R2021b