diff --git a/joss.06441/10.21105.joss.06441.crossref.xml b/joss.06441/10.21105.joss.06441.crossref.xml new file mode 100644 index 0000000000..b38dbf5557 --- /dev/null +++ b/joss.06441/10.21105.joss.06441.crossref.xml @@ -0,0 +1,297 @@ + + + + 20240614115908-3e7b3565a98dfbfcd96c9232e76d4f175b396c11 + 20240614115908 + + JOSS Admin + admin@theoj.org + + The Open Journal + + + + + Journal of Open Source Software + JOSS + 2475-9066 + + 10.21105/joss + https://joss.theoj.org + + + + + 06 + 2024 + + + 9 + + 98 + + + + MarSwitching.jl: A Julia package for Markov switching +dynamic models + + + + Mateusz + Dadej + https://orcid.org/0000-0002-1791-7611 + + + + 06 + 14 + 2024 + + + 6441 + + + 10.21105/joss.06441 + + + http://creativecommons.org/licenses/by/4.0/ + http://creativecommons.org/licenses/by/4.0/ + http://creativecommons.org/licenses/by/4.0/ + + + + Software archive + 10.5281/zenodo.11546432 + + + GitHub review issue + https://github.com/openjournals/joss-reviews/issues/6441 + + + + 10.21105/joss.06441 + https://joss.theoj.org/papers/10.21105/joss.06441 + + + https://joss.theoj.org/papers/10.21105/joss.06441.pdf + + + + + + Julia: A fresh approach to numerical +computing + Bezanson + SIAM review + 1 + 59 + 10.1137/141000671 + 2017 + Bezanson, J., Edelman, A., Karpinski, +S., & Shah, V. B. (2017). Julia: A fresh approach to numerical +computing. SIAM Review, 59(1), 65–98. +https://doi.org/10.1137/141000671 + + + A new approach to the economic analysis of +nonstationary time series and the business cycle + Hamilton + Econometrica + 2 + 57 + 10.2307/1912559 + 1989 + Hamilton, J. D. (1989). A new +approach to the economic analysis of nonstationary time series and the +business cycle. Econometrica, 57(2), 357–384. +https://doi.org/10.2307/1912559 + + + American options with regime +switching + Buffington + International Journal of Theoretical and +Applied Finance + 05 + 05 + 10.1142/S0219024902001523 + 2002 + Buffington, J., & Elliott, R. J. +(2002). American options with regime switching. International Journal of +Theoretical and Applied Finance, 05(05), 497–514. +https://doi.org/10.1142/S0219024902001523 + + + Evaluating forecasts of political conflict +dynamics + Brandt + International Journal of +Forecasting + 4 + 30 + 10.1016/j.ijforecast.2014.03.014 + 0169-2070 + 2014 + Brandt, P. T., Freeman, J. R., & +Schrodt, P. A. (2014). Evaluating forecasts of political conflict +dynamics. International Journal of Forecasting, 30(4), 944–962. +https://doi.org/10.1016/j.ijforecast.2014.03.014 + + + Predicting daily streamflow with a novel +multi-regime switching ARIMA-MS-GARCH model + Wang + Journal of Hydrology: Regional +Studies + 47 + 10.1016/j.ejrh.2023.101374 + 2214-5818 + 2023 + Wang, H., Song, S., Zhang, G., & +Ayantoboc, O. O. (2023). Predicting daily streamflow with a novel +multi-regime switching ARIMA-MS-GARCH model. Journal of Hydrology: +Regional Studies, 47, 101374. +https://doi.org/10.1016/j.ejrh.2023.101374 + + + Regime shifts in the COVID-19 case fatality +rate dynamics: A Markov-switching autoregressive model +analysis + Shiferaw + Chaos, Solitons & Fractals: +X + 6 + 10.1016/j.csfx.2021.100059 + 2590-0544 + 2021 + Shiferaw, Y. A. (2021). Regime shifts +in the COVID-19 case fatality rate dynamics: A Markov-switching +autoregressive model analysis. Chaos, Solitons & Fractals: X, 6, +100059. +https://doi.org/10.1016/j.csfx.2021.100059 + + + A Markov-switching approach to the study of +citations in academic journals + Delbianco + Journal of Informetrics + 4 + 14 + 10.1016/j.joi.2020.101081 + 1751-1577 + 2020 + Delbianco, F., Fioriti, A., +Hernandez-Chanto, A., & Tohmé, F. (2020). A Markov-switching +approach to the study of citations in academic journals. Journal of +Informetrics, 14(4), 101081. +https://doi.org/10.1016/j.joi.2020.101081 + + + R: A language and environment for statistical +computing + R Core Team + 2017 + R Core Team. (2017). R: A language +and environment for statistical computing. R Foundation for Statistical +Computing. https://www.R-project.org/ + + + MSwM: Fitting Markov switching +models + Josep A. Sanchez-Espigares + 10.32614/cran.package.mswm + 2021 + Josep A. Sanchez-Espigares, A. L.-M. +(2021). MSwM: Fitting Markov switching models. +https://doi.org/10.32614/cran.package.mswm + + + What’s for dynr: A package for linear and +nonlinear dynamic modeling in R + Ou + The R Journal + 11 + 10.32614/rj-2019-012 + 2019 + Ou, L., Hunter, M. D., & Chow, +S.-M. (2019). What’s for dynr: A package for linear and nonlinear +dynamic modeling in R. The R Journal, 11, 1–20. +https://doi.org/10.32614/rj-2019-012 + + + Statsmodels: Econometric and statistical +modeling with Python + Seabold + 9th python in science +conference + 10.25080/majora-92bf1922-011 + 2010 + Seabold, S., & Perktold, J. +(2010). Statsmodels: Econometric and statistical modeling with Python. +9th Python in Science Conference. +https://doi.org/10.25080/majora-92bf1922-011 + + + MS_regress - the MATLAB package for Markov +regime switching models + Perlin + 10.2139/ssrn.1714016 + 2012 + Perlin, M. (2012). MS_regress - the +MATLAB package for Markov regime switching models. +https://doi.org/10.2139/ssrn.1714016 + + + HiddenMarkovModels.jl: Generic, fast and +reliable state space modeling + Dalle + Journal of Open Source +Software + 96 + 9 + 10.21105/joss.06436 + 2024 + Dalle, G. (2024). +HiddenMarkovModels.jl: Generic, fast and reliable state space modeling. +Journal of Open Source Software, 9(96), 6436. +https://doi.org/10.21105/joss.06436 + + + Business-cycle phases and their transitional +dynamics + Filardo + Journal of Business & Economic +Statistics + 3 + 12 + 10.2307/1392086 + 1994 + Filardo, A. J. (1994). Business-cycle +phases and their transitional dynamics. Journal of Business & +Economic Statistics, 12(3), 299–308. +https://doi.org/10.2307/1392086 + + + Dynamic linear models with +Markov-switching + Kim + Journal of Econometrics + 1 + 60 + 10.1016/0304-4076(94)90036-1 + 0304-4076 + 1994 + Kim, C.-J. (1994). Dynamic linear +models with Markov-switching. Journal of Econometrics, 60(1), 1–22. +https://doi.org/10.1016/0304-4076(94)90036-1 + + + + + + diff --git a/joss.06441/10.21105.joss.06441.pdf b/joss.06441/10.21105.joss.06441.pdf new file mode 100644 index 0000000000..049956a2a0 Binary files /dev/null and b/joss.06441/10.21105.joss.06441.pdf differ diff --git a/joss.06441/paper.jats/10.21105.joss.06441.jats b/joss.06441/paper.jats/10.21105.joss.06441.jats new file mode 100644 index 0000000000..0122a5b0b5 --- /dev/null +++ b/joss.06441/paper.jats/10.21105.joss.06441.jats @@ -0,0 +1,622 @@ + + +
+ + + + +Journal of Open Source Software +JOSS + +2475-9066 + +Open Journals + + + +6441 +10.21105/joss.06441 + +MarSwitching.jl: A Julia package for Markov switching +dynamic models + + + +https://orcid.org/0000-0002-1791-7611 + +Dadej +Mateusz + + +* + + + +Phd. student, University of Brescia, Italy + + + + +* E-mail: + +9 +98 +6441 + +Authors of papers retain copyright and release the +work under a Creative Commons Attribution 4.0 International License (CC +BY 4.0) +2022 +The article authors + +Authors of papers retain copyright and release the work under +a Creative Commons Attribution 4.0 International License (CC BY +4.0) + + + +Julia +Time series +Econometrics +Markov processes +Nonlinear models + + + + + + Summary +

