User Guide

SGN-TS builds on SGN to add time-series handling. SGN's core framework is data-agnostic — a Frame carries any Python object. SGN-TS constrains this to uniformly sampled time-series data, which solves several problems you would otherwise need to handle yourself.

New Concepts Beyond SGN

SGN-TS introduces three ideas on top of SGN's Pipeline, Element, Frame, and Pad abstractions:

Uniformly sampled data

All data is represented as fixed-sample-rate arrays in SeriesBuffer objects, carried inside TSFrame containers. Only power-of-2 sample rates are allowed (1, 2, 4, ... up to 16384 Hz by default). This rigidity enables precise, rounding-error-free timing.

Offset-based temporal bookkeeping

Time is tracked via integer offsets — sample counts at the maximum sample rate — rather than floating-point seconds or integer nanoseconds. This keeps single-sample-point accuracy even for applications designed to run uninterrupted for years.

Synchronous data flow

Sources must produce data at consistent rates in offset space. SGN-TS enforces this through automatic frame alignment across pads at different sample rates, preventing data from piling up.

For a deeper discussion of these design decisions, see TimeSeries Concepts.

Guide Overview

This guide covers practical usage of SGN-TS's core tools, ordered so that each topic builds on the previous:

1. Offsets and Time — the timing system that underlies everything
2. Buffers and Frames — data containers: TSFrame (top-level), SeriesBuffer (samples), EventBuffer/EventFrame (events)
3. Time Slices — offset-range arithmetic for segment operations
4. Audio Adapter — configuring overlap, stride, and streaming behavior in elements
5. Array Backends — switching between NumPy and PyTorch
6. Plotting — visualizing buffers, frames, and pipeline output

For writing custom elements, see the Developer Guide.