Pyriodicity

About Pyriodicity

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 page.

Installation

To install pyriodicity, simply run:

pip install pyriodicity

To install the latest development version, you can run:

pip install git+https://github.com/iskandergaba/pyriodicity.git

Usage

Please refer to the package documentation for more information.

For this example, start by loading Mauna Loa Weekly Atmospheric CO2 Data from statsmodels and downsampling its data to a monthly frequency.

>>> 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.

>>> 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.

>>> 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 for more details.

References

• [1] Hyndman, R.J., & Athanasopoulos, G. (2021) Forecasting: principles and practice, 3rd edition, OTexts: Melbourne, Australia. 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.
• [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.
• [4] 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). https://doi.org/10.1145/3448016.3452779.