timeseries-eda 0.1.0__tar.gz

timeseries_eda-0.1.0/CHANGELOG.rst

@@ -0,0 +1,38 @@
+Changelog
+=========
+
+All notable changes to ``tseda`` are documented here.
+This project follows `Semantic Versioning <https://semver.org/>`_.
+
+----
+
+0.1.0 (2026-06-21)
+-------------------
+
+Initial release.
+
+**Modules**
+
+* ``tseda.core`` — :class:`~tseda.core.TimeSeries` data structure,
+  type aliases (:class:`~tseda.core.Frequency`, :class:`~tseda.core.AggMethod`,
+  :class:`~tseda.core.DiffMethod`), and validators.
+
+* ``tseda.quality`` — Missing-value analysis
+  (:class:`~tseda.quality.MissingValueAnalyzer`), outlier detection with
+  IQR / Z-score / MAD / GESD (:class:`~tseda.quality.OutlierDetector`),
+  and flat-line / near-zero detection
+  (:class:`~tseda.quality.DuplicateDetector`).
+
+* ``tseda.statistics`` — Comprehensive descriptive statistics
+  (:class:`~tseda.statistics.DescriptiveAnalyzer`), stationarity tests
+  ADF / KPSS / Phillips-Perron (:class:`~tseda.statistics.StationarityTester`),
+  and ACF / PACF / Ljung-Box autocorrelation analysis
+  (:class:`~tseda.statistics.AutocorrelationAnalyzer`).
+
+* ``tseda.decomposition`` — Classical additive / multiplicative decomposition
+  (:class:`~tseda.decomposition.ClassicalDecomposer`) and STL decomposition
+  (:class:`~tseda.decomposition.STLDecomposer`).
+
+* ``tseda.seasonality`` — Seasonal period detection via FFT periodogram,
+  ACF peaks, and combined scoring with Fisher G-test
+  (:class:`~tseda.seasonality.SeasonalityDetector`).

timeseries_eda-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amirhossein Jafari
+
+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.

timeseries_eda-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.rst
+include CHANGELOG.rst
+recursive-include tseda *.py
+recursive-include docs *.rst *.py *.png *.svg

