Docstrings

Struct MSM holds the parameters of the model, data and some other information. Is returned by the function MSModel.

MSModel(y::VecOrMat{V},
        k::Int64, 
        ;intercept::String = "switching",
        exog_vars::VecOrMat{V},
        exog_switching_vars::VecOrMat{V},
        switching_var::Bool = true,
        exog_tvtp::VecOrMat{V},
        x0::Vector{V},
        algorithm::Symbol = :LN_SBPLX,
        maxtime::Int64 = -1,
        random_search::Int64 = 0,
        random_search_em::Int64,
        verbose::Bool) where V <: AbstractFloat

Function to estimate the Markov Switching Model. Returns an instance of MSM struct.

Note: The model likelihood function is very nonlinear and prone to local maxima. Increasing number of random searches can help, for the cost of longer training time. For the same reason, it is recommended not to estimate model with many states (e.g. more than 5), altough it is possible.

Arguments

• y::VecOrMat{V}: dependent variable.

• k::Int64: number of states.

• intercept::String: "switching" or "non-switching" or "no".

• exog_vars::VecOrMat{V}: optional exogenous variables for the non-switching part of the model.

• exog_switching_vars::VecOrMat{V}: optional exogenous variables for the switching part of the model.

• switching_var::Bool: is variance state dependent?

• exog_tvtp::VecOrMat{V}: optional exogenous variables for the tvtp part of the model.

• x0::Vector{V}: initial guess for the parameters. If empty, the initial guess is generated from k-means clustering.

• algorithm::Symbol: optimization algorithm to use. One of [:LD_VAR2, :LD_VAR1, :LD_LBFGS, :LN_SBPLX]

• maxtime::Int64: maximum time in seconds to run the optimization. If negative, the maximum time is equal T/2.

• random_search_em::Int64: number of random searches to perform for the EM algorithm. If 0, no random search is performed.

• random_search::Int64: number of random searches to perform.

• verbose::Bool: if true, prints out the progress of the random searches.

References:

• Hamilton, J. D. (1989). A new approach to the economic analysis of nonstationary time series and the business cycle. Econometrica: Journal of the Econometric Society, 357-384.
• Filardo, Andrew J. (1994). Business cycle phases and their transitional dynamics. Journal of Business & Economic Statistics, 12(3), 299-308.

See also grid_search_msm.

grid_search_msm(y::VecOrMat{V}, 
                x::VecOrMat{V},
                criterion::String = "AIC";
                k::Vector{Int64} = [2,3,4],
                intercept::Vector{String} = ["switching", "non-switching"],
                vars::Vector{Vector{String}},
                switching_var::Vector{Bool} = [true, false],
                random_n::Int64,
                random_search_em::Int64 = 0,
                random_search::Int64 = 0,
                verbose::Bool = true,
                algorithm::Symbol = :LN_SBPLX,
                maxtime::Int64 = -1) where V <: AbstractFloat

Function for exhaustive or random search over specified parameter values for a Markov switching model (currently non-TVTP).

Returns a selected MSM model, vector of criterion values and a vector of tuples containing parameter space.

Note: Unless the data is of small size (both dimensions), it is best to limit the parameter space by providing smaller possible parameters or by chosing random number of parameters to evaluate.

Arguments

• y::VecOrMat{V}: dependent variable.
• x::VecOrMat{V}: independent variables.
• criterion::String: criterion to use for model selection. One of "AIC" (default) or "BIC".
• k::Int64: vector of states to evaluate.
• intercept::String: vector of "switching", "non-switching" or "no".
• vars::Vector{Vector{String}}: vector of vectors with either "switching" or "non-switching" for corresponding variables in x argument.
• switching_var::Vector{Bool}: vector of booleans for variance state dependency.
• switching_var::Bool: is variance state dependent?
• random_n::Int64: number of random parameters combinations to evaluate. If negative, performs an exhaustive grid search.
• random_search_em::Int64: number of random searches to perform for the EM algorithm in eery model estimation. If 0, no random search is performed.
• random_search::Int64: number of random searches to perform.
• algorithm::Symbol: optimization algorithm to use. One of [:LDVAR2, :LDVAR1, :LDLBFGS, :LNSBPLX]
• maxtime::Int64: maximum time in seconds to run the optimization. If negative, the maximum time is equal T/2.
• verbose::Bool: if true, prints out the progress of the grid/random search.

See also MSModel.

generate_msm(model::MSM, T::Int64)

When applied to estimated model, generates artificial data of size T from the model.

generate_msm(μ::Vector{Float64}, σ::Vector{Float64}, P::Matrix{Float64}, T::Int64; <keyword arguments>)

Generate artificial data from Markov switching model from provided parameters. Returns a tuple of (y, s_t, X) where y is the generated data, s_t is the state sequence and X is the design matrix.

Note, in order to have non-switching parameter provide it k-times.

Arguments

• μ::Vector{AbstractFloat}: intercepts for each state.
• σ::Vector{AbstractFloat}: standard deviations for each state.
• P::Matrix{AbstractFloat}: transition matrix.
• T::Int64: number of observations to generate.
• β::Vector{AbstractFloat}: switching coefficients. (first k elements in vector are coefficeints of the first state equation).
• β_ns::Vector{AbstractFloat}: non-switching coefficients.
• δ::Vector{AbstractFloat}: tvtp coefficients.
• tvtp_intercept::Bool: whether to include an intercept in the tvtp model.

