pynaviz.base_plot#

Simple plotting class for each pynapple object. Create a unique canvas/renderer for each class

Classes

`PlotIntervalSet`(data[, index, parent, ...])	A visualization of a set of non-overlapping epochs (`nap.IntervalSet`).
`PlotTs`(data[, index, parent, background])	Visualization for pynapple timestamps object (`nap.Ts`) as vertical tick marks.
`PlotTsGroup`(data[, index, parent, background])	Visualization for plotting multiple spike trains (`nap.TsGroup`) as a raster plot.
`PlotTsd`(data[, index, parent, background])	Visualization for 1-dimensional pynapple time series object (`nap.Tsd`)
`PlotTsdFrame`(data[, index, parent, ...])	Visualization of a multi-column pynapple time series (`nap.TsdFrame`).

class pynaviz.base_plot.PlotIntervalSet(data, index=None, parent=None, background='black')[source]#

Bases: _BasePlot

A visualization of a set of non-overlapping epochs (nap.IntervalSet).

This class allows dynamic rendering of each interval in a nap.IntervalSet, with interactive controls for span navigation. It supports coloring, grouping, and sorting of intervals based on metadata.

Parameters:

data (nap.IntervalSet) – The set of intervals to be visualized, with optional metadata.
index (Optional[int], default None) – Unique ID for synchronizing with external controllers.
parent (Optional[Any], default None) – Optional GUI parent (e.g. QWidget in Qt).
background (str | None)

controller#

Active interactive controller for zooming or selecting.

Type:: SpanController

graphic#

Dictionary of rectangle meshes for each interval.

Type:: dict[str, gfx.Mesh] or gfx.Mesh

get_plot_state()[source]#

Return interval visibility as a JSON-serializable list.

Returns:: {"visible": [bool, …]} ordered by manager index.
Return type:: dict

group_by(metadata_name, **kwargs)[source]#

Group the intervals vertically by a metadata field.

Parameters:: metadata_name (str) – Metadata key to group by.

jump_next()[source]#

Jump to the start of the next interval in the data.

Return type:: None

jump_previous()[source]#

Jump to the start of the previous interval in the data.

Return type:: None

set_plot_state(state, available_vars=None)[source]#

Restore interval visibility.

Parameters:

state (dict) – Value produced by get_plot_state().
available_vars (dict, optional) – Unused.

sort_by(metadata_name, mode='ascending')[source]#

Vertically sort the plotted intervals by a metadata field.

Parameters:

metadata_name (str) – Metadata key to sort by.
mode (str | None)

Return type:

None

class pynaviz.base_plot.PlotTs(data, index=None, parent=None, background='black')[source]#

Bases: _BasePlot

Visualization for pynapple timestamps object (nap.Ts) as vertical tick marks.

Parameters:

data (nap.Ts) – A Pynapple Ts object containing spike timestamps to visualize.
index (Optional[int], default None) – Controller index used for synchronized interaction (e.g., panning across multiple plots).
parent (Optional[Any], default None) – Optional parent widget (e.g., in a Qt context).
background (str | None)

jump_next()[source]#

Jump to the next timestamp in the data.

Return type:: None

jump_previous()[source]#

Jump to the previous timestamp in the data.

Return type:: None

class pynaviz.base_plot.PlotTsGroup(data, index=None, parent=None, background='black')[source]#

Bases: _BasePlot

Visualization for plotting multiple spike trains (nap.TsGroup) as a raster plot.

Each unit in the group is displayed as a row, where spike times are rendered as point markers (vertical ticks). Units can be sorted or grouped based on metadata. A SpanController is used to synchronize view ranges across plots.

Parameters:

data (nap.TsGroup) – A Pynapple TsGroup object containing multiple spike trains.
index (int, optional) – Identifier for the controller instance, useful when synchronizing multiple plots.
parent (QWidget, optional) – Parent widget in a Qt application, if applicable.
background (str | None)

get_plot_state()[source]#

Return spike marker sizes and visibility keyed by neuron ID.

Returns:: {"scale": {neuron_id: size, …}, "visible": [bool, …]}.
Return type:: dict

group_by(metadata_name, **kwargs)[source]#