timeseries_eda-0.1.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.4
+Name: timeseries-eda
+Version: 0.1.0
+Summary: Comprehensive Time Series Exploratory Data Analysis toolkit
+Author-email: Amirhossein Jafari <ajafari@gwu.edu>
+License: MIT License
+        
+        Copyright (c) 2026 Amirhossein Jafari
+        
+        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.
+Project-URL: Homepage, https://github.com/amir-jafari/Time-Series-EDA
+Project-URL: Documentation, https://amir-jafari.github.io/Time-Series-EDA
+Project-URL: Repository, https://github.com/amir-jafari/Time-Series-EDA
+Project-URL: Issues, https://github.com/amir-jafari/Time-Series-EDA/issues
+Project-URL: Changelog, https://github.com/amir-jafari/Time-Series-EDA/blob/main/CHANGELOG.rst
+Keywords: time series,eda,exploratory data analysis,forecasting,statistics,anomaly detection,seasonality,decomposition
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.9
+Requires-Dist: matplotlib>=3.6
+Provides-Extra: stats
+Requires-Dist: statsmodels>=0.14; extra == "stats"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.9; extra == "dev"
+Requires-Dist: pandas-stubs; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.2; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Requires-Dist: numpydoc>=1.7; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
+Provides-Extra: all
+Requires-Dist: tseda[dev,docs,stats]; extra == "all"
+Dynamic: license-file
+
+tseda — Time Series EDA
+=======================
+
+.. image:: https://img.shields.io/pypi/v/tseda.svg
+   :target: https://pypi.org/project/tseda/
+   :alt: PyPI
+
+.. image:: https://img.shields.io/pypi/pyversions/tseda.svg
+   :target: https://pypi.org/project/tseda/
+   :alt: Python Versions
+
+.. image:: https://img.shields.io/badge/license-MIT-blue.svg
+   :target: https://github.com/amir-jafari/Time-Series-EDA/blob/main/LICENSE
+   :alt: License
+
+.. image:: https://img.shields.io/github/actions/workflow/status/amir-jafari/Time-Series-EDA/tests.yml?branch=main
+   :target: https://github.com/amir-jafari/Time-Series-EDA/actions
+   :alt: Tests
+
+**"Understand your time series before you forecast it."**
+
+``tseda`` is a comprehensive, dependency-light Python toolkit for time series
+Exploratory Data Analysis (EDA).  It is to time series what
+`YData-Profiling <https://docs.profiling.ydata.ai/>`_ is to tabular data:
+a single command that produces a complete understanding of any time series
+dataset before you start modelling.
+
+----
+
+Why tseda?
+----------
+
+Existing libraries solve individual problems.  No single package provides all of:
+
+* Comprehensive EDA & data auditing
+* Forecastability assessment
+* Automated diagnostics (stationarity, seasonality, anomalies)
+* Structural break / changepoint detection
+* Feature engineering
+* Model recommendations
+* Interactive reports
+
+``tseda`` fills that gap, using only **numpy**, **pandas**, **scipy**, and
+**matplotlib** as core dependencies.
+
+----
+
+Installation
+------------
+
+.. code-block:: bash
+
+   pip install tseda
+
+For stationarity tests that use statsmodels (ADF, KPSS, Phillips-Perron):
+
+.. code-block:: bash
+
+   pip install tseda[stats]
+
+For building the documentation:
+
+.. code-block:: bash
+
+   pip install tseda[docs]
+
+----
+
+Quick Start
+-----------
+
+.. code-block:: python
+
+   import numpy as np
+   import pandas as pd
+   from tseda import TimeSeries
+
+   # Build a TimeSeries object
+   idx = pd.date_range("2020-01-01", periods=365, freq="D")
+   ts  = TimeSeries(
+       np.cumsum(np.random.randn(365)),
+       index=idx,
+       name="stock_price",
+       unit="USD",
+   )
+   print(ts)
+
+   # Data quality
+   from tseda.quality import MissingValueAnalyzer, OutlierDetector
+   missing = MissingValueAnalyzer().analyze(ts)
+   outliers = OutlierDetector().mad(ts)
+
+   # Statistics
+   from tseda.statistics import DescriptiveAnalyzer, StationarityTester
+   stats = DescriptiveAnalyzer().analyze(ts)
+   adf   = StationarityTester().adf(ts)
+   print(adf.summary() if hasattr(adf, "summary") else adf)
+
+   # Decomposition
+   from tseda.decomposition import STLDecomposer
+   dec = STLDecomposer().decompose(ts, period=7)
+   print(dec.summary())
+
+   # Seasonality
+   from tseda.seasonality import SeasonalityDetector
+   season = SeasonalityDetector().detect(ts)
+   print(f"Dominant period: {season.dominant_period}")
+
+----
+
+Modules
+-------
+
++---------------------+------------------------------------------------------+
+| Module              | Capability                                           |
++=====================+======================================================+
+| ``core``            | ``TimeSeries`` data structure & validators           |
++---------------------+------------------------------------------------------+
+| ``quality``         | Missing values, outlier detection, flat-line checks  |
++---------------------+------------------------------------------------------+
+| ``statistics``      | Descriptive stats, stationarity, ACF/PACF            |
++---------------------+------------------------------------------------------+
+| ``decomposition``   | Classical & STL decomposition                        |
++---------------------+------------------------------------------------------+
+| ``seasonality``     | FFT periodogram + ACF-based period detection         |
++---------------------+------------------------------------------------------+
+| ``anomaly``         | Rolling IQR/Z-score, STL-residual anomaly detection  |
++---------------------+------------------------------------------------------+
+| ``changepoint``     | Structural break / CUSUM detection                   |
++---------------------+------------------------------------------------------+
+| ``features``        | Temporal, statistical, spectral feature extraction   |
++---------------------+------------------------------------------------------+
+| ``forecastability`` | Forecast-readiness scoring & leakage detection       |
++---------------------+------------------------------------------------------+
+| ``visualization``   | Matplotlib plot suite                                |
++---------------------+------------------------------------------------------+
+| ``report``          | HTML & console report generation                     |
++---------------------+------------------------------------------------------+
+
+----
+
+Dependencies
+------------
+
+**Core** (always installed):
+
+* ``numpy >= 1.23``
+* ``pandas >= 1.5``
+* ``scipy >= 1.9``
+* ``matplotlib >= 3.6``
+
+**Optional**:
+
+* ``statsmodels >= 0.14`` — ADF, KPSS, Phillips-Perron, STL (``pip install tseda[stats]``)
+
+----
+
+Documentation
+-------------
+
+`https://amir-jafari.github.io/Time-Series-EDA <https://amir-jafari.github.io/Time-Series-EDA>`_
+
+----
+
+Contributing
+------------
+
+Contributions are welcome!  Please open an issue or pull request at
+`https://github.com/amir-jafari/Time-Series-EDA <https://github.com/amir-jafari/Time-Series-EDA>`_.
+
+----
+
+License
+-------
+
+MIT © 2026 Amirhossein Jafari

