TorchSpatiotemporal (tsl): a PyTorch layer for graph-based spatiotemporal forecasting
tsl: a PyTorch library for processing spatiotemporal data.
At a glance
- What is it?
- tsl bundles datasets, preprocessing, modular neural layers and Hydra-based experiment configs for spatiotemporal prediction on graphs. It fits researchers who want to reproduce published baselines, and it will frustrate anyone who wants a stable API or a data pipeline that survives a schema change.
- Who is it for?
- Adopt tsl if you are a researcher reproducing spatiotemporal GNN baselines and you can pin your dependency versions, because the last release in the supplied material is v0.9.5 from July 2024 and the API has moved between 0.9.3, 0.9.4 and 0.9.5. Do not adopt it as the data layer of a production forecasting service, where a schema change or a missing-value policy you cannot override becomes an incident.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 51 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem tsl addresses: spatiotemporal data has no natural tensor shape
A standard PyTorch workflow assumes a tensor with a fixed shape. Spatiotemporal data breaks that assumption in three places at once. The spatial dimension is a graph whose structure can change over time, so a sensor that reports today may be offline next week. The temporal dimension is irregular, with missing readings and sampling rates that differ between nodes. And the evaluation protocol is not a random train/test split, it is a chronological one, usually with a rolling or fixed horizon. The README describes tsl as a library built to accelerate research on neural spatiotemporal data processing methods, with a focus on Graph Neural Networks. That focus is the point. The library is aimed at people who already know what a spatiotemporal graph is and want the plumbing handled so they can spend their time on the model. It is not aimed at a team that has a tidy panel dataset and wants a general forecasting tool. The README lists the target domains explicitly: sensor networks, environmental data, and other spatiotemporal domains, with an emphasis on benchmarking against published baselines.
How tsl is put together: PyTorch, PyG, Lightning and Hydra
The README states that tsl is built on PyTorch, PyG (PyTorch Geometric) and PyTorch Lightning, and that it provides a framework going from data preprocessing to model prototyping. That stack choice determines most of the library's behaviour. PyG supplies the graph representation, so a spatial graph is a PyG object rather than a bespoke adjacency matrix format, and a model that consumes graph structure can reuse PyG conventions. PyTorch Lightning supplies the training loop, which is why the README can claim scaling from a single CPU to clusters of GPUs: that scaling is inherited from Lightning rather than implemented by tsl. Hydra supplies the experiment configuration, which is how the README supports its reproducibility claim. The data flow implied by the feature list is: raw spatiotemporal series enter a preprocessing stage that handles scaling, resampling and clustering of time series; the result is held in the library's own data structures; a dataset object applies a train/validation/test split; a model composed from the library's neural layers consumes batches; Lightning runs the training; Hydra records the configuration. The README also says the library handles irregularities including missing data and variations in network structures, though it does not describe the mechanism for either in the material available here, so the exact imputation or masking strategy is something to check in the documentation before relying on it.
Installing tsl and the version constraints that come with it
The README's installation section begins with a prerequisite: PyTorch >= 1.9.0 must be installed before tsl, and the same paragraph continues into a PyG requirement that is cut off in the supplied text. The package itself is distributed on PyPI as torch-spatiotemporal, which is also the name used in the PyPI badge and the download badge, so the install command is pip install torch-spatiotemporal. The README notes Python >= 3.8 in the badge. The homepage is the Read the Docs site at torch-spatiotemporal.readthedocs.io, which hosts a quickstart page and an introductory notebook linked from the README header. The repository ships an examples directory, and the README points readers there to see how to train deep learning models on spatiotemporal data. Experiment configuration is expected to be Hydra-based, which means your training entry point will be a Hydra app and your hyperparameters will live in YAML files rather than in Python constants. That is a real commitment: if your team does not already use Hydra, adopting tsl means adopting Hydra's config composition and override syntax as well. The exact minimum PyG version is not visible in the truncated README, so check the installation page before pinning.
Where tsl gets in the way: irregular graphs, missing data and a young API
The README claims seamless handling of irregularities and missing data, and that claim deserves scrutiny. Irregularity in spatiotemporal data is not one problem, it is several: a node that stops reporting, a node that starts reporting mid-series, a sampling interval that drifts, and a graph topology that is rebuilt every window. A library can offer a default policy for each of these, but a default policy is exactly what you need to override in a real deployment, and the material here does not show how configurable those policies are. The second limitation is version stability. The supplied release history shows v0.9.3 in June 2023, v0.9.4 in August 2023 and v0.9.5 in July 2024, all still on a 0.x version number. A 0.x series means the maintainers reserve the right to change APIs between minor releases, and the gap between 0.9.4 and 0.9.5 is roughly eleven months. If you build on tsl, pin the exact version and read the release notes before upgrading, because a preprocessing change between 0.9.4 and 0.9.5 can silently alter your splits and therefore your reported metrics. The third limitation is scope. tsl is built around graph-structured spatial relations. If your spatial structure is a regular grid and your problem is plain multivariate time series forecasting, the PyG dependency is overhead you are paying for nothing, and a lighter library will get you there with less to learn.
What to use instead when tsl is the wrong shape
The closest alternative in the same research space is PyTorch Geometric Temporal, which also targets neural spatiotemporal forecasting on graphs and also builds on PyG. The difference is in what each library treats as the unit of work. PyG Temporal is built around temporal graph snapshots and recurrent or attention-based layers over those snapshots, so its abstractions centre on the message-passing step over time. tsl, by contrast, is organised around a full pipeline: its own dataset classes, its own preprocessing for scaling and resampling, Hydra-driven experiment configs, and a catalogue of published datasets and baseline models for benchmarking. If your task is to reproduce a specific published result on a standard dataset, tsl's pipeline orientation is the advantage. If your task is to plug a new temporal message-passing layer into an existing PyG training script, you will spend more time working around tsl's dataset and config conventions than you save. For non-graph spatiotemporal data, a general time series library such as Darts or GluonTS is a better fit, and the deciding question is simply whether your spatial relations are a graph or a grid.
Maintenance, licensing and the cost of staying current
tsl is MIT licensed, which is permissive and imposes no copyleft obligation on your own code. The practical licence question is not tsl itself but its dependencies: PyTorch, PyG and PyTorch Lightning each carry their own licences, and the datasets the library exposes may carry terms that restrict redistribution or commercial use independently of the code. Check the licence of any dataset you download through the library before shipping a model trained on it. On maintenance cost, the material shows a release cadence of roughly one minor version per year across 2023 and 2024, with the most recent push to the default branch in July 2026 and the repository not archived. That pattern is consistent with a research library maintained by a small group rather than a product with a support contract. Budget for reading release notes, pinning versions in your requirements file, and re-validating your preprocessing pipeline after each upgrade, because the parts most likely to change are the parts that affect your numbers. There is no commercial support path visible in the material, so your fallback is the issue tracker and the source.
Who should pick up tsl, and what to check before you do
tsl is a reasonable choice for a research group that needs to benchmark a new spatiotemporal GNN against published baselines on standard datasets, and that is comfortable working inside PyTorch Lightning and Hydra. The library's value in that setting is the preprocessing and dataset catalogue, which is the part of spatiotemporal research that consumes the most time and produces the least publishable output. It is a poor choice for a production forecasting service, where the same preprocessing that saves a researcher time becomes an opaque component you cannot debug at 3am, and where a 0.x version bump that changes split semantics is a regression you did not ask for. Before adopting it, do three things. Confirm that your installed PyTorch and PyG versions satisfy the requirements on the installation page, since the README only shows PyTorch >= 1.9.0 and the PyG constraint is truncated. Read the documentation for the dataset classes to see how train/validation/test splitting is defined for temporal data, because a random split on a time series will inflate your metrics and you need to know which one you are getting. And check how missing values are represented and whether the imputation policy is configurable, because that policy will determine whether your model learns the signal or the gaps.
Editorial conclusion
Adopt tsl if you are a researcher reproducing spatiotemporal GNN baselines and you can pin your dependency versions, because the last release in the supplied material is v0.9.5 from July 2024 and the API has moved between 0.9.3, 0.9.4 and 0.9.5. Do not adopt it as the data layer of a production forecasting service, where a schema change or a missing-value policy you cannot override becomes an incident. Before committing, verify that the PyTorch, PyG and PyTorch Lightning versions you already run satisfy what the install instructions require, and read the DisjointDataset and temporal_signal documentation to confirm the splitting and scaling semantics match your own evaluation protocol.
Community notes