Group the raster vertically by a metadata field.

Parameters:: metadata_name (str) – Metadata key to group by.

set_plot_state(state, available_vars=None)[source]#

Restore spike marker sizes and visibility.

Parameters:

state (dict) – Value produced by get_plot_state(). Integer neuron-ID keys are recovered from their JSON string representation.
available_vars (dict, optional) – Unused, dict of available variables.

sort_by(metadata_name, mode='ascending')[source]#

Sort the raster vertically by a metadata field.

Parameters:

metadata_name (str) – Metadata key to sort by.
mode (str, optional) – “ascending” (default) or “descending”.

Return type:

None

class pynaviz.base_plot.PlotTsd(data, index=None, parent=None, background='black')[source]#

Bases: _BasePlot

Visualization for 1-dimensional pynapple time series object (nap.Tsd)

This class renders a continuous 1D time series as a line plot and manages user interaction through a SpanController. It supports optional synchronization across multiple plots and rendering via WebGPU.

Parameters:

data (nap.Tsd) – The time series data to be visualized (timestamps + values).
index (Optional[int], default None) – Controller index used for synchronized interaction (e.g., panning across multiple plots).
parent (Optional[Any], default None) – Optional parent widget (e.g., in a Qt context).
background (str | None)

controller#

Manages viewport updates, syncing, and linked plot interactions.

Type:: SpanController

line#

The main line plot showing the time series.

Type:: gfx.Line

class pynaviz.base_plot.PlotTsdFrame(data, index=None, parent=None, window_size=None, display_mode='lines', background='black')[source]#

Bases: _BasePlot

Visualization of a multi-column pynapple time series (nap.TsdFrame).

Supports three display modes toggled at runtime:

lines (default): each column rendered as a line with vertex colors.
image: all columns as a heatmap texture.
x_vs_y: one column plotted against another with a time marker.

Parameters:

data (nap.TsdFrame) – The column-based time series data.
index (int, optional) – Controller ID for synchronizing with other plots.
parent (optional) – GUI parent widget (e.g. QWidget).
window_size (float, optional) – Streaming window duration in seconds. If None, computed to fit up to 256 MB of memory.
display_mode (str, default "lines") – Initial display mode (“lines” or “image”). Toggle with the “m” key.
background (str or tuple, optional) – Background color (e.g. "white", "black", "#272822").

color_by(metadata_name, cmap_name='viridis', vmin=0.0, vmax=100.0)[source]#

Apply color mapping to channels based on a metadata field.

Parameters:

metadata_name (str) – Metadata field used for color mapping.
cmap_name (str, default "viridis") – Matplotlib colormap name.
vmin (float, default 0.0) – Minimum value for colormap normalization.
vmax (float, default 100.0) – Maximum value for colormap normalization.

Return type:

None

get_plot_state()[source]#

Return the current display mode and its serializable state.

Returns:: {"mode": str, "mode_state": ...} where mode_state is whatever the active mode’s get_state() returns.
Return type:: dict

property graphic#: The active pygfx graphic, delegated to the current display mode.

group_by(metadata_name, **kwargs)[source]#

Group channels vertically by a metadata field.

Parameters:: metadata_name (str) – Metadata key to group by.

plot_x_vs_y(x_col, y_col, color=None, thickness=1.0, markersize=10.0)[source]#

Plot one column versus another with a time-point marker.

Parameters:

x_col (str or int or float) – Column name for the x-axis.
y_col (str or int or float) – Column name for the y-axis.
color (str or tuple, optional) – Line color. Defaults to a color that contrasts with the background.
thickness (float, default 1.0) – Line thickness.
markersize (float, default 10.0) – Size of the time marker.

Return type:

None

set_plot_state(state, available_vars=None)[source]#

Restore display mode and mode-specific state.

Parameters:

state (dict or None) – Value produced by get_plot_state().
**available_vars – Unused, no extra argument needed.

Return type:

None

sort_by(metadata_name, mode='ascending')[source]#

Sort channels vertically by a metadata field.

Parameters:

metadata_name (str) – Metadata key to sort by.
mode (str, optional) – “ascending” (default) or “descending”.

Return type:

None