Markov-switching SBVAR (Dynare Reference Manual)

4.21 Markov-switching SBVAR

Given a list of variables, observed variables and a data file, Dynare can be used to solve a Markov-switching SBVAR model according to Sims, Waggoner and Zha (2008).¹⁰ Having done this, you can create forecasts and compute the marginal data density, regime probabilities, IRFs, and variance decomposition of the model.

The commands have been modularized, allowing for multiple calls to the same command within a <mod_file>.mod file. The default is to use <mod_file> to tag the input (output) files used (produced) by the program. Thus, to call any command more than once within a <mod_file>.mod file, you must use the *_tag options described below.

Command: markov_switching (OPTIONS…);

Description

Declares the Markov state variable information of a Markov-switching SBVAR model.

Options

chain = INTEGER

The Markov chain considered. Default: none

number_of_regimes = INTEGER

Specifies the total number of regimes in the Markov Chain. This is a required option.

duration = DOUBLE | [ROW VECTOR OF DOUBLES]

The duration of the regimes or regimes. This is a required option. When passed a scalar real number, it specifies the average duration for all regimes in this chain. When passed a vector of size equal number_of_regimes, it specifies the average duration of the associated regimes (1:number_of_regimes) in this chain. An absorbing state can be specified through the restrictions-option.

restrictions = [[ROW VECTOR OF 3 DOUBLES],[ROW VECTOR OF 3 DOUBLES],...]

Provides restrictions on this chain’s regime transition matrix. Its vector argument takes three inputs of the form: [current_period_regime, next_period_regime, transition_probability]

The first two entries are positive integers, and the third is a non-negative real in the set [0,1]. If restrictions are specified for every transition for a regime, the sum of the probabilities must be 1. Otherwise, if restrictions are not provided for every transition for a given regime the sum of the provided transition probabilities msut be <1. Regardless of the number of lags, the restrictions are specified for parameters at time t since the transition probability for a parameter at t is equal to that of the parameter at t-1.

In case of estimating a MS-DSGE model,¹¹ in addition the following options are allowed:

parameters = [LIST OF PARAMETERS]: This option specifies which parameters are controlled by this Markov Chain.
number_of_lags = DOUBLE: Provides the number of lags that each parameter can take within each regime in this chain.

Example

markov_switching(chain=1, duration=2.5, restrictions=[[1,3,0],[3,1,0]]);

Specifies a Markov-switching BVAR with a first chain with 3 regimes that all have a duration of 2.5 periods. The probability of directly going from regime 1 to regime 3 and vice versa is 0.

Example

markov_switching(chain=2, number_of_regimes=3, duration=[0.5, 2.5, 2.5],
parameter=[alpha, rho], number_of_lags=2, restrictions=[[1,3,0],[3,3,1]]);

Specifies a Markov-switching DSGE model with a second chain with 3 regimes that have durations of 0.5, 2.5, and 2.5 periods, respectively. The switching parameters are alpha and rho. The probability of directly going from regime 1 to regime 3 is 0, while regime 3 is an absorbing state.

Command: svar (OPTIONS…);

Description

Each Markov chain can control the switching of a set of parameters. We allow the parameters to be divided equation by equation and by variance or slope and intercept.

Options

coefficients: Specifies that only the slope and intercept in the given equations are controlled by the given chain. One, but not both, of coefficients or variances must appear. Default: none
variances: Specifies that only variances in the given equations are controlled by the given chain. One, but not both, of coefficients or variances must appear. Default: none
equations: Defines the equation controlled by the given chain. If not specified, then all equations are controlled by chain. Default: none
chain = INTEGER: Specifies a Markov chain defined by markov_switching. Default: none

Command: sbvar (OPTIONS…);

Description

To be documented. For now, see the wiki: http://www.dynare.org/DynareWiki/SbvarOptions

Options

datafile
freq
initial_year
initial_subperiod
final_year
final_subperiod
data
vlist
vlistlog
vlistper
restriction_fname
nlags
cross_restrictions
contemp_reduced_form
real_pseudo_forecast
no_bayesian_prior
dummy_obs
nstates
indxscalesstates
alpha
beta
gsig2_lmdm
q_diag
flat_prior
ncsk
nstd
ninv
indxparr
indxovr
aband
indxap
apband
indximf
indxfore
foreband
indxgforhat
indxgimfhat
indxestima
indxgdls
eq_ms
cms
ncms
eq_cms
tlindx
tlnumber
cnum
forecast
coefficients_prior_hyperparameters

Block: svar_identification ;

Description

This block is terminated by end;, and contains lines of the form:

