<div align="center">
<h1>Pyriodicity</h1>
[](https://pypi.org/project/pyriodicity/)
[](https://codecov.io/gh/iskandergaba/pyriodicity)
[](https://pyriodicity.readthedocs.io/en/latest)
[](https://github.com/iskandergaba/pyriodicity/actions/workflows/ci.yml)
Pyriodicity provides an intuitive and efficient Python implementation of periodicity length detection methods in univariate signals. You can check the supported detection methods in the [API Reference](https://pyriodicity.readthedocs.io/en/stable/api.html).
</div>
## Installation
To install ``pyriodicity``, simply run:
```shell
pip install pyriodicity
```
To install the latest development version, you can run:
```shell
pip install git+https://github.com/iskandergaba/pyriodicity.git
```
## Usage
Please refer to the [package documentation](https://pyriodicity.readthedocs.io) for more information.
For this example, start by loading Mauna Loa Weekly Atmospheric CO2 Data from [`statsmodels`](https://www.statsmodels.org) and downsampling its data to a monthly frequency.
```python
>>> from statsmodels.datasets import co2
>>> data = co2.load().data
>>> data = data.resample("ME").mean().ffill()
```
Use `Autoperiod` to find the list of periodicity lengths in this data, if any.
```python
>>> from pyriodicity import Autoperiod
>>> Autoperiod.detect(data)
array([12])
```
The detected periodicity length is 12 which suggests a strong yearly seasonality given that the data has a monthly frequency.
We can also use online detection methods for data streams as follows.
```python
>>> from pyriodicity import OnlineACFPeriodicityDetector
>>> data_stream = (sample for sample in data.values)
>>> detector = OnlineACFPeriodicityDetector(window_size=128)
>>> for sample in data_stream:
... periods = detector.detect(sample)
>>> 12 in periods
True
```
All the supported periodicity detection methods can be used in the same manner as in the examples above with different optional parameters. Check the [API Reference](https://pyriodicity.readthedocs.io/en/stable/api.html) for more details.
## References
1. Hyndman, R.J., & Athanasopoulos, G. (2021). Forecasting: principles and practice, 3rd edition, OTexts: Melbourne, Australia. [OTexts.com/fpp3](https://otexts.com/fpp3). Accessed on 09-15-2024.
2. Vlachos, M., Yu, P., & Castelli, V. (2005). On periodicity detection and Structural Periodic similarity. Proceedings of the 2005 SIAM International Conference on Data Mining. [doi.org/10.1137/1.9781611972757.40](https://doi.org/10.1137/1.9781611972757.40).
3. Puech, T., Boussard, M., D'Amato, A., & Millerand, G. (2020). A fully automated periodicity detection in time series. In Advanced Analytics and Learning on Temporal Data: 4th ECML PKDD Workshop, AALTD 2019, Würzburg, Germany, September 20, 2019, Revised Selected Papers 4 (pp. 43-54). Springer International Publishing. [doi.org/10.1007/978-3-030-39098-3_4](https://doi.org/10.1007/978-3-030-39098-3_4).
4. Toller, M., Santos, T., & Kern, R. (2019). SAZED: parameter-free domain-agnostic season length estimation in time series data. Data Mining and Knowledge Discovery, 33(6), 1775-1798. [doi.org/10.1007/s10618-019-00645-z](https://doi.org/10.1007/s10618-019-00645-z).
5. Wen, Q., He, K., Sun, L., Zhang, Y., Ke, M., & Xu, H. (2021, June). RobustPeriod: Robust time-frequency mining for multiple periodicity detection. In Proceedings of the 2021 international conference on management of data (pp. 2328-2337). [doi.org/10.1145/3448016.3452779](https://doi.org/10.1145/3448016.3452779).
Raw data
{
"_id": null,
"home_page": null,
"name": "pyriodicity",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "period, periodicity, seasonality, period-detection, periodicity-analysis, seasonality-analysis, autoperiod, cfd-autoperiod, robustperiod, sazed, signal-processing, time-series-analysis",
"author": "Iskander Gaba",
"author_email": "iskander@hey.com",
"download_url": "https://files.pythonhosted.org/packages/ca/c0/6b98014915f01da860ef1078480cae6bacf5757d5dcac61b8f529e85f67c/pyriodicity-0.6.2.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n<h1>Pyriodicity</h1>\n\n[](https://pypi.org/project/pyriodicity/)\n\n\n[](https://codecov.io/gh/iskandergaba/pyriodicity)\n[](https://pyriodicity.readthedocs.io/en/latest)\n[](https://github.com/iskandergaba/pyriodicity/actions/workflows/ci.yml)\n\nPyriodicity provides an intuitive and efficient Python implementation of periodicity length detection methods in univariate signals. You can check the supported detection methods in the [API Reference](https://pyriodicity.readthedocs.io/en/stable/api.html).\n</div>\n\n## Installation\nTo install ``pyriodicity``, simply run:\n```shell\npip install pyriodicity\n```\n\nTo install the latest development version, you can run:\n```shell\npip install git+https://github.com/iskandergaba/pyriodicity.git\n```\n\n## Usage\nPlease refer to the [package documentation](https://pyriodicity.readthedocs.io) for more information.\n\nFor this example, start by loading Mauna Loa Weekly Atmospheric CO2 Data from [`statsmodels`](https://www.statsmodels.org) and downsampling its data to a monthly frequency.\n```python\n>>> from statsmodels.datasets import co2\n>>> data = co2.load().data\n>>> data = data.resample(\"ME\").mean().ffill()\n```\n\nUse `Autoperiod` to find the list of periodicity lengths in this data, if any.\n```python\n>>> from pyriodicity import Autoperiod\n>>> Autoperiod.detect(data)\narray([12])\n```\n\nThe detected periodicity length is 12 which suggests a strong yearly seasonality given that the data has a monthly frequency.\n\nWe can also use online detection methods for data streams as follows.\n```python\n>>> from pyriodicity import OnlineACFPeriodicityDetector\n>>> data_stream = (sample for sample in data.values)\n>>> detector = OnlineACFPeriodicityDetector(window_size=128)\n>>> for sample in data_stream:\n... periods = detector.detect(sample)\n>>> 12 in periods\nTrue\n```\n\nAll the supported periodicity detection methods can be used in the same manner as in the examples above with different optional parameters. Check the [API Reference](https://pyriodicity.readthedocs.io/en/stable/api.html) for more details.\n\n## References\n1. Hyndman, R.J., & Athanasopoulos, G. (2021). Forecasting: principles and practice, 3rd edition, OTexts: Melbourne, Australia. [OTexts.com/fpp3](https://otexts.com/fpp3). Accessed on 09-15-2024.\n2. Vlachos, M., Yu, P., & Castelli, V. (2005). On periodicity detection and Structural Periodic similarity. Proceedings of the 2005 SIAM International Conference on Data Mining. [doi.org/10.1137/1.9781611972757.40](https://doi.org/10.1137/1.9781611972757.40).\n3. Puech, T., Boussard, M., D'Amato, A., & Millerand, G. (2020). A fully automated periodicity detection in time series. In Advanced Analytics and Learning on Temporal Data: 4th ECML PKDD Workshop, AALTD 2019, W\u00fcrzburg, Germany, September 20, 2019, Revised Selected Papers 4 (pp. 43-54). Springer International Publishing. [doi.org/10.1007/978-3-030-39098-3_4](https://doi.org/10.1007/978-3-030-39098-3_4).\n4. Toller, M., Santos, T., & Kern, R. (2019). SAZED: parameter-free domain-agnostic season length estimation in time series data. Data Mining and Knowledge Discovery, 33(6), 1775-1798. [doi.org/10.1007/s10618-019-00645-z](https://doi.org/10.1007/s10618-019-00645-z).\n5. Wen, Q., He, K., Sun, L., Zhang, Y., Ke, M., & Xu, H. (2021, June). RobustPeriod: Robust time-frequency mining for multiple periodicity detection. In Proceedings of the 2021 international conference on management of data (pp. 2328-2337). [doi.org/10.1145/3448016.3452779](https://doi.org/10.1145/3448016.3452779).\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Pyriodicity provides an intuitive and efficient Python implementation of periodicity length detection methods in univariate signals.",
"version": "0.6.2",
"project_urls": {
"Documentation": "https://pyriodicity.readthedocs.io",
"Repository": "https://github.com/iskandergaba/pyriodicity"
},
"split_keywords": [
"period",
" periodicity",
" seasonality",
" period-detection",
" periodicity-analysis",
" seasonality-analysis",
" autoperiod",
" cfd-autoperiod",
" robustperiod",
" sazed",
" signal-processing",
" time-series-analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c1533950f139e0524cd81e049e6173d3f251733b843bfaa6c95e103c5660b440",
"md5": "6bf572863f33cac59b676f89a19ba0bb",
"sha256": "0ad39efe4d1d0600297c0072675033da35d172e3723ea6726822e68be3b33b60"
},
"downloads": -1,
"filename": "pyriodicity-0.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6bf572863f33cac59b676f89a19ba0bb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 29896,
"upload_time": "2025-10-12T23:14:29",
"upload_time_iso_8601": "2025-10-12T23:14:29.180001Z",
"url": "https://files.pythonhosted.org/packages/c1/53/3950f139e0524cd81e049e6173d3f251733b843bfaa6c95e103c5660b440/pyriodicity-0.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cac06b98014915f01da860ef1078480cae6bacf5757d5dcac61b8f529e85f67c",
"md5": "a661d53f3bc827dad4385f3b66f12887",
"sha256": "3acbb800ce2b881b4dae35ce981365608836ca14fda3eff6836b680de60d7fa8"
},
"downloads": -1,
"filename": "pyriodicity-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "a661d53f3bc827dad4385f3b66f12887",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19628,
"upload_time": "2025-10-12T23:14:30",
"upload_time_iso_8601": "2025-10-12T23:14:30.245125Z",
"url": "https://files.pythonhosted.org/packages/ca/c0/6b98014915f01da860ef1078480cae6bacf5757d5dcac61b8f529e85f67c/pyriodicity-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-12 23:14:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "iskandergaba",
"github_project": "pyriodicity",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "pyriodicity"
}
JSON
