tstools-forecast 1.1.1b1

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.

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:

pip install tstools-forecast

Install from PyPI with Spark support:

pip install "tstools-forecast[spark]"

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]

For editable local development with Spark support:

pip install -e .[spark]

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)

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:

.\.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