timeseries_eda-0.1.0/README.rst

@@ -0,0 +1,176 @@
+tseda — Time Series EDA
+=======================
+
+.. image:: https://img.shields.io/pypi/v/tseda.svg
+   :target: https://pypi.org/project/tseda/
+   :alt: PyPI
+
+.. image:: https://img.shields.io/pypi/pyversions/tseda.svg
+   :target: https://pypi.org/project/tseda/
+   :alt: Python Versions
+
+.. image:: https://img.shields.io/badge/license-MIT-blue.svg
+   :target: https://github.com/amir-jafari/Time-Series-EDA/blob/main/LICENSE
+   :alt: License
+
+.. image:: https://img.shields.io/github/actions/workflow/status/amir-jafari/Time-Series-EDA/tests.yml?branch=main
+   :target: https://github.com/amir-jafari/Time-Series-EDA/actions
+   :alt: Tests
+
+**"Understand your time series before you forecast it."**
+
+``tseda`` is a comprehensive, dependency-light Python toolkit for time series
+Exploratory Data Analysis (EDA).  It is to time series what
+`YData-Profiling <https://docs.profiling.ydata.ai/>`_ is to tabular data:
+a single command that produces a complete understanding of any time series
+dataset before you start modelling.
+
+----
+
+Why tseda?
+----------
+
+Existing libraries solve individual problems.  No single package provides all of:
+
+* Comprehensive EDA & data auditing
+* Forecastability assessment
+* Automated diagnostics (stationarity, seasonality, anomalies)
+* Structural break / changepoint detection
+* Feature engineering
+* Model recommendations
+* Interactive reports
+
+``tseda`` fills that gap, using only **numpy**, **pandas**, **scipy**, and
+**matplotlib** as core dependencies.
+
+----
+
+Installation
+------------
+
+.. code-block:: bash
+
+   pip install tseda
+
+For stationarity tests that use statsmodels (ADF, KPSS, Phillips-Perron):
+
+.. code-block:: bash
+
+   pip install tseda[stats]
+
+For building the documentation:
+
+.. code-block:: bash
+
+   pip install tseda[docs]
+
+----
+
+Quick Start
+-----------
+
+.. code-block:: python
+
+   import numpy as np
+   import pandas as pd
+   from tseda import TimeSeries
+
+   # Build a TimeSeries object
+   idx = pd.date_range("2020-01-01", periods=365, freq="D")
+   ts  = TimeSeries(
+       np.cumsum(np.random.randn(365)),
+       index=idx,
+       name="stock_price",
+       unit="USD",
+   )
+   print(ts)
+
+   # Data quality
+   from tseda.quality import MissingValueAnalyzer, OutlierDetector
+   missing = MissingValueAnalyzer().analyze(ts)
+   outliers = OutlierDetector().mad(ts)
+
+   # Statistics
+   from tseda.statistics import DescriptiveAnalyzer, StationarityTester
+   stats = DescriptiveAnalyzer().analyze(ts)
+   adf   = StationarityTester().adf(ts)
+   print(adf.summary() if hasattr(adf, "summary") else adf)
+
+   # Decomposition
+   from tseda.decomposition import STLDecomposer
+   dec = STLDecomposer().decompose(ts, period=7)
+   print(dec.summary())
+
+   # Seasonality
+   from tseda.seasonality import SeasonalityDetector
+   season = SeasonalityDetector().detect(ts)
+   print(f"Dominant period: {season.dominant_period}")
+
+----
+
+Modules
+-------
+
++---------------------+------------------------------------------------------+
+| Module              | Capability                                           |
++=====================+======================================================+
+| ``core``            | ``TimeSeries`` data structure & validators           |
++---------------------+------------------------------------------------------+
+| ``quality``         | Missing values, outlier detection, flat-line checks  |
++---------------------+------------------------------------------------------+
+| ``statistics``      | Descriptive stats, stationarity, ACF/PACF            |
++---------------------+------------------------------------------------------+
+| ``decomposition``   | Classical & STL decomposition                        |
++---------------------+------------------------------------------------------+
+| ``seasonality``     | FFT periodogram + ACF-based period detection         |
++---------------------+------------------------------------------------------+
+| ``anomaly``         | Rolling IQR/Z-score, STL-residual anomaly detection  |
++---------------------+------------------------------------------------------+
+| ``changepoint``     | Structural break / CUSUM detection                   |
++---------------------+------------------------------------------------------+
+| ``features``        | Temporal, statistical, spectral feature extraction   |
++---------------------+------------------------------------------------------+
+| ``forecastability`` | Forecast-readiness scoring & leakage detection       |
++---------------------+------------------------------------------------------+
+| ``visualization``   | Matplotlib plot suite                                |
++---------------------+------------------------------------------------------+
+| ``report``          | HTML & console report generation                     |
++---------------------+------------------------------------------------------+
+
+----
+
+Dependencies
+------------
+
+**Core** (always installed):
+
+* ``numpy >= 1.23``
+* ``pandas >= 1.5``
+* ``scipy >= 1.9``
+* ``matplotlib >= 3.6``
+
+**Optional**:
+
+* ``statsmodels >= 0.14`` — ADF, KPSS, Phillips-Perron, STL (``pip install tseda[stats]``)
+
+----
+
+Documentation
+-------------
+
+`https://amir-jafari.github.io/Time-Series-EDA <https://amir-jafari.github.io/Time-Series-EDA>`_
+
+----
+
+Contributing
+------------
+
+Contributions are welcome!  Please open an issue or pull request at
+`https://github.com/amir-jafari/Time-Series-EDA <https://github.com/amir-jafari/Time-Series-EDA>`_.
+
+----
+
+License
+-------
+
+MIT © 2026 Amirhossein Jafari

