tstools-forecast 1.0.0

Designed to make time series forecasting workflows faster, safer, and more standardized.

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.

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:

pip install tstools-forecast

Import it as:

import tstools

For local development:

pip install tstools-forecast

For editable local development:

pip install -e .

For development tools:

pip install -e .[dev]

Quickstart

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)

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

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:

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

Docs

• Getting Started
• Sanity Validation Guide
• Sample Data Guide
• API Reference