MarSwitching.jl package allows users of the + Julia programming language + (Bezanson + et al., 2017) to efficiently use Markov switching dynamic + models. It provides a set of tools for estimation, simulation, and + forecasting of Markov switching models. This class of models is the + principal tool for modelling time series with regime changes. The + time-variation of model parameters is governed by the limited memory + Markov process. Given the non-trivial nature of the likelihood + function and the amount of model parameters, Julia is an ideal + language for implementing this class of models due to its + computational performance.

+

Currently, the package provides model estimation with a combination + of switching or non-switching intercept, error variance and exogenous + variables. The transition matrix can be either constant or + time-varying. The package also provides a set of functions for model + diagnostics and forecasting. Further development of the package is + considered, conditional on the interest in thereof.

+ + + Statement of need +

The Markov switching regression (also referred to as regime + switching) was first introduced in the seminal work of Hamilton + (1989). + Since then, it has been extensively used in empirical research. + Although the model was introduced as an application to economic data, + the range of applications has expanded significantly since the first + publication. These fields include finance + (Buffington + & Elliott, 2002), political science + (Brandt + et al., 2014), hydrology + (Wang + et al., 2023), epidemiology + (Shiferaw, + 2021) and even bibliometrics + (Delbianco + et al., 2020).

+

The popularity of these models among applied scientists and + industry professionals is reflected in the availability of + implementations. There are several packages in R + (R Core + Team, 2017) such as MSwM + (Josep + A. Sanchez-Espigares, 2021) or dynr + (Ou et al., + 2019). For the Python language, the Markov switching model is + implemented as part of the statsmodels package + (Seabold + & Perktold, 2010). MATLAB users may also estimate these + models with the MS_Regress + (Perlin, + 2012) package. Most of the well-established closed-source + statistical applications also have their own implementations of Markov + switching models. These include EViews, Stata, and SAS.