UPPER_CHOLESKY;
LOWER_CHOLESKY;
EXCLUSION CONSTANTS;
EXCLUSION LAG INTEGER; VARIABLE_NAME [,VARIABLE_NAME…]
EXCLUSION LAG INTEGER; EQUATION INTEGER, VARIABLE_NAME [,VARIABLE_NAME…]
RESTRICTION EQUATION INTEGER, EXPRESSION = EXPRESSION;

To be documented. For now, see the wiki: http://www.dynare.org/DynareWiki/MarkovSwitchingInterface

Command: ms_estimation (OPTIONS…);

Description

Triggers the creation of an initialization file for, and the estimation of, a Markov-switching SBVAR model. At the end of the run, the , , and $\zeta$ matrices are contained in the oo_.ms structure.

Options

General Options

file_tag = FILENAME: The portion of the filename associated with this run. This will create the model initialization file, init_<file_tag>.dat. Default: <mod_file>
output_file_tag = FILENAME: The portion of the output filename that will be assigned to this run. This will create, among other files, est_final_<output_file_tag>.out, est_intermediate_<output_file_tag>.out. Default: <file_tag>
no_create_init: Do not create an initialization file for the model. Passing this option will cause the Initialization Options to be ignored. Further, the model will be generated from the output files associated with the previous estimation run (i.e. est_final_<file_tag>.out, est_intermediate_<file_tag>.out or init_<file_tag>.dat, searched for in sequential order). This functionality can be useful for continuing a previous estimation run to ensure convergence was reached or for reusing an initialization file. NB: If this option is not passed, the files from the previous estimation run will be overwritten. Default: off (i.e. create initialization file)

Initialization Options

coefficients_prior_hyperparameters = [DOUBLE1 DOUBLE2 DOUBLE3 DOUBLE4 DOUBLE5 DOUBLE6]

Sets the hyper parameters for the model. The six elements of the argument vector have the following interpretations:

Position: Interpretation
1: Overall tightness for and
2: Relative tightness for
3: Relative tightness for the constant term
4: Tightness on lag decay (range: 1.2 - 1.5); a faster decay produces better inflation process
5: Weight on nvar sums of coeffs dummy observations (unit roots)
6: Weight on single dummy initial observation including constant

Default: [1.0 1.0 0.1 1.2 1.0 1.0]

freq = INTEGER | monthly | quarterly | yearly

Frequency of the data (e.g. monthly, 12). Default: 4

initial_year = INTEGER

The first year of data. Default: none

initial_subperiod = INTEGER

The first period of data (i.e. for quarterly data, an integer in [1,4]). Default: 1

final_year = INTEGER

The last year of data. Default: Set to encompass entire dataset.

final_subperiod = INTEGER

