This release is a pre-release and may not be stable for production use.
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, andtslab doctorto 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.