timeseries_eda-0.1.0/docs/api/anomaly.rst

@@ -0,0 +1,18 @@
+tseda.anomaly
+=============
+
+.. automodule:: tseda.anomaly
+   :members:
+   :undoc-members:
+
+Report
+------
+
+.. autoclass:: tseda.anomaly.detector.AnomalyReport
+   :members:
+
+Detector
+--------
+
+.. autoclass:: tseda.anomaly.detector.AnomalyDetector
+   :members:

timeseries_eda-0.1.0/docs/api/changepoint.rst

@@ -0,0 +1,18 @@
+tseda.changepoint
+=================
+
+.. automodule:: tseda.changepoint
+   :members:
+   :undoc-members:
+
+Report
+------
+
+.. autoclass:: tseda.changepoint.detector.ChangepointReport
+   :members:
+
+Detector
+--------
+
+.. autoclass:: tseda.changepoint.detector.ChangepointDetector
+   :members:

timeseries_eda-0.1.0/docs/api/core.rst

@@ -0,0 +1,37 @@
+tseda.core
+==========
+
+.. automodule:: tseda.core
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+TimeSeries
+----------
+
+.. autoclass:: tseda.core.TimeSeries
+   :members:
+   :special-members: __init__, __repr__, __len__, __contains__, __getitem__
+   :show-inheritance:
+
+Types & Enumerations
+--------------------
+
+.. autoclass:: tseda.core.types.Frequency
+   :members:
+   :show-inheritance:
+
+.. autoclass:: tseda.core.types.AggMethod
+   :members:
+   :show-inheritance:
+
+.. autoclass:: tseda.core.types.DiffMethod
+   :members:
+   :show-inheritance:
+
+Validators
+----------
+
+.. automodule:: tseda.core.validator
+   :members:
+   :undoc-members:

