pyriodicity 0.2.0__tar.gz

pyriodicity-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Iskander Gaba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyriodicity-0.2.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.1
+Name: pyriodicity
+Version: 0.2.0
+Summary: Pyriodicity provides intuitive and easy-to-use Python implementation for periodicity (seasonality) detection in univariate time series.
+Home-page: https://github.com/iskandergaba/pyriodicity
+License: MIT
+Keywords: signal,time,series,forecast,analysis,seasonality,trend,decomposition
+Author: Iskander Gaba
+Author-email: iskander@hey.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: scipy (>=1.14.0,<2.0.0)
+Project-URL: Repository, https://github.com/iskandergaba/pyriodicity
+Description-Content-Type: text/markdown
+
+<div align="center">
+<h1>Pyriodicity</h1>
+
+[![PyPI Version](https://img.shields.io/pypi/v/pyriodicity.svg?label=PyPI)](https://pypi.org/project/pyriodicity/)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyriodicity?label=Python)
+![GitHub License](https://img.shields.io/github/license/iskandergaba/pyriodicity?label=License)
+
+</div>
+
+
+## About Pyriodicity
+Pyriodicity provides intuitive and easy-to-use Python implementation for periodicity (seasonality) detection in univariate time series. Pyriodicity supports the following detection methods:
+- [Autocorrelation Function (ACF)](https://otexts.com/fpp3/acf.html)
+- [Autoperiod]( https://doi.org/10.1137/1.9781611972757.40)
+- [Fast Fourier Transform (FFT)](https://otexts.com/fpp3/useful-predictors.html#fourier-series)
+
+## Installation
+To install the latest version of `pyriodicity`, simply run:
+
+```shell
+pip install pyriodicity
+```
+
+## Example
+Start by loading a the `co2` timeseries emissions sample data from [`statsmodels`](https://www.statsmodels.org)
+```python
+from statsmodels.datasets import co2
+data = co2.load().data
+```
+
+You can then resample the data to whatever frequency you want. In this example, we downsample the data to a monthly frequency
+```python
+data = data.resample("ME").mean().ffill()
+```
+
+Use `Autoperiod` to find the list of periods based in this data (if any).
+```python
+from pyriodicity import Autoperiod
+autoperiod = Autoperiod(data)
+periods = autoperiod.fit()
+```
+
+There are multiple parameters you can play with should you wish to. For example, you can specify a lower percentile value for a more lenient detection
+```python
+autoperiod.fit(percentile=90)
+```
+
+Or increase the number of random data permutations for a better power threshold estimation
+```python
+autoperiod.fit(k=300)
+```
+
+Alternatively, you can use other periodicity detection methods such as `ACFPeriodicityDetector` and `FFTPeriodicityDetector` and compare results and performances.
+
+## Development Environment Setup
+This project is built and published using [Poetry](https://python-poetry.org). To setup a development environment for this project you can follow these steps:
+
+1. Install one of the compatible [Python](https://www.python.org) versions indicated above.
+2. Install [Poetry](https://python-poetry.org/docs/#installing-with-pipx).
+3. Navigate to the root folder and install dependencies in a virtual environment:
+```shell
+poetry install
+```
+4. If everything worked properly, you should have an environment under the name `pyriodicity-py3.*` activated. You can verify this by running:
+```shell
+poetry env list
+```
+5. You can run tests using the command:
+```shell
+poetry run pytest
+```
+6. To export the detailed dependency list, consider running the following:
+```shell
+# Add poetry-plugin-export plugin to poetry
+poetry self add poetry-plugin-export
+
+# Export the package dependencies to requirements.txt
+poetry export --output requirements.txt
+
+# If you wish to export all the dependencies, including those needed for testing, run the following command
+poetry export --with test --output requirements-dev.txt
+```
+
+## 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).
+

pyriodicity-0.2.0/README.md

@@ -0,0 +1,86 @@
+<div align="center">
+<h1>Pyriodicity</h1>
+
+[![PyPI Version](https://img.shields.io/pypi/v/pyriodicity.svg?label=PyPI)](https://pypi.org/project/pyriodicity/)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyriodicity?label=Python)
+![GitHub License](https://img.shields.io/github/license/iskandergaba/pyriodicity?label=License)
+
+</div>
+
+
+## About Pyriodicity
+Pyriodicity provides intuitive and easy-to-use Python implementation for periodicity (seasonality) detection in univariate time series. Pyriodicity supports the following detection methods:
+- [Autocorrelation Function (ACF)](https://otexts.com/fpp3/acf.html)
+- [Autoperiod]( https://doi.org/10.1137/1.9781611972757.40)
+- [Fast Fourier Transform (FFT)](https://otexts.com/fpp3/useful-predictors.html#fourier-series)
+
+## Installation
+To install the latest version of `pyriodicity`, simply run:
+
+```shell
+pip install pyriodicity
+```
+
+## Example
+Start by loading a the `co2` timeseries emissions sample data from [`statsmodels`](https://www.statsmodels.org)
+```python
+from statsmodels.datasets import co2
+data = co2.load().data
+```
+
+You can then resample the data to whatever frequency you want. In this example, we downsample the data to a monthly frequency
+```python
+data = data.resample("ME").mean().ffill()
+```
+
+Use `Autoperiod` to find the list of periods based in this data (if any).
+```python
+from pyriodicity import Autoperiod
+autoperiod = Autoperiod(data)
+periods = autoperiod.fit()
+```
+
+There are multiple parameters you can play with should you wish to. For example, you can specify a lower percentile value for a more lenient detection
+```python
+autoperiod.fit(percentile=90)
+```
+
+Or increase the number of random data permutations for a better power threshold estimation
+```python
+autoperiod.fit(k=300)
+```
+
+Alternatively, you can use other periodicity detection methods such as `ACFPeriodicityDetector` and `FFTPeriodicityDetector` and compare results and performances.
+
+## Development Environment Setup
+This project is built and published using [Poetry](https://python-poetry.org). To setup a development environment for this project you can follow these steps:
+
+1. Install one of the compatible [Python](https://www.python.org) versions indicated above.
+2. Install [Poetry](https://python-poetry.org/docs/#installing-with-pipx).
+3. Navigate to the root folder and install dependencies in a virtual environment:
+```shell
+poetry install
+```
+4. If everything worked properly, you should have an environment under the name `pyriodicity-py3.*` activated. You can verify this by running:
+```shell
+poetry env list
+```
+5. You can run tests using the command:
+```shell
+poetry run pytest
+```
+6. To export the detailed dependency list, consider running the following:
+```shell
+# Add poetry-plugin-export plugin to poetry
+poetry self add poetry-plugin-export
+
+# Export the package dependencies to requirements.txt
+poetry export --output requirements.txt
+
+# If you wish to export all the dependencies, including those needed for testing, run the following command
+poetry export --with test --output requirements-dev.txt
+```
+
+## 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).

pyriodicity-0.2.0/pyproject.toml

@@ -0,0 +1,25 @@
+[tool.poetry]
+name = "pyriodicity"
+version = "0.2.0"
+description = "Pyriodicity provides intuitive and easy-to-use Python implementation for periodicity (seasonality) detection in univariate time series."
+
+license = "MIT"
+readme = ["README.md"]
+repository = "https://github.com/iskandergaba/pyriodicity"
+
+authors = ["Iskander Gaba <iskander@hey.com>"]
+keywords = ["signal", "time", "series", "forecast", "analysis", "seasonality", "trend", "decomposition"]
+
+
+[tool.poetry.dependencies]
+python = "^3.10"
+scipy = "^1.14.0"
+
+
+[tool.poetry.group.test.dependencies]
+pytest = "^7.4.3"
+statsmodels = "^0.14.2"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

pyriodicity-0.2.0/pyriodicity/__init__.py

@@ -0,0 +1,7 @@
+from .detectors import (
+    ACFPeriodicityDetector,
+    Autoperiod,
+    FFTPeriodicityDetector,
+)
+
+__all__ = ["ACFPeriodicityDetector", "Autoperiod", "FFTPeriodicityDetector"]

pyriodicity-0.2.0/pyriodicity/detectors/__init__.py

@@ -0,0 +1,9 @@
+from .acf import ACFPeriodicityDetector
+from .autoperiod import Autoperiod
+from .fft import FFTPeriodicityDetector
+
+__all__ = [
+    "ACFPeriodicityDetector",
+    "Autoperiod",
+    "FFTPeriodicityDetector",
+]

pyriodicity-0.2.0/pyriodicity/detectors/acf.py

@@ -0,0 +1,117 @@
+from typing import Callable, Optional, Union
+
+from numpy.typing import ArrayLike, NDArray
+from scipy.signal import argrelmax
+
+from pyriodicity.tools import acf, apply_window, detrend, to_1d_array
+
+
+class ACFPeriodicityDetector:
+    """
+    Autocorrelation function (ACF) based periodicity detector.
+
+    Find the periods in a given signal or series using its ACF. A lag value
+    is considered a period if it is a local maximum of the ACF.
+
+    Parameters
+    ----------
+    endog : array_like
+        Data to be investigated. Must be squeezable to 1-d.
+
+    References
+    ----------
+    .. [1] Hyndman, R.J., & Athanasopoulos, G. (2021)
+    Forecasting: principles and practice, 3rd edition, OTexts: Melbourne, Australia.
+    OTexts.com/fpp3/acf.html. Accessed on 09-15-2024.
+
+    Examples
+    --------
+    Start by loading a timeseries datasets.
+
+    >>> from statsmodels.datasets import co2
+    >>> data = co2.load().data
+
+    You can resample the data to whatever frequency you want.
+
+    >>> data = data.resample("ME").mean().ffill()
+
+    Use ACFPeriodicityDetector to find the list of seasonality periods using the ACF.
+
+    >>> acf_detector = ACFPeriodicityDetector(data)
+    >>> periods = acf_detector.fit()
+
+    You can get the most prominent period by setting max_period_count to 1
+
+    >>> acf_detector.fit(max_period_count=1)
+
+    You can also use a different correlation function like Spearman
+
+    >>> acf_detector.fit(correlation_func="spearman")
+    """
+
+    def __init__(self, endog: ArrayLike):
+        self.y = to_1d_array(endog)
+
+    def fit(
+        self,
+        max_period_count: Optional[int] = None,
+        detrend_func: Optional[Union[str, Callable[[ArrayLike], NDArray]]] = "linear",
+        window_func: Optional[Union[str, float, tuple]] = None,
+        correlation_func: Optional[str] = "pearson",
+    ) -> NDArray:
+        """
+        Find periods in the given series.
+
+        Parameters
+        ----------
+        max_period_count : int, optional, default = None
+            Maximum number of periods to look for.
+        detrend_func : str, callable, default = None
+            The kind of detrending to be applied on the series. It can either be
+            'linear' or 'constant' if it the parameter is of 'str' type, or a
+            custom function that returns a detrended series.
+        window_func : float, str, tuple optional, default = None
+            Window function to be applied to the time series. Check
+            'window' parameter documentation for scipy.signal.get_window
+            function for more information on the accepted formats of this
+            parameter.
+        correlation_func : str, default = 'pearson'
+            The correlation function to be used to calculate the ACF of the time
+            series. Possible values are ['pearson', 'spearman', 'kendall'].
+
+        See Also
+        --------
+        scipy.signal.detrend
+            Remove linear trend along axis from data.
+        scipy.signal.get_window
+            Return a window of a given length and type.
+        scipy.stats.kendalltau
+            Calculate Kendall's tau, a correlation measure for ordinal data.
+        scipy.stats.pearsonr
+            Pearson correlation coefficient and p-value for testing non-correlation.
+        scipy.stats.spearmanr
+            Calculate a Spearman correlation coefficient with associated p-value.
+
+
+        Returns
+        -------
+        NDArray
+            List of detected periods.
+        """
+        # Detrend data
+        self.y = self.y if detrend_func is None else detrend(self.y, detrend_func)
+
+        # Apply window on data
+        self.y = self.y if window_func is None else apply_window(self.y, window_func)
+
+        # Compute the ACF
+        acf_arr = acf(self.y, len(self.y) // 2, correlation_func)
+
+        # Find the local argmax of the first half of the ACF array
+        local_argmax = argrelmax(acf_arr)[0]
+
+        # Argsort the local maxima in the ACF array in a descending order
+        periods = local_argmax[acf_arr[local_argmax].argsort()][::-1]
+
+        # Return the requested maximum count of detected periods
+        return periods[:max_period_count]

pyriodicity-0.2.0/pyriodicity/detectors/autoperiod.py

@@ -0,0 +1,242 @@
+from typing import Callable, Optional, Union
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy.signal import argrelmax, periodogram
+from scipy.stats import linregress
+
+from pyriodicity.tools import acf, apply_window, detrend, to_1d_array
+
+
+class Autoperiod:
+    """
+    Autoperiod periodicity detector.
+
+    Find the periods in a given signal or series using Autoperiod.
+
+    Parameters
+    ----------
+    endog : array_like
+        Data to be investigated. Must be squeezable to 1-d.
+
+    References
+    ----------
+    .. [1] Vlachos, M., Yu, P., & Castelli, V. (2005).
+    On periodicity detection and Structural Periodic similarity.
+    Proceedings of the 2005 SIAM International Conference on Data Mining.
+    https://doi.org/10.1137/1.9781611972757.40
+
+    Examples
+    --------
+    Start by loading a timeseries dataset.
+
+    >>> from statsmodels.datasets import co2
+    >>> data = co2.load().data
+
+    You can resample the data to whatever frequency you want.
+
+    >>> data = data.resample("ME").mean().ffill()
+
+    Use Autoperiod to find the list of periods in the data.
+
+    >>> autoperiod = Autoperiod(data)
+    >>> periods = autoperiod.fit()
+
+    You can specify a lower percentile value for a more lenient detection
+
+    >>> autoperiod.fit(percentile=90)
+
+    Or increase the number of random data permutations for a better power threshold estimation
+
+    >>> autoperiod.fit(k=300)
+    """
+
+    def __init__(self, endog: ArrayLike):
+        self.y = to_1d_array(endog)
+
+    def fit(
+        self,
+        k: int = 100,
+        percentile: int = 95,
+        detrend_func: Optional[Union[str, Callable[[ArrayLike], NDArray]]] = "linear",
+        window_func: Optional[Union[str, float, tuple]] = None,
+        correlation_func: Optional[str] = "pearson",
+    ) -> NDArray:
+        """
+        Find periods in the given series.
+
+        Parameters
+        ----------
+        k : int, optional, default = 100
+            The number of times the data is randomly permuted while estimating the
+            power threshold.
+        percentile : int, optional, default = 95
+            Percentage for the percentile parameter used in computing the power
+            threshold. Value must be between 0 and 100 inclusive.
+        detrend_func : str, callable, default = None
+            The kind of detrending to be applied on the series. It can either be
+            'linear' or 'constant' if it the parameter is of 'str' type, or a
+            custom function that returns a detrended series.
+        window_func : float, str, tuple optional, default = None
+            Window function to be applied to the time series. Check
+            'window' parameter documentation for scipy.signal.get_window
+            function for more information on the accepted formats of this
+            parameter.
+        correlation_func : str, default = 'pearson'
+            The correlation function to be used to calculate the ACF of the time
+            series. Possible values are ['pearson', 'spearman', 'kendall'].
+
+        See Also
+        --------
+        scipy.signal.detrend
+            Remove linear trend along axis from data.
+        scipy.signal.get_window
+            Return a window of a given length and type.
+        scipy.stats.kendalltau
+            Calculate Kendall's tau, a correlation measure for ordinal data.
+        scipy.stats.pearsonr
+            Pearson correlation coefficient and p-value for testing non-correlation.
+        scipy.stats.spearmanr
+            Calculate a Spearman correlation coefficient with associated p-value.
+
+        Returns
+        -------
+        NDArray
+            List of detected periods.
+        """
+        # Detrend data
+        self.y = self.y if detrend_func is None else detrend(self.y, detrend_func)
+        # Apply window on data
+        self.y = self.y if window_func is None else apply_window(self.y, window_func)
+
+        # Compute the power threshold
+        p_threshold = self._power_threshold(self.y, k, percentile)
+
+        # Find period hints
+        freq, power = periodogram(self.y, window=None, detrend=None)
+        period_hints = np.array(
+            [
+                1 / f
+                for f, p in zip(freq, power)
+                if f >= 1 / len(freq) and p >= p_threshold
+            ]
+        )
+
+        # Compute the ACF
+        length = len(self.y)
+        acf_arr = acf(self.y, nlags=length, correlation_func=correlation_func)
+
+        # Validate period hints
+        period_hints_valid = []
+        for p in period_hints:
+            q = length / p
+            start = np.floor((p + length / (q + 1)) / 2 - 1).astype(int)
+            end = np.ceil((p + length / (q - 1)) / 2 + 1).astype(int)
+
+            splits = [
+                self._split(np.arange(len(acf_arr)), acf_arr, start, end, i)
+                for i in range(start + 2, end)
+            ]
+            line1, line2, _ = splits[
+                np.array([error for _, _, error in splits]).argmin()
+            ]
+
+            if line1.slope > 0 > line2.slope:
+                period_hints_valid.append(p)
+
+        period_hints_valid = np.array(period_hints_valid)
+
+        # Return the closest ACF peak for each valid period hint
+        local_argmax = argrelmax(acf_arr)[0]
+        return np.array(
+            list(
+                {
+                    min(local_argmax, key=lambda x: abs(x - p))
+                    for p in period_hints_valid
+                }
+            )
+        )
+
+    @staticmethod
+    def _power_threshold(y: ArrayLike, k: int, p: int) -> float:
+        """
+        Compute the power threshold as the p-th percentile of the maximum
+        power values of the periodogram of k permutations of the data.
+
+        Parameters
+        ----------
+        y : array_like
+            Data to be investigated. Must be squeezable to 1-d.
+        k : int
+            The number of times the data is randomly permuted to compute
+            the maximum power values.
+        p : int
+            The percentile value used to compute the power threshold.
+            It determines the cutoff point in the sorted list of the maximum
+            power values from the periodograms of the permuted data.
+            Value must be between 0 and 100 inclusive.
+
+        See Also
+        --------
+        scipy.signal.periodogram
+            Estimate power spectral density using a periodogram.
+
+        Returns
+        -------
+        float
+            Power threshold of the target data.
+        """
+        max_powers = []
+        while len(max_powers) < k:
+            _, power_p = periodogram(
+                np.random.permutation(y), window=None, detrend=None
+            )
+            max_powers.append(power_p.max())
+        max_powers.sort()
+        return np.percentile(max_powers, p)
+
+    @staticmethod
+    def _split(x: ArrayLike, y: ArrayLike, start: int, end: int, split: int) -> tuple:
+        """
+        Approximate a function at [start, end] with two line segments at
+        [start, split - 1] and [split, end].
+
+        Parameters
+        ----------
+        x : array_like
+            The x-coordinates of the data points.
+        y : array_like
+            The y-coordinates of the data points.
+        start : int
+            The start index of the data points to be approximated.
+        end : int
+            The end index of the data points to be approximated.
+        split : int
+            The split index of the data points to be approximated.
+
+        See Also
+        --------
+        scipy.stats.linregress
+            Calculate a linear least-squares regression for two sets of measurements.
+
+        Returns
+        -------
+        linregress
+            The first line segment.
+        linregress
+            The second line segment.
+        float
+            The error of the approximation.
+        """
+        x1, y1, x2, y2 = (
+            x[start:split],
+            y[start:split],
+            x[split : end + 1],
+            y[split : end + 1],
+        )
+        line1 = linregress(x1, y1)
+        line2 = linregress(x2, y2)
+        error = np.sum(np.abs(y1 - (line1.intercept + line1.slope * x1))) + np.sum(
+            np.abs(y2 - (line2.intercept + line2.slope * x2))
+        )
+        return line1, line2, error

pyriodicity-0.2.0/pyriodicity/detectors/fft.py

@@ -0,0 +1,110 @@
+from typing import Callable, Optional, Union
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from pyriodicity.tools import apply_window, detrend, to_1d_array
+
+
+class FFTPeriodicityDetector:
+    """
+    Fast Fourier Transform (FFT) based periodicity detector.
+
+    Find the periods in a given signal or series using FFT.
+
+    Parameters
+    ----------
+    endog : array_like
+        Data to be investigated. Must be squeezable to 1-d.
+
+    References
+    ----------
+    .. [1] Hyndman, R.J., & Athanasopoulos, G. (2021)
+    Forecasting: principles and practice, 3rd edition, OTexts: Melbourne, Australia.
+    OTexts.com/fpp3/useful-predictors.html#fourier-series. Accessed on 09-15-2024.
+
+    Examples
+    --------
+    Start by loading a timeseries dataset.
+
+    >>> from statsmodels.datasets import co2
+    >>> data = co2.load().data
+
+    You can resample the data to whatever frequency you want.
+
+    >>> data = data.resample("ME").mean().ffill()
+
+    Use FFTPeriodicityDetector to find the list of periods using FFT, ordered
+    by corresponding frequency amplitudes in a descending order.
+
+    >>> fft_detector = FFTPeriodicityDetector(data)
+    >>> periods = fft_detector.fit()
+
+    You can optionally specify a window function for pre-processing.
+
+    >>> periods = fft_detector.fit(window_func="blackman")
+    """
+
+    def __init__(self, endog: ArrayLike):
+        self.y = to_1d_array(endog)
+
+    def fit(
+        self,
+        max_period_count: Optional[int] = None,
+        detrend_func: Optional[Union[str, Callable[[ArrayLike], NDArray]]] = "linear",
+        window_func: Optional[Union[float, str, tuple]] = None,
+    ) -> NDArray:
+        """
+        Find periods in the given series.
+
+        Parameters
+        ----------
+        max_period_count : int, optional, default = None
+            Maximum number of periods to look for.
+        detrend_func : str, callable, default = None
+            The kind of detrending to be applied on the series. It can either be
+            'linear' or 'constant' if it the parameter is of 'str' type, or a
+            custom function that returns a detrended series.
+        window_func : float, str, tuple optional, default = None
+            Window function to be applied to the time series. Check
+            'window' parameter documentation for scipy.signal.get_window
+            function for more information on the accepted formats of this
+            parameter.
+
+        See Also
+        --------
+        numpy.fft
+            Discrete Fourier Transform.
+        scipy.signal.detrend
+            Remove linear trend along axis from data.
+        scipy.signal.get_window
+            Return a window of a given length and type.
+
+        Returns
+        -------
+        NDArray
+            List of detected periods.
+        """
+        # Detrend data
+        self.y = self.y if detrend_func is None else detrend(self.y, detrend_func)
+
+        # Apply the window function on the data
+        self.y = (
+            self.y
+            if window_func is None
+            else apply_window(self.y, window_func=window_func)
+        )
+
+        # Compute DFT and ignore the zero frequency
+        freqs = np.fft.rfftfreq(len(self.y), d=1)[1:]
+        ft = np.fft.rfft(self.y)[1:]
+
+        # Compute periods and their respective amplitudes
+        periods = np.round(1 / freqs)
+        amps = abs(ft)
+
+        # A period cannot be greater than half the length of the series
+        filter = periods < len(self.y) // 2
+
+        # Return periods in descending order of their corresponding amplitudes
+        return periods[filter][np.argsort(-amps[filter])][:max_period_count]

pyriodicity-0.2.0/pyriodicity/tools/__init__.py

@@ -0,0 +1,17 @@
+from ._tools import (
+    acf,
+    apply_window,
+    detrend,
+    remove_overloaded_kwargs,
+    seasonality_strength,
+    to_1d_array,
+)
+
+__all__ = [
+    "acf",
+    "apply_window",
+    "detrend",
+    "remove_overloaded_kwargs",
+    "seasonality_strength",
+    "to_1d_array",
+]

pyriodicity-0.2.0/pyriodicity/tools/_tools.py

@@ -0,0 +1,57 @@
+from typing import Callable, Dict, List, Optional, Union
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy.signal import detrend as _detrend
+from scipy.signal import get_window
+from scipy.stats import kendalltau, pearsonr, spearmanr
+
+
+@staticmethod
+def to_1d_array(x: ArrayLike) -> NDArray:
+    y = np.ascontiguousarray(np.squeeze(np.asarray(x)), dtype=np.double)
+    if y.ndim != 1:
+        raise ValueError("y must be a 1d array")
+    return y
+
+
+@staticmethod
+def remove_overloaded_kwargs(kwargs: Dict, args: List) -> Dict:
+    for arg in args:
+        kwargs.pop(arg, None)
+    return kwargs
+
+
+@staticmethod
+def seasonality_strength(seasonal: ArrayLike, resid: ArrayLike) -> float:
+    return max(0, 1 - np.var(resid) / np.var(seasonal + resid))
+
+
+@staticmethod
+def apply_window(x: ArrayLike, window_func: Union[str, float, tuple]) -> NDArray:
+    return x * get_window(window=window_func, Nx=len(x))
+
+
+@staticmethod
+def detrend(
+    x: ArrayLike,
+    method: Union[str, Callable[[ArrayLike], NDArray]],
+) -> NDArray:
+    if isinstance(method, str):
+        return _detrend(x, type=method)
+    return method(x)
+
+
+@staticmethod
+def acf(
+    x: ArrayLike,
+    nlags: int,
+    correlation_func: Optional[str] = "pearson",
+) -> NDArray:
+    if not 0 < nlags <= len(x):
+        raise ValueError("nlags must be a postive integer less than the data length")
+    if correlation_func == "spearman":
+        return np.array([spearmanr(x, np.roll(x, l)).statistic for l in range(nlags)])
+    elif correlation_func == "kendall":
+        return np.array([kendalltau(x, np.roll(x, l)).statistic for l in range(nlags)])
+    return np.array([pearsonr(x, np.roll(x, l)).statistic for l in range(nlags)])