+

Despite the popularity of the method, + MarSwitching.jl is, at the moment, the only + package that allows for estimation of Markov switching models with the + Julia programming language by specifying a minimal set of regime + switching parameters. At the same time, it is implemented purely in + this language. For more general modeling with hidden Markov models, + Julia users may find the HiddenMarkovModels.jl + (Dalle, + 2024) package useful as well. + HiddenMarkovModels.jl offers a more generic + approach to programming hidden Markov models, albeit requiring + user-side development of certain estimation algorithms for Markov + switching models, as well as model inference functions.

+ + + Background +

Markov switching models are a class of regression models that allow + for time variation of parameters in an otherwise linear model. More + specifically, the current state is determined only by the state from + the previous period, which is described in the transition matrix.

+

Consider a general model:

+

+ + 𝐲t=𝐗t,iβS,i+ϵt + + + ϵ∼f(0,Σs)

+

where + + 𝐲t + is + + N-vector + of the dependent variable indexed by time + + + t, + + + 𝐗t,i + is + + N×M + matrix of exogenous regressors, + + βS,i + is + + K-vector + of parameters, and + + ϵt + is + + N-vector + of errors. The errors are distributed according to some distribution + + + f(0,Σs) + with zero mean and covariance matrix + + Σs. + The state + + S + is a latent (unobservable) variable that can take values from + + + 1 + to + + K. + Parameters indexed by + + S + are different for each state.

+

The state + + St + is governed by the Markov process. The probability of transition from + state + + i + to state + + j + is given by the + + K×K + left-stochastic transition matrix + + 𝐏:

+

+ + 𝐏=P(St=i|St−1=j)=(p1,1p1,2⋯p1,kp2,1p2,2⋯p2,k⋮⋮⋱⋮pk,1pk,2⋯pk,k)

+

with standard constraints: + + 0<pi,j<1,∀j,i∈{1,…,K} + and + + ∑iKpi,j∀j∈{1,…,K}.

+

In a standard model, the transition matrix is assumed to be + constant over time. However, it is possible to allow for time + variation of the transition matrix itself, as described in + (Filardo, + 1994) (and as implemented in the package). In this case, each + of the transition probabilities is modeled as a function of the + exogenous variables + + 𝐙t:

+

+ + pi,j,t=exp(𝐙tδi,j)∑j=1exp(𝐙tδi,j)

+

where + + δi,j + is a vector of coefficients. The exponentiation and sum division of + the coefficients ensure that the probabilities are non-negative and + sum up to one. For this model, the expected duration of the state is + time-varying as well.

+ + + Quick start +

The package allows for simulation of data from the Markov switching + model. The user can specify the number of states, observations, and + model parameters (both transition and regression parameters). The + package will return a simulated dataset and the standardized exogenous + variables.

+ using MarSwitching +using Random +import Statistics: quantile + +k = 2 # number of regimes +T = 400 # number of generated observations +μ = [1.0, -0.5] # regime-switching intercepts +β = [-1.5, 0.0] # regime-switching coefficient for β +σ = [1.1, 0.8] # regime-switching standard deviation +P = [0.9 0.05 # transition matrix (left-stochastic) + 0.1 0.95] + +Random.seed!(123) + +# generate artificial data with given parameters +y, s_t, X = generate_msm(μ, σ, P, T, β = β) +

The model is estimated using MSModel() + function. The user needs to specify the dependent variable + y, the number of states + k. The exogenous variables are passed to either + the exog_vars or the + exog_switching_vars argument, depending wether + the variable is expected to have a switching parameter. In a similar + vein the user may pass an exogenous variable for the time-varying + transition matrix into exog_tvtp. However, in + order to have an intercept the column of ones needs to be added + explicitly.

+ # estimate the model +model = MSModel(y, k, intercept = "switching", exog_switching_vars = X[:,2]) +

Thanks to Julia’s multiple dispatch, the + generate_msm() function works by either + providing the parameters as in the first code chunk or using the + previously estimated model. This is useful, e.g., for assessing the + statistical properties of the model by Monte Carlo simulation.

+ quantile(generate_msm(model, 1000)[1], 0.05) +

There are several functions for printing statistics of the + estimated model. Each of the functions has a + digits argument specifying a rounding number. + state_coeftable() shows model coefficients’ + statistics for a given state and the expected duration of the state. + For a standard model with constant transition matrix, the function + transition_mat() prints a formatted matrix of + estimated transition probabilities. For models with time-varying + transition probabilities, the coefficients can be inspected with + coeftable_tvtp(). The function + summary_mars() prints all the relevant + information about the model for each of the states. Additionally, it + shows basic information about the model and fitness statistics.

+

The package also provides functions for filtered transition + probabilities + + P(St=i|Ψt) + and smoothed ones + + P(St=i|ΨT) + (Kim, + 1994). The former is estimated using the data available up to + time + + t, + while the latter is estimated using the full sample information in a + backward fashion, starting from + + T, + + + T−1, + + + ... + and so on. The functions to obtain these probability vectors are + filtered_probs() and + smoothed_probs(), respectively.

+ using Plots + +plot(filtered_probs(model), + label = ["Regime 1" "Regime 2"], + title = "Regime probabilities", + linewidth = 2) +

Figure + [fig:example] + presents the output of the code above.

+ +

Filtered probabilites. +

+ + +

The package also provides a function for forecasting the dependent + variable. However, for the Markov switching models, the prediction is + not as intuitive as in less complex models. The reason is that the + model also requires a forecast of state at time + + + t+1.

+

predict() function returns the forecasted + values either calculated in the instantaneous way:

+

+ + ŷt=∑i=1kξ̂i,tXt′β̂i

+

or as a one step ahead forecast, where the states are predicted + themselves:

+

+ + ŷt+1=∑i=1k(Pξ̂i,t)Xt+1′β̂i

+

For more details, the user is referred to the package + documentation. + Alternatively, in order to inspect the description of a particular + function, the help operator - ? in Julia’s REPL + may come in handy (e.g., ?MSModel).

+ + + Acknowledgements +

This open-source research software project received no financial + support.

