Metadata-Version: 2.4
Name: tstools-forecast
Version: 1.0.1
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"
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.

In the current version, `sanity_checks(...)` is designed for prepared forecasting data held in a pandas 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
```

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]
```

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

Only pandas DataFrames are supported in this version.

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

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

## 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)
