Plotting

Burst Plots

tad.plotting.burst.plot_bursts_on_raster(r, bursts, *, ax=None, tstart=None, tstop=None, channels=None, alpha=0.15, show=False)[source]

Convenience: plot a raster then overlay burst spans.

Parameters:

  • r – Raster instance (expects .plot(…) method).

  • bursts (BurstDetectionResult) – BurstDetectionResult.

  • ax (Axes | None) – Axes to draw on. If None, creates a new figure/axes.

  • tstart (float | None) – Time window forwarded to Raster.plot.

  • tstop (float | None) – Time window forwarded to Raster.plot.

  • channels (Sequence[int | str] | None) – Channels to overlay bursts for (burst detection channels, not raster plot channels). If None, overlays all channels present in bursts.

  • alpha (float) – Span transparency.

  • show (bool) – If True, calls plt.show().

Returns:

Axes containing raster + burst overlays.

Return type:

matplotlib.axes.Axes

tad.plotting.burst.plot_bursts_spans(bursts, *, ax=None, channels=None, ymin=0.0, ymax=1.0, alpha=0.15, show=False)[source]

Overlay burst intervals as shaded spans on an axis.

Parameters:

  • bursts (BurstDetectionResult) – Output of tad.metrics.bursts.detect_bursts.

  • ax (Axes | None) – Matplotlib Axes to draw on. If None, creates a new figure/axes.

  • channels (Sequence[int | str] | None) – Optional subset of channels to plot. If None, plot all channels present in bursts.channels.

  • ymin (float) – Vertical span fraction in axis coordinates, passed to ax.axvspan. Default (0,1) shades full vertical extent.

  • ymax (float) – Vertical span fraction in axis coordinates, passed to ax.axvspan. Default (0,1) shades full vertical extent.

  • alpha (float) – Span transparency.

  • show (bool) – If True, calls plt.show(). Default False so you can compose plots.

Returns:

Axis with spans added.

Return type:

matplotlib.axes.Axes

Notes

  • This helper intentionally draws spans in axis coordinates so it can be used both on raster plots and on rate plots.

  • Coloring is uniform by default for clarity; if you later want per-channel colors, we can add an option.

ISI Plots

tad.plotting.isi.plot_logisih_threshold(diag, *, ax=None, show=False)[source]

Plot log-ISIH histogram/smoothed curve and the selected threshold.

Parameters:

  • diag (LogISIThresholdDiagnostics) – Diagnostics from choose_isi_threshold_logisih.

  • ax (Axes | None) – Matplotlib axes.

  • show (bool) – Whether to call plt.show().

Return type:

Axes

Firing Rate Plots

tad.plotting.rates.order_channels_by_activity(Y, *, method='population_corr')[source]

Compute an ordering of channels given a (n_channels, n_time) activity matrix.

Parameters:

  • Y (ndarray) – Activity matrix (e.g., firing rate), shape (n_channels, n_time).

  • method (Literal['population_corr', 'pca1', 'greedy_corr_chain']) – Ordering method: - “population_corr”: sort by corr(channel, population_mean) - “pca1”: sort by projection on first principal component - “greedy_corr_chain”: build a chain where adjacent channels are highly correlated

Returns:

order – Indices that reorder channels.

Return type:

ndarray, shape (n_channels,)

tad.plotting.rates.plot_firing_rate_heatmap(fr, *, ax=None, channels=None, normalize='none', robust=True, vmin=None, vmax=None, cmap='viridis', show_colorbar=True, order=None, show=False)[source]

Plot per-channel firing rate as a channels × time heatmap.

Parameters:

  • fr (FiringRateCurveResult) – Output of tad.metrics.rates.firing_rate_curve.

  • ax (Axes | None) – Axes to draw on. If None, creates a new figure and axes.

  • channels (Sequence[int] | None) – Optional subset of channels by row indices in fr.fr_ch. If None, uses all channels in stored order.

  • normalize (str) –

    • “none”: show raw FR (Hz)

    • ”zscore”: z-score each channel across time (highlights synchrony patterns)

    • ”max”: divide each channel by its max (unit peak per channel)

    • ”log1p”: show log(1 + FR) (useful when FR has rare large peaks)

  • robust (bool) – If True and vmin/vmax are not provided, choose color limits using percentiles (2nd, 98th) to avoid a few extreme bins dominating the colormap.

  • vmin (float | None) – Explicit color limits. Overrides robust scaling.

  • vmax (float | None) – Explicit color limits. Overrides robust scaling.

  • cmap (str) – Matplotlib colormap name.

  • show_colorbar (bool) – If True, add a colorbar.

  • order (str | None) – Optional method to reorder channels by activity pattern similarity for better visualization. See order_channels_by_activity for available methods.

  • show (bool) – If True, calls plt.show().

Returns:

Axes containing the plot.

Return type:

matplotlib.axes.Axes

Notes

This is a visualization helper. It does not alter the metric computation.

tad.plotting.rates.plot_firing_rate_stack(fr, *, ax=None, channels=None, mode='stack', spacing=None, normalize='none', color='b', show=False)[source]

Plot per-channel firing-rate curves in an EEG-like view.

Parameters:

  • fr (FiringRateCurveResult) – Output of tad.metrics.rates.firing_rate_curve.

  • ax (Axes | None) – Axes to draw on. If None, creates a new figure and axes.

  • channels (Sequence[int] | None) – Optional subset of channels by row indices in fr.fr_ch. If None, plots all rows (in stored order).

  • mode (str) –

    • “stack”: stacked traces with vertical offsets (EEG-like)

    • ”overlay”: all traces overlaid without offsets (butterfly)

  • spacing (float | None) – Vertical spacing between traces (only for mode=”stack”). If None, uses 1.2 * median(max(fr)-min(fr)) across selected channels.

  • normalize (str) –

    • “none”: plot raw Hz

    • ”zscore”: z-score each channel across time

    • ”max”: scale each channel by its own max (unit peak)

  • show (bool) – If True, calls plt.show().

  • color (str)

Returns:

Axes containing the plot.

Return type:

matplotlib.axes.Axes

Notes

This is a plotting helper; it does not change metric definitions.

PSTH Plots

tad.plotting.psth.plot_psth_heatmap(psth, *, ax=None, kind='rate', robust=True, show_colorbar=True, show=True)[source]

Plot PSTH as a channel × time heatmap.

Parameters:

  • psth (PSTHResult) – PSTHResult from compute_psth.

  • ax (Axes | None) – Matplotlib axes.

  • kind (str) – “rate” or “counts”.

  • robust (bool) – If True, clip color range to 2–98 percentiles for readability.

  • show_colorbar (bool) – Add a colorbar.

  • show (bool) – If True, calls plt.show().

Return type:

Axes

tad.plotting.psth.plot_psth_lines(psth, *, ax=None, channels=None, kind='rate', show=True)[source]

Plot PSTH as lines for selected channels.

Parameters:

  • psth (PSTHResult) – PSTHResult from compute_psth.

  • ax (Axes | None) – Matplotlib axes.

  • channels (Sequence[int] | None) – Row indices into psth.counts/psth.rate_hz. If None, plots up to first 10.

  • kind (str) – “rate” (Hz) or “counts” (counts/bin/stim).

  • show (bool) – If True, calls plt.show().

Return type:

Axes