Metadata-Version: 2.4
Name: tstools-forecast
Version: 0.1.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 designed to make time series forecasting workflows faster, safer, and more standardized.

Its goal is to provide a clean, analyst-friendly toolkit for preparing, validating, exploring, and eventually forecasting time series data at scale. The package is built for users who work with forecasting datasets regularly and need a reliable way to check whether their data is actually fit for modeling before moving into EDA, feature engineering, and forecasting.

Version 1 is focused on the first major pillar of that vision: sanity validation for forecast-readiness.

## Product Vision

At its core, TSTools is meant to reduce avoidable forecasting errors caused by bad input data, inconsistent time structure, missing dates, duplicate keys, invalid target values, and weak series quality. Instead of discovering these issues deep into the modeling workflow, users should be able to catch them immediately through a simple, reusable API.

The intended experience is lightweight and intuitive. A user should be able to import a module from TSTools, pass in a base dataframe with a few key parameters such as the date column, target column, and group identifiers, and instantly receive a detailed sanity report explaining whether the dataset is in the correct shape for time series forecasting.

TSTools is designed to be:

- simple to use for analysts working in notebooks
- modular internally so it can scale into a fuller package
- structured enough for pipelines by returning usable report objects, not just printed text
- practical for real forecasting data, especially grouped or panel datasets such as DFU-level demand series

Over time, the package is intended to grow into a broader toolkit with dedicated submodules for:

- sanity checks for forecast-readiness validation
- EDA for fast time series exploration and diagnostics
- forecasting for baseline models, evaluation, and reusable forecasting utilities

## Installation

```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("panel_with_issues")

report = sanity_checks(
    df,
    date_col="date",
    target_col="sales",
    group_cols=["dfu"],
    expected_freq="D",
    min_history=10,
)

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

You can also test against a lightweight real forecasting dataset:

```python
df = load_sample_data("tourism_monthly")

report = sanity_checks(
    df,
    date_col="date",
    target_col="target",
    group_cols=["series_id"],
    expected_freq="MS",
    min_history=24,
)
```

## Intended Experience

The main v1 workflow is to run sanity checks before deeper exploration or modeling:

```python
from tstools import sanity_checks

sanity_checks(
    base_df,
    date_col="date",
    target_col="sales",
    group_cols=["dfu"],
    expected_freq="D",
)
```

The report is designed to help users quickly understand whether:

- required columns are present
- dates are parseable
- targets are numeric
- duplicate time keys exist
- dates are missing between the minimum and maximum range for each series
- frequency is consistent with expectations
- target values are missing
- some series are too short for reliable modeling
- some series are constant or all zero

## Sanity Checks in v1

TSTools v1 currently focuses on forecast-readiness validation through a single entry point: `sanity_checks`.

It checks:

- schema integrity
- date parsing quality
- duplicate keys
- missing timestamps by series
- frequency consistency
- missing target values
- short history by group
- constant and all-zero series

```python
from tstools import load_sample_data, sanity_checks

df = load_sample_data("panel_with_issues")
report = sanity_checks(
    df,
    date_col="date",
    target_col="sales",
    group_cols=["dfu"],
    expected_freq="D",
    min_history=10,
)
```

Sample printed output:

```text
==================================================
TSTools Sanity Check Report
==================================================

Dataset shape     : 66 rows x 3 columns
Date column       : date
Target column(s)  : sales
Group column(s)   : ['dfu']
Expected frequency: D
Min history       : 10

Overall status    : NOT_READY
```

The function prints a readable console report and also returns a structured report object that can be used in notebooks, scripts, or pipelines.

## Built-in Sample Data

TSTools includes sample datasets so users can quickly test the APIs, understand expected input formats, and see how the reports behave on both clean and problematic forecasting data.

- `daily_series_clean`
- `panel_clean`
- `panel_with_issues`
- `tourism_monthly`

`tourism_monthly` is a lightweight real forecasting dataset loaded from the Monash Tourism Monthly data hosted on Zenodo over HTTPS and cached locally on first use. It is normalized into long format with columns `series_id`, `date`, and `target`.

Source:

- Zenodo Tourism Monthly archive: https://zenodo.org/records/4656096
- Dataset header cites the tourism forecasting competition and Monash forecasting repository materials

Example:

```python
from tstools import load_sample_data

df = load_sample_data("panel_with_issues")
df.head()
```

## Report Statuses

- `READY`: no failures or warnings
- `READY_WITH_WARNINGS`: no failures, but at least one warning
- `NOT_READY`: at least one failed check

Check statuses:

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

## Development

Run the test suite:

```bash
.\.venv\Scripts\python.exe -m pytest
```

Run optional quality tools:

```bash
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m black --check .
.\.venv\Scripts\python.exe -m mypy src
.\.venv\Scripts\python.exe -m bandit -q -r src
```

## Automated Release

The `prod` branch is configured for automated publication to PyPI with GitHub Actions.

- pushes to `prod` run verification, Bandit application-security scanning, dependency vulnerability checks, and then trigger a package publish workflow
- `main` is intended to remain the development branch
- the PyPI distribution name is `tstools-forecast`
- GitHub CodeQL is configured for `main` and `prod` pushes, pull requests, and scheduled code scanning
- PyPI releases are immutable, so each new production publish must use a new package version

To make trusted publishing work on GitHub, configure the PyPI project to trust this repository and the `publish-prod.yml` workflow for the `prod` branch.

## Project Docs

Detailed code-grounded documentation is available in [docs/README.md](c:/Users/rudre/OneDrive/Documents/GitHub/TSTools/docs/README.md).

## Roadmap

TSTools starts with sanity checks, but the larger vision is to become a dependable toolkit for end-to-end time series forecasting preparation and analysis. The long-term direction includes:

- stronger forecast-readiness validation workflows
- faster EDA for grouped time series datasets
- reusable forecasting utilities and baseline modeling helpers
