Metadata-Version: 2.4
Name: timeseries-eda
Version: 0.1.2
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: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: nbsphinx>=0.9; extra == "docs"
Requires-Dist: ipykernel>=6.0; extra == "docs"
Requires-Dist: sphinx-design>=0.5; extra == "docs"
Requires-Dist: myst-parser>=3.0; 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
