*Note: An explanation of the application of JMs to the value factor in this figure can be found in the* [Examples](#usage-and-examples) *section.*
# `jumpmodels`: Python Library for Statistical Jump Models
`jumpmodels` is a Python library offering a collection of statistical jump models (JMs), an unsupervised algorithm designed for regime identification in time series data.
It includes implementations of the original discrete JM, the continuous JM (CJM), and the sparse JM (SJM) with feature selection.
The library follows a [`scikit-learn`](https://github.com/scikit-learn/scikit-learn)-style API and supports `pandas` DataFrames for both input and output.
---
- [Installation](#installation)
- [Usage & Examples](#usage-and-examples)
- [References & Citations](#references-and-citations)
- [Contributing](#contributing)
- [Credits & Related Repo](#credits-and-related-repo)
- [License](#license)
## Installation
To install the package, use the following [pip](https://pip.pypa.io/en/stable/) command:
```bash
pip install jumpmodels
```
`jumpmodels` requires the following dependencies:
- Python `(>=3.8)`
- `numpy`
- `pandas`
- `scipy`
- `scikit-learn`
- `matplotlib`
All dependencies will be installed automatically with the package. While version sensitivity is minimal, an `environment.yaml` file is provided to ensure reproducibility.
To run the example notebook, you will also need the following additional dependencies:
- `yfinance`
- `jupyterlab`
You can install these along with the package by running:
```bash
pip install jumpmodels[example]
```
## Usage and Examples
You can import the two core classes, `JumpModel` and `SparseJumpModel`, as follows:
```python
from jumpmodels.jump import JumpModel # JM & CJM class
from jumpmodels.sparse_jump import SparseJumpModel # Sparse JM class
```
We follow a `scikit-learn`-style API, with class methods such as `.fit()`, `.predict()`, `.predict_proba()`, and `.set_params()` for model fitting, state and probability prediction, and resetting model parameters.
Specifically designed for time series applications, we also provide `.predict_online()` and `.predict_proba_online()` methods for online prediction.
A comprehensive demonstration of the core functionality is available in the `examples/Nasdaq/example.ipynb` notebook, which includes an analysis of the Nasdaq-100 Index using data from [Yahoo Finance](https://finance.yahoo.com/quote/%5ENDX/) (fully public source).
The figure on top features an application of the sparse JM, showing the in-sample identified bull and bear market regimes for the value factor index based on its daily active returns relative to the market.
Further details can be found in Shu and Mulvey (2024), as listed in the [References](#factor) section.
## References and Citations
Below are articles related to the methodology and applications of JMs.
If any of them assist your research, please cite the corresponding paper.
### JM Methodology
- **Continuous Statistical Jump Models** (CJM): Aydınhan, A. O., Kolm, P. N., Mulvey, J. M., and Shu, Y. (2024). Identifying patterns in financial markets: Extending the statistical jump model for regime identification. *Annals of Operations Research*. To appear. [[journal](https://link.springer.com/article/10.1007/s10479-024-06035-z)] [[SSRN](https://papers.ssrn.com/abstract=4556048)]
```bibtex
@article{Aydinhan2024CJM,
title = {Identifying patterns in financial markets: extending the statistical jump model for regime identification},
author = {Afşar Onat Aydınhan and Petter N. Kolm and John M. Mulvey and Yizhan Shu},
journal = {Annals of Operations Research},
year = {2024},
note = {To appear},
doi = {https://doi.org/10.1007/s10479-024-06035-z},
}
```
- (Original) **Statistical Jump Models**: Nystrup, P., Lindström, E., and Madsen, H. (2020a). Learning hidden Markov models with persistent states by penalizing jumps. *Expert Systems with Applications*, 150:113307. [[journal](https://www.sciencedirect.com/science/article/abs/pii/S0957417420301329)] [[OpenAccess](https://orbit.dtu.dk/files/255194701/Learning_hidden_Markov_models_with_persistent_states_by_penalizing_jumps_ACCEPTED_ESWA.pdf)]
```bibtex
@article{Nystrup2020JM,
title = {Learning hidden {Markov} models with persistent states by penalizing jumps},
author = {Peter Nystrup and Erik Lindstr{\"o}m and Henrik Madsen},
journal = {Expert Systems with Applications},
year = {2020},
pages = {113307},
volume = {150},
doi = {https://doi.org/10.1016/j.eswa.2020.113307},
}
```
- **Sparse Jump Models**: Nystrup, P., Kolm, P. N., and Lindström, E. (2021). Feature selection in jump models. *Expert Systems with Applications*, 184:115558. [[journal](https://www.sciencedirect.com/science/article/pii/S0957417421009647)] [[SSRN](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3805831)]
```bibtex
@article{nystrup2021SJM,
title = {Feature selection in jump models},
author = {Peter Nystrup and Petter N. Kolm and Erik Lindstr{\"o}m},
journal = {Expert Systems with Applications},
volume = {184},
pages = {115558},
year = {2021},
doi = {https://doi.org/10.1016/j.eswa.2021.115558},
}
```
- **Online Inference for JMs**: Nystrup, P., Kolm, P. N., and Lindström, E. (2020b). Greedy online classification of persistent market states using realized intraday volatility features. *The Journal of Financial Data Science*, 2(3):25–39. [[journal](https://www.pm-research.com/content/iijjfds/2/3/25)] [[OpenAccess](https://backend.orbit.dtu.dk/ws/portalfiles/portal/242396317/Greedy_online_classification_of_persistent_market_states_using_realized_intraday_volatility_features.pdf)]
```bibtex
@article{Nystrup2020onlineJM,
title = {Greedy Online Classification of Persistent Market States Using Realized Intraday Volatility Features},
author = {Peter Nystrup and Petter N. Kolm and Erik Lindstr{\"o}m},
journal = {The Journal of Financial Data Science}
year = {2020},
volume = {2},
number = {3},
pages = {25--39},
doi = {https://doi.org/10.3905/jfds.2020.2.3.025},
}
```
### JM Applications
- **Downside Risk Recution**: Shu, Y., Yu, C., and Mulvey, J. M. (2024a). Downside risk reduction using regime-switching signals: A statistical jump model approach. *Journal of Asset Management*. To appear. [[journal](https://link.springer.com/article/10.1057/s41260-024-00376-x)] [[SSRN](https://ssrn.com/abstract=4719989)]
```bibtex
@article{Shu2024downside,
title = {Downside Risk Reduction Using Regime-Switching Signals: A Statistical Jump Model Approach},
author = {Shu, Yizhan and Yu, Chenyu and Mulvey, John M.},
journal = {Journal of Asset Management},
year = {2024},
note = {To appear},
doi = {https://doi.org/10.1057/s41260-024-00376-x},
}
```
- **Dynamic Asset Allocation**: Shu, Y., Yu, C., and Mulvey, J. M. (2024b). Dynamic asset allocation with asset-specific regime forecasts. *Annals of Operations Research*. To appear. [[journal](https://link.springer.com/article/10.1007/s10479-024-06266-0)] [[SSRN](https://ssrn.com/abstract=4864358)]
```bibtex
@article{Shu2024DAA,
title = {Dynamic Asset Allocation with Asset-Specific Regime Forecasts},
author = {Shu, Yizhan and Yu, Chenyu and Mulvey, John M.},
journal = {Annals of Operations Research},
year = {2024},
note = {To appear},
doi = {https://doi.org/10.1007/s10479-024-06266-0},
}
```
- <a id="factor"></a> **Dynamic Factor Allocation**: Shu, Y. and Mulvey, J. M. (2024). Dynamic Factor Allocation Leveraging Regime-Switching Signals. [[SSRN](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=4960484)]
```bibtex
@article{Shu2024factor,
title = {Dynamic Factor Allocation Leveraging Regime-Switching Signals},
author = {Shu, Yizhan and Mulvey, John M.},
journal = {SSRN},
year = {2024},
}
```
## Contributing
Pull requests and open issues are welcome. I am happy to discuss any related questions.
## Credits and Related Repo
This library builds upon the open-source [code](https://www.sciencedirect.com/science/article/pii/S0957417421009647#appSB) accompanying Nystrup et al. (2021).
The GitHub [Repo](https://github.com/FedericoCortese/GIC-for-SJM) by Federico P. Cortese implements the generalized information criteria (GIC) for high-dimensional SJMs, detailed in Cortese, F. P., Kolm, P. N., and Lindström, E. (2024). Generalized information criteria for high-dimensional sparse statistical jump models [[SSRN](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=4774429)].
The structure of this README file is inspired by the format used in [`cvxpylayers`](https://github.com/cvxgrp/cvxpylayers).
## License
Our library carries an Apache 2.0 license.
Raw data
{
"_id": null,
"home_page": null,
"name": "jumpmodels",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "regime, regime switching, jump models, clustering, time series, financial data",
"author": null,
"author_email": "Yizhan Shu <olivershu98@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6d/5b/08f39c8acbf6d2fcff1e1556aad86db1a10fdf1aa3b117eea46f7105d9fe/jumpmodels-0.1.1.tar.gz",
"platform": null,
"description": "\n\n*Note: An explanation of the application of JMs to the value factor in this figure can be found in the* [Examples](#usage-and-examples) *section.*\n\n# `jumpmodels`: Python Library for Statistical Jump Models\n\n\n`jumpmodels` is a Python library offering a collection of statistical jump models (JMs), an unsupervised algorithm designed for regime identification in time series data. \nIt includes implementations of the original discrete JM, the continuous JM (CJM), and the sparse JM (SJM) with feature selection. \nThe library follows a [`scikit-learn`](https://github.com/scikit-learn/scikit-learn)-style API and supports `pandas` DataFrames for both input and output.\n\n\n\n---\n\n- [Installation](#installation)\n- [Usage & Examples](#usage-and-examples)\n- [References & Citations](#references-and-citations)\n- [Contributing](#contributing)\n- [Credits & Related Repo](#credits-and-related-repo)\n- [License](#license)\n\n\n\n\n## Installation\n\nTo install the package, use the following [pip](https://pip.pypa.io/en/stable/) command:\n\n```bash\npip install jumpmodels\n```\n\n\n`jumpmodels` requires the following dependencies:\n\n- Python `(>=3.8)`\n- `numpy`\n- `pandas`\n- `scipy`\n- `scikit-learn`\n- `matplotlib`\n\nAll dependencies will be installed automatically with the package. While version sensitivity is minimal, an `environment.yaml` file is provided to ensure reproducibility.\n\nTo run the example notebook, you will also need the following additional dependencies:\n\n- `yfinance`\n- `jupyterlab`\n\nYou can install these along with the package by running:\n\n```bash\npip install jumpmodels[example]\n```\n\n\n\n\n\n## Usage and Examples\n\nYou can import the two core classes, `JumpModel` and `SparseJumpModel`, as follows:\n\n```python\nfrom jumpmodels.jump import JumpModel # JM & CJM class\nfrom jumpmodels.sparse_jump import SparseJumpModel # Sparse JM class\n```\n\nWe follow a `scikit-learn`-style API, with class methods such as `.fit()`, `.predict()`, `.predict_proba()`, and `.set_params()` for model fitting, state and probability prediction, and resetting model parameters. \nSpecifically designed for time series applications, we also provide `.predict_online()` and `.predict_proba_online()` methods for online prediction.\n\n\nA comprehensive demonstration of the core functionality is available in the `examples/Nasdaq/example.ipynb` notebook, which includes an analysis of the Nasdaq-100 Index using data from [Yahoo Finance](https://finance.yahoo.com/quote/%5ENDX/) (fully public source).\n\nThe figure on top features an application of the sparse JM, showing the in-sample identified bull and bear market regimes for the value factor index based on its daily active returns relative to the market. \nFurther details can be found in Shu and Mulvey (2024), as listed in the [References](#factor) section.\n\n\n\n\n\n## References and Citations\n\nBelow are articles related to the methodology and applications of JMs. \nIf any of them assist your research, please cite the corresponding paper.\n\n### JM Methodology\n\n- **Continuous Statistical Jump Models** (CJM): Ayd\u0131nhan, A. O., Kolm, P. N., Mulvey, J. M., and Shu, Y. (2024). Identifying patterns in financial markets: Extending the statistical jump model for regime identification. *Annals of Operations Research*. To appear. [[journal](https://link.springer.com/article/10.1007/s10479-024-06035-z)] [[SSRN](https://papers.ssrn.com/abstract=4556048)]\n\n\n```bibtex\n@article{Aydinhan2024CJM,\n title = {Identifying patterns in financial markets: extending the statistical jump model for regime identification},\n author = {Af\u015far Onat Ayd\u0131nhan and Petter N. Kolm and John M. Mulvey and Yizhan Shu},\n journal = {Annals of Operations Research},\n year = {2024},\n note = {To appear},\n doi = {https://doi.org/10.1007/s10479-024-06035-z},\n}\n```\n\n\n- (Original) **Statistical Jump Models**: Nystrup, P., Lindstr\u00f6m, E., and Madsen, H. (2020a). Learning hidden Markov models with persistent states by penalizing jumps. *Expert Systems with Applications*, 150:113307. [[journal](https://www.sciencedirect.com/science/article/abs/pii/S0957417420301329)] [[OpenAccess](https://orbit.dtu.dk/files/255194701/Learning_hidden_Markov_models_with_persistent_states_by_penalizing_jumps_ACCEPTED_ESWA.pdf)]\n\n\n```bibtex\n@article{Nystrup2020JM,\n title = {Learning hidden {Markov} models with persistent states by penalizing jumps},\n author = {Peter Nystrup and Erik Lindstr{\\\"o}m and Henrik Madsen},\n journal = {Expert Systems with Applications},\n year = {2020},\n pages = {113307},\n volume = {150},\n doi = {https://doi.org/10.1016/j.eswa.2020.113307},\n}\n```\n\n\n- **Sparse Jump Models**: Nystrup, P., Kolm, P. N., and Lindstr\u00f6m, E. (2021). Feature selection in jump models. *Expert Systems with Applications*, 184:115558. [[journal](https://www.sciencedirect.com/science/article/pii/S0957417421009647)] [[SSRN](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3805831)]\n\n\n```bibtex\n@article{nystrup2021SJM,\n title = {Feature selection in jump models},\n author = {Peter Nystrup and Petter N. Kolm and Erik Lindstr{\\\"o}m},\n journal = {Expert Systems with Applications},\n volume = {184},\n pages = {115558},\n year = {2021},\n doi = {https://doi.org/10.1016/j.eswa.2021.115558},\n}\n```\n\n\n\n\n- **Online Inference for JMs**: Nystrup, P., Kolm, P. N., and Lindstr\u00f6m, E. (2020b). Greedy online classification of persistent market states using realized intraday volatility features. *The Journal of Financial Data Science*, 2(3):25\u201339. [[journal](https://www.pm-research.com/content/iijjfds/2/3/25)] [[OpenAccess](https://backend.orbit.dtu.dk/ws/portalfiles/portal/242396317/Greedy_online_classification_of_persistent_market_states_using_realized_intraday_volatility_features.pdf)]\n\n```bibtex\n@article{Nystrup2020onlineJM,\n title = {Greedy Online Classification of Persistent Market States Using Realized Intraday Volatility Features},\n author = {Peter Nystrup and Petter N. Kolm and Erik Lindstr{\\\"o}m},\n journal = {The Journal of Financial Data Science}\n year = {2020},\n volume = {2},\n number = {3},\n pages = {25--39},\n doi = {https://doi.org/10.3905/jfds.2020.2.3.025},\n}\n```\n\n\n### JM Applications\n\n\n- **Downside Risk Recution**: Shu, Y., Yu, C., and Mulvey, J. M. (2024a). Downside risk reduction using regime-switching signals: A statistical jump model approach. *Journal of Asset Management*. To appear. [[journal](https://link.springer.com/article/10.1057/s41260-024-00376-x)] [[SSRN](https://ssrn.com/abstract=4719989)]\n\n\n```bibtex\n@article{Shu2024downside,\n title = {Downside Risk Reduction Using Regime-Switching Signals: A Statistical Jump Model Approach},\n author = {Shu, Yizhan and Yu, Chenyu and Mulvey, John M.},\n journal = {Journal of Asset Management},\n year = {2024},\n note = {To appear},\n doi = {https://doi.org/10.1057/s41260-024-00376-x},\n}\n```\n\n\n\n\n- **Dynamic Asset Allocation**: Shu, Y., Yu, C., and Mulvey, J. M. (2024b). Dynamic asset allocation with asset-specific regime forecasts. *Annals of Operations Research*. To appear. [[journal](https://link.springer.com/article/10.1007/s10479-024-06266-0)] [[SSRN](https://ssrn.com/abstract=4864358)]\n\n```bibtex\n@article{Shu2024DAA,\n title = {Dynamic Asset Allocation with Asset-Specific Regime Forecasts},\n author = {Shu, Yizhan and Yu, Chenyu and Mulvey, John M.},\n journal = {Annals of Operations Research},\n year = {2024},\n note = {To appear},\n doi = {https://doi.org/10.1007/s10479-024-06266-0},\n}\n```\n\n\n\n\n- <a id=\"factor\"></a> **Dynamic Factor Allocation**: Shu, Y. and Mulvey, J. M. (2024). Dynamic Factor Allocation Leveraging Regime-Switching Signals. [[SSRN](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=4960484)]\n\n\n```bibtex\n@article{Shu2024factor,\n title = {Dynamic Factor Allocation Leveraging Regime-Switching Signals},\n author = {Shu, Yizhan and Mulvey, John M.},\n journal = {SSRN},\n year = {2024},\n}\n```\n\n\n\n## Contributing\n\nPull requests and open issues are welcome. I am happy to discuss any related questions.\n\n\n## Credits and Related Repo\n\nThis library builds upon the open-source [code](https://www.sciencedirect.com/science/article/pii/S0957417421009647#appSB) accompanying Nystrup et al. (2021).\n\nThe GitHub [Repo](https://github.com/FedericoCortese/GIC-for-SJM) by Federico P. Cortese implements the generalized information criteria (GIC) for high-dimensional SJMs, detailed in Cortese, F. P., Kolm, P. N., and Lindstr\u00f6m, E. (2024). Generalized information criteria for high-dimensional sparse statistical jump models [[SSRN](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=4774429)].\n\nThe structure of this README file is inspired by the format used in [`cvxpylayers`](https://github.com/cvxgrp/cvxpylayers). \n\n\n\n\n\n## License\n\nOur library carries an Apache 2.0 license.\n\n\n\n\n\n\n\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Statistical Jump Models in Python, with `scikit-learn`-style APIs",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/Yizhan-Oliver-Shu/jump-models",
"Issues": "https://github.com/Yizhan-Oliver-Shu/jump-models/issues"
},
"split_keywords": [
"regime",
" regime switching",
" jump models",
" clustering",
" time series",
" financial data"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5c9fb0eae26428d430fad2ee21a5ac512249055c6b5c0c6411fe870e6fdbe69a",
"md5": "ab3a9af061930c87c38b72faddd1aa4a",
"sha256": "89132e1308801ffac5a9d88ba000a842be61eb80c6746d683cbb0216db327047"
},
"downloads": -1,
"filename": "jumpmodels-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ab3a9af061930c87c38b72faddd1aa4a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 35158,
"upload_time": "2024-10-04T21:19:22",
"upload_time_iso_8601": "2024-10-04T21:19:22.157796Z",
"url": "https://files.pythonhosted.org/packages/5c/9f/b0eae26428d430fad2ee21a5ac512249055c6b5c0c6411fe870e6fdbe69a/jumpmodels-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6d5b08f39c8acbf6d2fcff1e1556aad86db1a10fdf1aa3b117eea46f7105d9fe",
"md5": "ede7b1bd111e46d77008fe70405003b8",
"sha256": "4d4ec6ceb8877a4fb1a148193dd6e2c6eaf761d26d613bd9ca64074cbb0d75ff"
},
"downloads": -1,
"filename": "jumpmodels-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "ede7b1bd111e46d77008fe70405003b8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 34099,
"upload_time": "2024-10-04T21:19:23",
"upload_time_iso_8601": "2024-10-04T21:19:23.891057Z",
"url": "https://files.pythonhosted.org/packages/6d/5b/08f39c8acbf6d2fcff1e1556aad86db1a10fdf1aa3b117eea46f7105d9fe/jumpmodels-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-04 21:19:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Yizhan-Oliver-Shu",
"github_project": "jump-models",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "jumpmodels"
}
JSON