The final period of data (i.e. for monthly data, an integer in [1,12]. Default: When final_year is also missing, set to encompass entire dataset; when final_year is indicated, set to the maximum number of subperiods given the frequency (i.e. 4 for quarterly data, 12 for monthly,...).

datafile = FILENAME

See datafile.

xls_sheet = NAME

See xls_sheet.

xls_range = RANGE

See xls_range.

nlags = INTEGER

The number of lags in the model. Default: 1

cross_restrictions

Use cross and restrictions. Default: off

contemp_reduced_form

Use contemporaneous recursive reduced form. Default: off

no_bayesian_prior

Do not use Bayesian prior. Default: off (i.e. use Bayesian prior)

alpha = INTEGER

Alpha value for squared time-varying structural shock lambda. Default: 1

beta = INTEGER

Beta value for squared time-varying structural shock lambda. Default: 1

gsig2_lmdm = INTEGER

The variance for each independent $\lambda$ parameter under SimsZha restrictions. Default: 50^2

specification = sims_zha | none

This controls how restrictions are imposed to reduce the number of parameters. Default: Random Walk

Estimation Options

convergence_starting_value = DOUBLE: This is the tolerance criterion for convergence and refers to changes in the objective function value. It should be rather loose since it will gradually be tightened during estimation. Default: 1e-3
convergence_ending_value = DOUBLE: The convergence criterion ending value. Values much smaller than square root machine epsilon are probably overkill. Default: 1e-6
convergence_increment_value = DOUBLE: Determines how quickly the convergence criterion moves from the starting value to the ending value. Default: 0.1
max_iterations_starting_value = INTEGER: This is the maximum number of iterations allowed in the hill-climbing optimization routine and should be rather small since it will gradually be increased during estimation. Default: 50
max_iterations_increment_value = DOUBLE: Determines how quickly the maximum number of iterations is increased. Default: 2
max_block_iterations = INTEGER: The parameters are divided into blocks and optimization proceeds over each block. After a set of blockwise optimizations are performed, the convergence criterion is checked and the blockwise optimizations are repeated if the criterion is violated. This controls the maximum number of times the blockwise optimization can be performed. Note that after the blockwise optimizations have converged, a single optimization over all the parameters is performed before updating the convergence value and maximum number of iterations. Default: 100
max_repeated_optimization_runs = INTEGER: The entire process described by max_block_iterations is repeated until improvement has stopped. This is the maximum number of times the process is allowed to repeat. Set this to 0 to not allow repetitions. Default: 10
function_convergence_criterion = DOUBLE: The convergence criterion for the objective function when max_repeated_optimizations_runs is positive. Default: 0.1
parameter_convergence_criterion = DOUBLE: The convergence criterion for parameter values when max_repeated_optimizations_runs is positive. Default: 0.1
number_of_large_perturbations = INTEGER: The entire process described by max_block_iterations is repeated with random starting values drawn from the posterior. This specifies the number of random starting values used. Set this to 0 to not use random starting values. A larger number should be specified to ensure that the entire parameter space has been covered. Default: 5
number_of_small_perturbations = INTEGER: The number of small perturbations to make after the large perturbations have stopped improving. Setting this number much above 10 is probably overkill. Default: 5
number_of_posterior_draws_after_perturbation = INTEGER: The number of consecutive posterior draws to make when producing a small perturbation. Because the posterior draws are serially correlated, a small number will result in a small perturbation. Default: 1
max_number_of_stages = INTEGER: The small and large perturbation are repeated until improvement has stopped. This specifics the maximum number of stages allowed. Default: 20
random_function_convergence_criterion = DOUBLE: The convergence criterion for the objective function when number_of_large_perturbations is positive. Default: 0.1
random_parameter_convergence_criterion = DOUBLE: The convergence criterion for parameter values when number_of_large_perturbations is positive. Default: 0.1

Example

ms_estimation(datafile=data, initial_year=1959, final_year=2005,
nlags=4, max_repeated_optimization_runs=1, max_number_of_stages=0);

ms_estimation(file_tag=second_run, datafile=data, initial_year=1959,
final_year=2005, nlags=4, max_repeated_optimization_runs=1,
max_number_of_stages=0);

ms_estimation(file_tag=second_run, output_file_tag=third_run,
no_create_init, max_repeated_optimization_runs=5,
number_of_large_perturbations=10);

Command: ms_simulation ;

Command: ms_simulation (OPTIONS…);

Description

Simulates a Markov-switching SBVAR model.

Options

file_tag = FILENAME: The portion of the filename associated with the ms_estimation run. Default: <mod_file>
output_file_tag = FILENAME: The portion of the output filename that will be assigned to this run. Default: <file_tag>
mh_replic = INTEGER: The number of draws to save. Default: 10,000
drop = INTEGER: The number of burn-in draws. Default: 0.1*mh_replic*thinning_factor
thinning_factor = INTEGER: The total number of draws is equal to thinning_factor*mh_replic+drop. Default: 1
adaptive_mh_draws = INTEGER: Tuning period for Metropolis-Hastings draws. Default: 30,000
save_draws: Save all elements of , , , and $\zeta$ , to a file named draws_<<file_tag>>.out with each draw on a separate line. A file that describes how these matrices are laid out is contained in draws_header_<<file_tag>>.out. A file called load_flat_file.m is provided to simplify loading the saved files into the corresponding variables A0, Aplus, Q, and Zeta in your MATLAB/Octave workspace. Default: off

Example

ms_simulation(file_tag=second_run);

ms_simulation(file_tag=third_run, mh_replic=5000, thinning_factor=3);

Command: ms_compute_mdd ;

Command: ms_compute_mdd (OPTIONS…);

Description

Computes the marginal data density of a Markov-switching SBVAR model from the posterior draws. At the end of the run, the Muller and Bridged log marginal densities are contained in the oo_.ms structure.

Options

file_tag = FILENAME

See file_tag.

output_file_tag = FILENAME

See output_file_tag.

simulation_file_tag = FILENAME

The portion of the filename associated with the simulation run. Default: <file_tag>

proposal_type = INTEGER

The proposal type:

1: Gaussian
2: Power
3: Truncated Power
4: Step
5: Truncated Gaussian

Default: 3

proposal_lower_bound = DOUBLE

The lower cutoff in terms of probability. Not used for proposal_type in [1,2]. Required for all other proposal types. Default: 0.1

proposal_upper_bound = DOUBLE

The upper cutoff in terms of probability. Not used for proposal_type equal to 1. Required for all other proposal types. Default: 0.9

mdd_proposal_draws = INTEGER

The number of proposal draws. Default: 100,000

mdd_use_mean_center

Use the posterior mean as center. Default: off

Command: ms_compute_probabilities ;

Command: ms_compute_probabilities (OPTIONS…);

Description

Computes smoothed regime probabilities of a Markov-switching SBVAR model. Output .eps files are contained in <output_file_tag/Output/Probabilities>.

Options

file_tag = FILENAME: See file_tag.
output_file_tag = FILENAME: See output_file_tag.
filtered_probabilities: Filtered probabilities are computed instead of smoothed. Default: off
real_time_smoothed: Smoothed probabilities are computed based on time t information for $0\le t\le nobs$ . Default: off

Command: ms_irf ;

Command: ms_irf (OPTIONS…);

Description

Computes impulse response functions for a Markov-switching SBVAR model. Output .eps files are contained in <output_file_tag/Output/IRF>, while data files are contained in <output_file_tag/IRF>.

Options

file_tag = FILENAME: See file_tag.
output_file_tag = FILENAME: See output_file_tag.
simulation_file_tag = FILENAME: See simulation_file_tag.
horizon = INTEGER: The forecast horizon. Default: 12
filtered_probabilities: Uses filtered probabilities at the end of the sample as initial conditions for regime probabilities. Only one of filtered_probabilities, regime and regimes may be passed. Default: off
error_band_percentiles = [DOUBLE1 …]: The percentiles to compute. Default: [0.16 0.50 0.84]. If median is passed, the default is [0.5]
shock_draws = INTEGER: The number of regime paths to draw. Default: 10,000
shocks_per_parameter = INTEGER: The number of regime paths to draw under parameter uncertainty. Default: 10
thinning_factor = INTEGER: Only $1/@code{thinning_factor}$ of the draws in posterior draws file are used. Default: 1
free_parameters = NUMERICAL_VECTOR: A vector of free parameters to initialize theta of the model. Default: use estimated parameters
parameter_uncertainty: Calculate IRFs under parameter uncertainty. Requires that ms_simulation has been run. Default: off
regime = INTEGER: Given the data and model parameters, what is the ergodic probability of being in the specified regime. Only one of filtered_probabilities, regime and regimes may be passed. Default: off
regimes: Describes the evolution of regimes. Only one of filtered_probabilities, regime and regimes may be passed. Default: off
median: A shortcut to setting error_band_percentiles=[0.5]. Default: off

Command: ms_forecast ;

Command: ms_forecast (OPTIONS…);

Description

Generates forecasts for a Markov-switching SBVAR model. Output .eps files are contained in <output_file_tag/Output/Forecast>, while data files are contained in <output_file_tag/Forecast>.

Options

file_tag = FILENAME: See file_tag.
output_file_tag = FILENAME: See output_file_tag.
simulation_file_tag = FILENAME: See simulation_file_tag.
data_obs_nbr = INTEGER: The number of data points included in the output. Default: 0
error_band_percentiles = [DOUBLE1 …]: See error_band_percentiles.
shock_draws = INTEGER: See shock_draws.
shocks_per_parameter = INTEGER: See shocks_per_parameter.
thinning_factor = INTEGER: See thinning_factor.
free_parameters = NUMERICAL_VECTOR: See free_parameters.
parameter_uncertainty: See parameter_uncertainty.
regime = INTEGER: See regime.
regimes: See regimes.
median: See median.
horizon = INTEGER: See horizon.

Command: ms_variance_decomposition ;

Command: ms_variance_decomposition (OPTIONS…);

Description

Computes the variance decomposition for a Markov-switching SBVAR model. Output .eps files are contained in <output_file_tag/Output/Variance_Decomposition>, while data files are contained in <output_file_tag/Variance_Decomposition>.

Options

file_tag = FILENAME: See file_tag.
output_file_tag = FILENAME: See output_file_tag.
simulation_file_tag = FILENAME: See simulation_file_tag.
horizon = INTEGER: See horizon.
filtered_probabilities: See filtered_probabilities.
no_error_bands: Do not output percentile error bands (i.e. compute mean). Default: off (i.e. output error bands)
error_band_percentiles = [DOUBLE1 …]: See error_band_percentiles.
shock_draws = INTEGER: See shock_draws.
shocks_per_parameter = INTEGER: See shocks_per_parameter.
thinning_factor = INTEGER: See thinning_factor.
free_parameters = NUMERICAL_VECTOR: See free_parameters.
parameter_uncertainty: See parameter_uncertainty.
regime = INTEGER: See regime.
regimes: See regimes.

Footnotes

(10)

If you want to align the paper with the description herein, please note that is and is .

(11)

An example can be found at https://github.com/DynareTeam/dynare/blob/master/tests/ms-dsge/test_ms_dsge.mod.