+ + + + + + + + + BezansonJeff + EdelmanAlan + KarpinskiStefan + ShahViral B + + Julia: A fresh approach to numerical computing + SIAM review + SIAM + 2017 + 59 + 1 + https://doi.org/10.1137/141000671 + 10.1137/141000671 + 65 + 98 + + + + + + HamiltonJames D. + + A new approach to the economic analysis of nonstationary time series and the business cycle + Econometrica + [Wiley, Econometric Society] + 1989 + 20231010 + 57 + 2 + http://www.jstor.org/stable/1912559 + 10.2307/1912559 + 357 + 384 + + + + + + BuffingtonJohn + ElliottRobert J. + + American options with regime switching + International Journal of Theoretical and Applied Finance + 2002 + 05 + 05 + https://doi.org/10.1142/S0219024902001523 + 10.1142/S0219024902001523 + 497 + 514 + + + + + + BrandtPatrick T. + FreemanJohn R. + SchrodtPhilip A. + + Evaluating forecasts of political conflict dynamics + International Journal of Forecasting + 2014 + 30 + 4 + 0169-2070 + https://www.sciencedirect.com/science/article/pii/S0169207014000612 + 10.1016/j.ijforecast.2014.03.014 + 944 + 962 + + + + + + WangHuimin + SongSongbai + ZhangGengxi + AyantobocOlusola O. + + Predicting daily streamflow with a novel multi-regime switching ARIMA-MS-GARCH model + Journal of Hydrology: Regional Studies + 2023 + 47 + 2214-5818 + https://www.sciencedirect.com/science/article/pii/S2214581823000617 + 10.1016/j.ejrh.2023.101374 + 101374 + + + + + + + ShiferawYegnanew A. + + Regime shifts in the COVID-19 case fatality rate dynamics: A Markov-switching autoregressive model analysis + Chaos, Solitons & Fractals: X + 2021 + 6 + 2590-0544 + https://www.sciencedirect.com/science/article/pii/S259005442100004X + 10.1016/j.csfx.2021.100059 + 100059 + + + + + + + DelbiancoFernando + FioritiAndrés + Hernandez-ChantoAllan + TohméFernando + + A Markov-switching approach to the study of citations in academic journals + Journal of Informetrics + 2020 + 14 + 4 + 1751-1577 + https://www.sciencedirect.com/science/article/pii/S1751157720301851 + 10.1016/j.joi.2020.101081 + 101081 + + + + + + + R Core Team + + R: A language and environment for statistical computing + R Foundation for Statistical Computing + Vienna, Austria + 2017 + https://www.R-project.org/ + + + + + + Josep A. Sanchez-EspigaresAlberto Lopez-Moreno + + MSwM: Fitting Markov switching models + 2021 + https://cran.r-project.org/package=MSwM + 10.32614/cran.package.mswm + + + + + + OuLu + HunterMichael D. + ChowSy-Miin + + What’s for dynr: A package for linear and nonlinear dynamic modeling in R + The R Journal + 2019 + 11 + 10.32614/rj-2019-012 + 1 + 20 + + + + + + SeaboldSkipper + PerktoldJosef + + Statsmodels: Econometric and statistical modeling with Python + 9th python in science conference + 2010 + 10.25080/majora-92bf1922-011 + + + + + + PerlinMarcelo + + MS_regress - the MATLAB package for Markov regime switching models + 2012 + https://github.com/msperlin/MS\_Regress-Matlab + 10.2139/ssrn.1714016 + + + + + + DalleGuillaume + + HiddenMarkovModels.jl: Generic, fast and reliable state space modeling + Journal of Open Source Software + The Open Journal + 2024 + 9 + 96 + https://doi.org/10.21105/joss.06436 + 10.21105/joss.06436 + 6436 + + + + + + + FilardoAndrew J. + + Business-cycle phases and their transitional dynamics + Journal of Business & Economic Statistics + [American Statistical Association, Taylor & Francis, Ltd.] + 1994 + 20231011 + 12 + 3 + 10.2307/1392086 + 299 + 308 + + + + + + KimChang-Jin + + Dynamic linear models with Markov-switching + Journal of Econometrics + 1994 + 60 + 1 + 0304-4076 + https://www.sciencedirect.com/science/article/pii/0304407694900361 + 10.1016/0304-4076(94)90036-1 + 1 + 22 + + + + +
diff --git a/joss.06441/paper.jats/regime_probs.png b/joss.06441/paper.jats/regime_probs.png new file mode 100644 index 0000000000..77b0829650 Binary files /dev/null and b/joss.06441/paper.jats/regime_probs.png differ