summary_msm(model::MSM; digits::Int64=3)

Returns formated summary table of estimated model. It's built from summary_msm, state_coeftable and coeftable_tvtp functions.

transition_mat(model::MSM; digits::Int64=2)

Returns formated table of estimated transition matrix probabilities. It's one of the functions called by the summary_msm function.

See also summary_msm, state_coeftable, coeftable_tvtp.

state_coeftable(model::MSM, state::Int64; digits::Int64=3)

Returns formated table of coefficients and their statistics for a given state. It's one of the functions called by the summary_msm function.

See also summary_msm, coeftable_tvtp, transition_mat.

coeftable_tvtp(model::MSM; digits::Int64=3)

Returns formated table of estimated coefficients from TVTP model and their statistics. It's one of the functions called by the summary_msm function.

See also summary_msm, state_coeftable, transition_mat.

get_std_errors(model::MSM)

Returns standard errors of the estimated parameters. The errors are calculated with finite difference hessian od the log-likelihood function.

The output is a vector of standard errors in order given by raw_params field of the model.

The formula is squared diagonal values of the inverse (moore-penrose) of the hessian matrix:

\[(-\frac{\partial^2 \mathcal{L}(\mathbf{\theta})}{\partial \mathbf{\theta} \mathbf{\theta}'})^{-1}\]

filtered_probs(model::MSM; kwargs...)

Returns filtered probabilities of each state at each time period. If only model is provided, in-sample data is used.

Filtered probabilites, unlike smoothed probabilites, are calculated using data available up to time T.

Arguments

• model::MSM: estimated model.
• y: optional data for dependent variabla.
• exog_vars: optional exogenous variables for the non-switching part of the model.
• exog_switching_vars: optional exogenous variables for the switching part of the model.
• exog_tvtp: optional exogenous variables for the tvtp part of the model.

See also smoothed_probs and expected_duration.

smoothed_probs(model::MSM; kwargs...)

Returns smoothed probabilities of each state at each time period (Kim, 1994). If only MSM model is provided, in-sample data is used.

Smoothed probabilites, unlike filtered probabilites, are calculated using all available data.

Arguments

• model::MSM: estimated model.
• y: optional data for dependent variabla.
• exog_vars: optional exogenous variables for the non-switching part of the model.
• exog_switching_vars: optional exogenous variables for the switching part of the model.
• exog_tvtp: optional exogenous variables for the tvtp part of the model.

See also filtered_probs and expected_duration.

References

Kim, Chang Jin (1994). Dynamic Linear Models with Markov-Switching. Journal of Econometrics 60, 1-22.

predict(model::MSM, instantaneous::Bool = false; kwargs...)

Provide either instantaneous or one-step-ahead prediction of the dependent variable.

Which is the probability weighted average of predictions of each state equation:

\[\hat{y}_t = \sum_{i=1}^{k} \hat{\xi}_{i,t}X_{t}'\hat{\beta}_{i}\]

And for one step ahead, the state probabilities have to be predicted themselves:

\[\hat{y}_{t+1} = \sum_{i=1}^{k} (P\hat{\xi}_{i,t})X_{t+1}'\hat{\beta}_{i}\]

If only MSM model is provided, in-sample data is used.

Returns a tuple of (ŷ, ξ_t) where ŷ is the predicted value of the dependent variable and ξ_t is the filtered probabilities of each state at each time period.

Arguments

• model::MSM: estimated model.
• y: optional data for dependent variabla.
• exog_vars: optional exogenous variables for the non-switching part of the model.
• exog_switching_vars: optional exogenous variables for the switching part of the model.
• exog_tvtp: optional exogenous variables for the tvtp part of the model.

expected_duration(model::MSM, exog_tvtp::VecOrMat{AbstractFloat})

For non-TVTP model, returns Vector of expected duration of each state. For TVTP model, returns a matrix of expected duration of each state at timt t.

formula: 1 / (1 - P[i,i]) or for TVTP - 1 / (1 - P[i,i, t])

Arguments

• model::MSM: estimated model.
• exog_tvtp::VecOrMat{AbstractFloat}: optional exogenous variables for the tvtp model. If not provided, in-sample data is used.

See also ergodic_probs.

ergodic_probs(P::Matrix{Float64})

Returns a k-size Vector of ergodic probabilites of each state.

The ergodic probabilites (also known as long-term probabilites) of a Markov process are the probabilites that satisfy the following equation:

\[\lim_{n\to\infty} P^n = \pi = P \pi \]

The ergodic probability is proportional to the eigenvector of the transition matrix P associated to the unit eigenvalue.

Arguments

• P::Matrix{Float64}: left stochastic transition matrix.

See also expected_duration.

ergodic_probs(model::MSM, exog_tvtp::VecOrMat{V})

when applied to the non-TVTP model, returns a k-size Vector of ergodic probabilites of each state. For TVTP model, returns $T \times K$ a matrix of ergodic probabilites of each state at time t.

Arguments

• model::MSM: estimated model.
• exog_tvtp::VecOrMat{AbstractFloat}: optional exogenous variables for the tvtp model. If not provided, in-sample data is used.

See also expected_duration.

add_lags(y::Vector{Float64}, p::Int64)

Given a vector y of length T, returns a matrix of size (T-p) x (p+1) where the first column is y[p+1:T], second column is y[p:T-1] and so on.