Main Content

summarize

Summarize threshold-switching dynamic regression model estimation results

Description

example

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

example

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

example

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

collapse all

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: yt=εt.

  • State 2: yt=2+εt.

  • εtΝ(0,1).

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 d=1. In other words, the threshold variable is yt-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 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)

Figure contains an axes object. The axes object with title Threshold Transitions contains 2 objects of type line.

Create the following fully specified SETAR model for the DGP.

  • State 1: [y1,ty2,t]=[-1-4]+[-0.50.10.2-0.75][y1,t-1y2,t-1]+[ε1,tε2,t].

  • State 2: [y1,ty2,t]=[14]+[ε1,tε2,t].

  • State 3:[y1,ty2,t]=[14]+[0.50.10.20.75][y1,t-1y2,t-1]+[ε1,tε2,t].

  • [ε1,tε2,t]N2([00],[2-1-11]).

  • The system is in state 1 when y2,t-4<-3, the system is in state 2 when -3y2,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 y2,t-4. Plot the loglikelihood after each iteration of the threshold search algorithm.

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

Figure contains an axes object. The axes object with title Threshold Search Algorithm contains an object of type line.

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

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: yt=εt.

  • State 2: yt=2+εt.

  • εtΝ(0,1).

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 d = 1. In other words, the threshold variable is yt-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 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

collapse all

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

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

collapse all

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:

    FieldDescription
    DescriptionModel summary description (character vector)
    EffectiveSampleSizeEffective sample size (numeric scalar)
    NumEstimatedParametersNumber of estimated parameters (numeric scalar)
    NumConstraintsNumber of equality constraints (numeric scalar)
    LogLikelihoodOptimized loglikelihood value (numeric scalar)
    AICAkaike information criterion (numeric scalar)
    BICBayesian 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

See Also

Objects

Functions