# Plotting

SGN-TS provides plotting utilities for visualizing `SeriesBuffer` and `TSFrame`
data. Requires matplotlib (`pip install sgn-ts[plot]`).

## Plot a Buffer

```{.python notest}
import numpy as np
from sgnts.base import SeriesBuffer
from sgnts.plotting import plot_buffer

buf = SeriesBuffer(offset=0, sample_rate=2048, data=np.random.randn(2048))
fig, ax = plot_buffer(buf)
```

## Plot a Frame

`plot_frame` plots all buffers in a `TSFrame`, with gap regions shaded
automatically:

```{.python notest}
from sgnts.plotting import plot_frame

fig, ax = plot_frame(frame)
```

## Time Units

Control the x-axis unit with `time_unit`:

```{.python notest}
plot_buffer(buf, time_unit="s")    # Seconds
plot_buffer(buf, time_unit="ms")   # Milliseconds
plot_buffer(buf, time_unit="ns")   # Nanoseconds
plot_buffer(buf, time_unit="gps")  # GPS time (default)
```

## Gap Visualization

Gaps are shaded in red by default. Customize with `gap_color` and `gap_alpha`,
or disable with `show_gaps=False`:

```{.python notest}
plot_frame(frame, gap_color="gray", gap_alpha=0.2)
plot_frame(frame, show_gaps=False)
```

## Multi-channel Data

For multi-dimensional buffers, select specific channels with `channel`:

```{.python notest}
# Plot only channel 0
plot_buffer(buf, channel=0)

# Plot channels 0 and 1
plot_buffer(buf, channel=(0, 1))
```

## Plotting on Existing Axes

Pass a matplotlib `Axes` to overlay data on an existing plot:

```{.python notest}
import matplotlib.pyplot as plt

fig, ax = plt.subplots()
plot_buffer(buf1, ax=ax, label="Signal A")
plot_buffer(buf2, ax=ax, label="Signal B")
ax.legend()
```

## TSPlotSink

Use `TSPlotSink` to plot data directly from a pipeline:

```{.python notest}
from sgn import Pipeline
from sgnts.sources import FakeSeriesSource
from sgnts.sinks import TSPlotSink

src = FakeSeriesSource(
    name="src",
    source_pad_names=["out"],
    signal_type="sin",
    rate=2048,
    duration=1,
)
snk = TSPlotSink(name="plot")

Pipeline().connect(src, snk).run()
```
