# User Guide

SGN-TS builds on [SGN](https://docs.ligo.org/greg/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](../background/timeseries-concepts.md).

## 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](work-with-offsets-and-time.md)** — the timing system
   that underlies everything
2. **[Buffers and Frames](use-buffers-and-frames.md)** — data containers:
   TSFrame (top-level), SeriesBuffer (samples), EventBuffer/EventFrame (events)
3. **[Time Slices](use-time-slices.md)** — offset-range arithmetic for segment
   operations
4. **[Audio Adapter](configure-audio-adapter.md)** — configuring overlap,
   stride, and streaming behavior in elements
5. **[Array Backends](use-array-backends.md)** — switching between NumPy and
   PyTorch
6. **[Plotting](use-plotting.md)** — visualizing buffers, frames, and pipeline
   output

For writing custom elements, see the
[Developer Guide](../developer/develop-elements.md).
