DOCSEARCHbyAlgolia
Submit Docs

Torch Spatiotemporal (tsl)

repository·main·Indexed 18 days ago

https://github.com/torchspatiotemporal/tsl

A Python library for neural spatiotemporal data processing and Graph Neural Networks (GNNs), built on PyTorch, PyG (PyTorch Geometric), and PyTorch Lightning. It provides tools for the complete workflow from data preprocessing (scaling, detrending) to model prototyping for sensor networks. Key features include high-level APIs for custom datasets and models, handling of irregular data and missing observations, and integration with Hydra for reproducible experiment management via the tsl.experiment.Experiment class.

Tokens
8.2K
Snippets
16
Records
50
Agent score
61%

What's inside tsl

  1. Overview of Torch Spatiotemporal (tsl) features

    main

    tsl is a library designed to accelerate research on neural spatiotemporal data processing, specifically focusing on Graph Neural Networks (GNNs). It is built on top of PyTorch, PyG (PyTorch Geometric), and PyTorch Lightning.

    Key Capabilities

    • Customization: High-level APIs to build custom models and datasets for domains like sensor networks or environmental data.
    • Pre-built Assets: Access to a collection of existing spatiotemporal datasets and state-of-the-art baseline models.
    • Data Robustness: Built-in handling for irregular data streams, missing data, and varying network structures.
    • Preprocessing: Automated methods for scaling, resampling, and clustering time series.
    • Scalability: Seamless integration with PyTorch Lightning for scaling from single CPUs to GPU clusters.
    • Modularity: A collection of specialized neural layers for building complex spatiotemporal architectures.
    • Reproducibility: Integration with the Hydra framework for managing experiments.

  2. Overview of Torch Spatiotemporal (tsl)

    main

    Torch Spatiotemporal (tsl) is a Python library designed for neural spatiotemporal data processing, with a specific focus on Graph Neural Networks (GNNs). It provides a complete workflow from data preprocessing to model prototyping for sensor networks and spatiotemporal signals.

    Key capabilities include:

    • Dataset & Model Building: High-level APIs for creating spatiotemporal datasets compatible with PyTorch and PyG (PyTorch Geometric).
    • Data Irregularity Handling: Tools to manage missing data and variations in underlying network structures.
    • Automated Preprocessing: Built-in methods for scaling and detrending time series.
    • Scalable Training: Integration with PyTorch Lightning for scaling from single CPUs to GPU clusters.
    • Pre-built Models & Layers: Access to state-of-the-art spatiotemporal models and modular neural layers.
    • Reproducible Experiments: Uses the Hydra framework to standardize experiment configuration and reproducibility.

  3. Use the tsl.ops module for spatiotemporal operations

    main
    The tsl.ops module provides the primary API for performing operations and utilities on spatiotemporal data. It is organized into specialized submodules based on the scope of the operation. Use these submodules to access specific functionalities such as connectivity, frame array manipulation, imputation, pattern recognition, and AZ-testing.

  7. How to create new datasets using tsl prototypes

    main

    The tsl.datasets.prototypes submodule provides the base interfaces used to implement all datasets within the tsl library. When building a custom dataset, you should extend one of these prototype classes depending on your data structure.

    • Dataset: The most general base class for all datasets in tsl.
    • TabularDataset: Use this for multivariate time series data in tabular format (dimensions: time, node, and feature). It accepts pandas.DataFrame and/or numpy.ndarray. Missing values can be handled via nan entries or by explicitly setting the mask attribute.
    • DatetimeDataset: Use this if your observations are associated with specific dates and times. It extends TabularDataset and adds temporal functionalities like datetime_encoded and resample. It expects a pandas.DataFrame with a DatetimeIndex and columns using a MultiIndex (where the first level is nodes and the second is channels) for the target attribute.

  9. Configure experiment parameters using Hydra overrides

    main

    When running an experiment script, you can override default settings by passing key-value pairs in the format key=value.

    For example, in a traffic forecasting experiment, passing dataset=la instructs the program to use the la.yaml configuration file (which corresponds to the MetrLA dataset). Parameters defined in these specific subordinate config files will override any matching parameters in the default.yaml configuration.

    Available Dataset Options for Traffic Forecasting:

    • la (MetrLA)
    • bay
    • pems3
    • pems4
    • pems7
    • pems8

  10. Use Multi Layers to break permutation equivariance

    main

    The tsl.nn.layers.multi subpackage contains layers that apply different sets of parameters to different instances stacked in a dimension of the input data (such as the node dimension).

    Use Case: Use these layers when you need to process each node or time step with independent parameters, which effectively breaks the permutation equivariant property of the original operation.

  12. Use Encoders from tsl.nn.blocks.encoders

    main

    The tsl.nn.blocks.encoders module provides various encoder architectures for spatiotemporal data. These are categorized into standard encoders and recurrent encoders.

    Standard Encoders

    Standard encoders are available via the tsl.nn.blocks.encoders.enc_classes registry. These typically handle spatial or temporal feature extraction based on the specific class implementation.

    Recurrent Encoders

    For models requiring temporal dependency modeling through recurrence, use the classes listed in tsl.nn.blocks.encoders.rnn_classes. These implement recurrent architectures (like RNN, LSTM, or GRU variants) adapted for spatiotemporal inputs.