Synaesthesia

Composable, timestamp-aligned sensor datasets for PyTorch and PyTorch Lightning.

Synaesthesia combines sensor readers, aligns observations on a shared timeline, builds temporal windows, and transforms dictionary batches. It includes HDF5 reading and extension classes for CSV, image folders, video, and multispectral imagery.

This release candidate targets Python 3.14. APIs may change before version 1.0.

Installation

Version 0.2.0 is unreleased. PyPI currently serves 0.1.0, which does not include the changes documented here. Use the source checkout below to try the candidate. Install the currently published release with:

pip install synaesthesia
# or: uv add synaesthesia

For development or to try the release candidate from source:

git clone https://github.com/danieledema/synaesthesia.git
cd synaesthesia
uv sync --locked --dev
uv run python examples/quickstart.py

Quick start

The complete runnable example creates two temporary CSV recordings and defines a concrete CSV reader. Its main pipeline is:

from torch.utils.data import DataLoader
from synaesthesia.abstract.multi_signal_dataset import MultiSignalDataset
from synaesthesia.abstract.sequential_dataset import SequentialDataset
from synaesthesia.collates import BatchCollate

# speed and temperature are the concrete readers defined in the example.
aligned = MultiSignalDataset([speed, temperature], aggregation="all", fill="last")
windows = SequentialDataset(aligned, n_samples=2, timestamp_idx="last")
loader = DataLoader(
    windows,
    batch_size=2,
    collate_fn=BatchCollate(item_keys=r"^DemoRig_"),
)
batch = next(iter(loader))

The full example prints:

[0, 10, 20, 30]
[[1.0, 2.0], [2.0, 3.0]]
[[10.0, 10.0], [10.0, 30.0]]
[10, 20]

These are the aligned timeline, batched speed and temperature windows, and window timestamps. Selecting sensor keys keeps metadata timestamps as exact integers; BatchCollate converts selected numeric values to float32.

Documentation

• Installation and quick start
• Sensor readers and timestamp conventions
• Alignment policies
• Sequences and recording wrappers
• Batching and augmentations
• Lightning, sampling, and caching
• Current limitations
• API reference
• Release notes and release checklist

Build browsable HTML locally:

uv sync --locked --dev --group docs
uv run --locked --group docs sphinx-build -W --keep-going -b html docs/source docs/_build/html

Open docs/_build/html/index.html. Classes are imported from their defining modules; the package namespaces do not re-export them.

Development

uv sync --locked --dev
uv run --locked pytest
uv run --locked pytest --cov --cov-report=term-missing
uv run --locked ruff check tests examples docs/source/conf.py

Tests generate temporary inputs and need no external recordings. CI tests CPython 3.14 on Linux and macOS. See CONTRIBUTING.md for the dataset contract and documentation workflow.

License

Apache License 2.0.