Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

TSLab: a batteries-included lab for time series research

PyPI version Total downloads CI status License GitHub stars Code style: ruff

Python Docs
Python versions Documentation status

TSLab lets you write your time series experiments as plain Python scripts and takes care of the rest. Every step is cached, so a rerun picks up where the last one stopped instead of starting over. When one script turns into a whole grid of experiments, TSLab runs it on your laptop or a SLURM cluster, retries what crashed, and gathers the results into a single table for the paper.

It ships with:

  • cached, resumable stages: finished steps load on the next run, and only what changed or failed runs again (see How it works);
  • studies: named grids of experiments (datasets × models × seeds) that you submit, follow, resubmit and collect with one command each;
  • SLURM support: job arrays built from machine profiles, checkpoint and pause before the time limit, automatic resubmit or requeue, grids chained by job dependencies, code snapshots for queued jobs, multi-GPU training through srun, and tslab doctor to check a cluster;
  • local runs of the same study on a laptop or workstation, no scheduler needed;
  • Lightning training with safe resume;
  • ready stages for time series representation learning: train, encode, and evaluate with linear probes;
  • experiment trackers: CSV always; Weights & Biases, MLflow and TensorBoard as extras;
  • typed command-line configs with presets;
  • adapters for the chronocratic model and dataset libraries;
  • a CLI (tslab): project templates, run overviews and every study command (see CLI).

How it works

Mark each step of your main() as a stage. TSLab fingerprints the inputs and settings of each stage and stores its result. On the next run it loads finished results, resumes unfinished training, and reruns only what changed or failed.

import tslab.lab


@tslab.lab.stage(name='smooth', output=tslab.ml.Tensors)
def smooth(*, run: tslab.lab.Run, data: tslab.ml.Tensors, window: int) -> tslab.ml.Tensors: ...


with tslab.lab.Run(config=config, root=Path('runs'), relative_path=Path('minimal')) as run:
    data = make_series(run=run, series=8, length=256)
    smoothed = smooth(run=run, data=data, window=9)  # loaded, not computed, on the next run

One distribution, three layers: tslab.lab (runs, stages, studies, jobs; no torch), tslab.ml (torch and Lightning) and tslab.ts (time series). The lab seeds Python random and NumPy; importing tslab.ml adds torch seeding and torch metadata.

Install

Python 3.12 or newer. With uv:

uv add tslab                  # lab only, no torch
uv add "tslab[ml]"            # plus torch, Lightning, safetensors
uv add "tslab[ts]"            # plus scikit-learn, for the time series layer
uv add "tslab[full]"          # ts, both chronocratic adapters and analysis
uv add "tslab[full,wandb]"    # extras combine
Extra Adds
ml torch, Lightning, safetensors
ts ml and scikit-learn
chronocratic-models, chronocratic-datasets ts and the chronocratic adapter packages
wandb, mlflow, tensorboard ml and the tracker
wandb-sync W&B alone, to run tslab wandb-sync on a login node without torch
analysis pandas, SciPy, Matplotlib
full ts, both chronocratic adapters and analysis

Quick start

Create a project from the template, then train and evaluate on toy data:

uvx tslab new my-paper                            # add --template lab for a bare project; inside a project it joins its uv workspace
cd my-paper
uv sync
uv run python -m my_paper.toy_data data           # write small synthetic datasets
uv run python -m my_paper.classify ts2vec-archive-split
uv run tslab status runs                          # see what ran and what was cached

Run the classify line again: every stage loads instead of computing. The generated README.md explains the rest.

⭐ Found this useful? Give it a star. TSLab is free and open source. A star takes one click, tells us the work is worth continuing, and helps other time series researchers find the project.

CLI

TSLab ships with a CLI. Installing it puts a tslab command on your path (or run it without installing via uvx tslab). Your experiments stay plain Python scripts; the CLI creates projects, launches studies and shows what runs are doing.

Command Does
tslab new FOLDER Create a project from a template (ts by default, or lab); inside another Python project it becomes a uv workspace member of it.
tslab status PATH Show the instances of a run, or one line per run below a folder.
tslab study ... Run an experiment grid on SLURM or locally: submit, status, wait, failures, logs, resubmit, results.
tslab machine ... Register machine profiles (local, SLURM clusters): add, list, remove.
tslab doctor Check whether a machine, and optionally a study, is ready.
tslab wandb-sync Resync offline W&B runs that the server shows as crashed or failed.

A study, step by step:

tslab study submit STUDY --machine local --dry-run   # check the plan
tslab study submit STUDY --machine local             # launch the runs
tslab study status STUDY --machine local             # follow them
tslab study results STUDY --machine local --out results.csv

tslab --help and tslab COMMAND --help list every option.

Examples

  • examples/minimal: three plain stages, no deep learning; shows caching and instances.
  • examples/advanced: TS2Vec with your own transform stage, a failing instance and selective reruns.

Documentation

tslab.readthedocs.io: three sections, one per layer (tslab.lab without torch, tslab.ml, tslab.ts), plus the API.

Contributing

See CONTRIBUTING.md. Changes are listed in CHANGELOG.md.

License

BSD 3-Clause. See LICENSE.

Metadata

Release files for tslab 0.1.0a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tslab 0.1.0a1
File Size Uploaded Provenance Actions
tslab-0.1.0a1.tar.gz 1.3 MB With provenance Details for tslab-0.1.0a1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tslab 0.1.0a1
File Interpreter ABI Platform Actions
tslab-0.1.0a1-py3-none-any.whl Python 3 none any Details for tslab-0.1.0a1-py3-none-any.whl

Total release size: 1.8 MB

Release files / tslab-0.1.0a1.tar.gz

Download URL tslab-0.1.0a1.tar.gz
Size 1.3 MB
Tags Source
SHA-256 checksum
How to use checksums
186dc971f379130782f29a8039341ef8e5e45980f23f9f389c730d55460776b7
BLAKE2b-256 checksum
How to use checksums
10e0951b8713e539cfd882e80eae89d4a42015fbd69e4f25fa8c8b081fd3713e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / tslab-0.1.0a1-py3-none-any.whl

Download URL tslab-0.1.0a1-py3-none-any.whl
Size 490.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
83ce09fbb1765d6352e1b15ff253d1f22a40250d65358be560557652c6563db8
BLAKE2b-256 checksum
How to use checksums
02828c56a671549f8f5673b5f538dc3cb6f22c04224e66d41f5d5fef5de9a393
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for tslab 0.1.0a1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tslab-0.1.0a1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page