timeseries_eda-0.1.0/docs/api/decomposition.rst

@@ -0,0 +1,24 @@
+tseda.decomposition
+===================
+
+.. automodule:: tseda.decomposition
+   :members:
+   :undoc-members:
+
+Result
+------
+
+.. autoclass:: tseda.decomposition.classical.DecompositionResult
+   :members:
+
+Classical Decomposition
+-----------------------
+
+.. autoclass:: tseda.decomposition.classical.ClassicalDecomposer
+   :members:
+
+STL Decomposition
+-----------------
+
+.. autoclass:: tseda.decomposition.stl.STLDecomposer
+   :members:

timeseries_eda-0.1.0/docs/api/features.rst

@@ -0,0 +1,24 @@
+tseda.features
+==============
+
+.. automodule:: tseda.features
+   :members:
+   :undoc-members:
+
+Temporal Features
+-----------------
+
+.. autoclass:: tseda.features.temporal.TemporalFeatureExtractor
+   :members:
+
+Statistical Features
+--------------------
+
+.. autoclass:: tseda.features.statistical.StatisticalFeatureExtractor
+   :members:
+
+Spectral Features
+-----------------
+
+.. autoclass:: tseda.features.spectral.SpectralFeatureExtractor
+   :members:

timeseries_eda-0.1.0/docs/api/forecastability.rst

@@ -0,0 +1,24 @@
+tseda.forecastability
+====================
+
+.. automodule:: tseda.forecastability
+   :members:
+   :undoc-members:
+
+Forecastability Scorer
+----------------------
+
+.. autoclass:: tseda.forecastability.scorer.ForecastabilityReport
+   :members:
+
+.. autoclass:: tseda.forecastability.scorer.ForecastabilityScorer
+   :members:
+
+Leakage Detector
+----------------
+
+.. autoclass:: tseda.forecastability.leakage.LeakageReport
+   :members:
+
+.. autoclass:: tseda.forecastability.leakage.LeakageDetector
+   :members:

timeseries_eda-0.1.0/docs/api/quality.rst

@@ -0,0 +1,33 @@
+tseda.quality
+=============
+
+.. automodule:: tseda.quality
+   :members:
+   :undoc-members:
+
+Missing Values
+--------------
+
+.. autoclass:: tseda.quality.missing.MissingValueReport
+   :members:
+
+.. autoclass:: tseda.quality.missing.MissingValueAnalyzer
+   :members:
+
+Outliers
+--------
+
+.. autoclass:: tseda.quality.outliers.OutlierReport
+   :members:
+
+.. autoclass:: tseda.quality.outliers.OutlierDetector
+   :members:
+
+Flat-line / Duplicates
+----------------------
+
+.. autoclass:: tseda.quality.duplicates.FlatlineReport
+   :members:
+
+.. autoclass:: tseda.quality.duplicates.DuplicateDetector
+   :members:

timeseries_eda-0.1.0/docs/api/report.rst

@@ -0,0 +1,18 @@
+tseda.report
+============
+
+.. automodule:: tseda.report
+   :members:
+   :undoc-members:
+
+HTML Report
+-----------
+
+.. autoclass:: tseda.report.html_report.HTMLReport
+   :members:
+
+Console Report
+--------------
+
+.. autoclass:: tseda.report.console_report.ConsoleReport
+   :members: