Metadata-Version: 2.4
Name: tstools-forecast
Version: 1.1.1b1
Summary: Designed to make time series forecasting workflows faster, safer, and more standardized.
Author: TSTools
License: MIT
Project-URL: Homepage, https://github.com/rudreshmishra16/TSTools
Project-URL: Repository, https://github.com/rudreshmishra16/TSTools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: bandit[toml]>=1.7.8; extra == "dev"
Provides-Extra: spark
Requires-Dist: pyspark>=3.5; extra == "spark"
Dynamic: license-file

# TSTools

TSTools is a Python package for making time series forecasting workflows faster, safer, and more standardized.

It is intended to become a practical forecasting helper package for:

- validating forecasting datasets
- exploring time series structure quickly
- supporting reusable forecasting workflows

Today, the implemented package starts with the first and most important layer of that vision: data sanity checks for forecast readiness.

`sanity_checks(...)` is designed for prepared forecasting data held in either:

- `pandas.DataFrame`
- `pyspark.sql.DataFrame`

## Why TSTools

Forecasting projects often lose time because basic data problems are discovered too late:

- invalid or inconsistent dates
- duplicate time keys
- missing timestamps
- invalid target values
- weak or broken grouped-series structure
- messy regressor columns

TSTools is designed to catch those problems early, with an API that works well in notebooks, scripts, and pipeline-style checks.

## Current Release

The current public workflow is centered on:

- `load_sample_data(...)`
- `sanity_checks(...)`

Current implemented package areas:

- `tstools.sanity`
  forecast-readiness validation
- `tstools.datasets`
  sample data for trying the API quickly

Planned package areas:

- `tstools.eda`
  fast exploration and diagnostics for time series data
- `tstools.forecasting`
  reusable forecasting helpers, baselines, and evaluation utilities

## Install

Install from PyPI:

```bash
pip install tstools-forecast
```

Install from PyPI with Spark support:

```bash
pip install "tstools-forecast[spark]"
```

Import it as:

```python
import tstools
```

For local development:

```bash
pip install tstools-forecast
```

For editable local development:

```bash
pip install -e .
```

For development tools:

```bash
pip install -e .[dev]
```

For editable local development with Spark support:

```bash
pip install -e .[spark]
```

## Quickstart

```python
from tstools import load_sample_data, sanity_checks

df = load_sample_data("sample_timeseries_dataframe")

report = sanity_checks(
    df,
    date_col="date",  # timestamp column for the time series
    target_col="sales",  # value column to validate for forecasting
    group_cols=["dfu"],  # key column(s) defining each individual series
    expected_freq="D",  # expected cadence, here daily
    min_history=10,  # minimum observations expected per series
    non_negative_target=True,
    integer_like_target=True,
    regressors={
        "categorical": ["promo_type"],
        "numerical": ["price"],
        "boolean": ["is_promo"],
    },
)

print(report.overall_status)
print(report.summary)
```

Use `sanity_checks(...)` once your forecasting dataset is already assembled into a modeling-ready table:

- one date column
- one or more target columns
- optional key columns for panel data
- optional regressor columns you want validated as model inputs

Supported dataframe backends in this release:

- pandas: full current sanity-check surface
- Spark (`pyspark.sql.DataFrame`): core structural sanity subset

Current Spark-specific note:

- row-order monotonicity is pandas-only because Spark DataFrames do not carry stable row order semantics

Recommended first-time flow:

1. install `tstools-forecast`
2. import from `tstools`
3. run `load_sample_data("sample_timeseries_dataframe")`
4. inspect the printed report and `report.summary`

## What The Current Sanity Module Covers

`sanity_checks(...)` currently covers:

- required columns
- duplicate column names
- empty data / zero usable rows
- null group keys
- date parsing
- monotonic timestamp order
- duplicate keys and conflicting duplicate keys
- missing dates and frequency consistency
- numeric target validity
- target domain constraints
- missing targets
- constant and all-zero series
- short history
- typed regressor validation for categorical, numerical, and boolean regressors

Spark v1 supports the core structural subset:

- schema and required columns
- empty input and null key columns
- date parseability, missing dates, and cadence checks
- duplicate and conflicting duplicate keys
- target numeric/domain checks
- missing targets
- constant and all-zero series
- regressor validation
- short history

It is most useful after raw joins, filtering, and feature assembly are already done, and before EDA or modeling begins.

## Sample Data

TSTools ships with one maintained public demo dataset:

- `sample_timeseries_dataframe`

It is intentionally designed to exercise the current sanity-check surface in one dataframe, including:

- invalid dates
- missing dates
- duplicate and conflicting duplicate keys
- missing targets
- constant and all-zero series
- short history
- target domain violations
- invalid or missing regressors

## Report Statuses

Overall report status:

- `READY`
- `READY_WITH_WARNINGS`
- `NOT_READY`

Check status:

- `PASS`
- `WARN`
- `FAIL`
- `INFO`

## Product Direction

The long-term goal is not just to validate data, but to support a fuller forecasting workflow:

1. validate time series inputs
2. explore and diagnose the data
3. build repeatable forecasting utilities on top of clean inputs

Spark support is intentionally phased so the package can stay fast, explicit, and reliable while the backend surface grows.

## Development

Run verification:

```bash
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m bandit -q -r src
```

## Docs

- [Getting Started](docs/getting_started.md)
- [Sanity Validation Guide](docs/user_guide/sanity_validation.md)
- [Sample Data Guide](docs/user_guide/sample_data.md)
- [API Reference](docs/api_reference/README.md)
