tstools-forecast 0.2.0

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

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

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

report = sanity_checks(
    df,
    date_col="date",
    target_col="sales",
    group_cols=["dfu"],
    expected_freq="D",
    min_history=10,
    non_negative_target=True,
    regressors={
        "categorical": ["promo_type"],
        "numerical": ["price"],
        "boolean": ["is_promo"],
    },
)

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

You can also test against a lightweight real forecasting dataset:

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:

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
• timestamps are in monotonic order within each series
• targets are numeric
• targets violate explicit domain rules such as non-negative or integer-like constraints
• regressor columns exist in the declared buckets
• regressors match their declared categorical / numerical / boolean types
• regressors contain missing, blank, or invalid values
• 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
• monotonic timestamp order by series
• duplicate keys
• missing timestamps by series
• frequency consistency
• missing target values
• regressor sanity by user-declared bucket
• optional target domain constraints such as non-negative, integer-like, and min/max bounds
• short history by group
• constant and all-zero series

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,
    non_negative_target=True,
    regressors={
        "categorical": ["promo_type"],
        "numerical": ["price"],
        "boolean": ["is_promo"],
    },
)

Sample printed output:

==================================================
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:

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:

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

Run optional quality tools:

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

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