pynaviz.qt.mainwindow#

Functions

scope(variables[, layout_path, ephys_format])

Launch the pynaviz GUI and block until the window is closed.

Classes

MainWindow([variables, layout_path])

Main application window for pynaviz.
class pynaviz.qt.mainwindow.MainWindow(variables=None, layout_path=None)[source]#

Bases: LayoutManagerMixin, QMainWindow

Main application window for pynaviz.

MainWindow is the top-level Qt widget that hosts all plot docks. It is normally created indirectly through pynaviz.scope(), but can also be instantiated directly when embedding pynaviz inside a larger Qt application or when writing tests.

Layout#

The window is divided into three areas:

  • Left panel — VariableDock: a tree widget listing all variables passed at construction time. Double-clicking an entry opens a new plot dock for that variable.

  • Central / right area — plot docks, one per visualised variable. Docks can be dragged, tabbed, floated, or closed.

  • Bottom status bar — a global time display and time-unit selector that reflects the current playback position shared across all docks.

Time synchronisation#

All open plot docks share a single ControllerGroup (self.ctrl_group). Panning or scrubbing in any dock updates the shared time and propagates to every other dock automatically.

Keyboard shortcuts#

Global (window-level):

  • Space — play / pause

  • Ctrl+S — save layout

  • Ctrl+O — load layout

Per-dock (active when the mouse is over or the canvas has focus):

  • r — reset view

  • ← / → — pan left / right by one page

  • y — toggle y-axis lock (span mode only; no-op in x-vs-y or image mode)

  • x — toggle x-axis lock (span and image mode; no-op in x-vs-y mode)

  • Ctrl+← / Ctrl+→ — jump to previous / next superposed epoch; requires at least one IntervalSet to be overlaid on that dock via Select IntervalSet (works on any plot type, not only IntervalSet plots)

  • i / d — increase / decrease contrast (TsdFrame) or marker size (TsGroup)

param variables:

Mapping of {name: object} to populate the variable panel. Accepts the same types as pynaviz.scope(). Defaults to an empty dict (no variables pre-loaded).

type variables:

dict or None, optional

param layout_path:

Path to a .json layout file produced by Save Layout. When given, the window restores the saved dock arrangement, camera views, and plot actions immediately after construction. Variables are matched to saved docks by name; unmatched docks are skipped.

type layout_path:

str, pathlib.Path, or None, optional

variables#

Live mapping of all variables currently known to the window, including any loaded via File → Open after construction.

Type:

dict

ctrl_group#

Shared time controller that synchronises all open plot docks.

Type:

ControllerGroup

variable_dock#

The left-panel tree widget.

Type:

VariableDock

add_dock_widget(variable, key_path, state_dict=None)[source]#

Add a new dock widget to the main window based on the variable or its key path.

Parameters:
Return type:

QDockWidget | None

closeEvent(event)[source]#

Handle the close event to ensure proper cleanup.

Parameters:

event (QEvent)

open_file()[source]#
open_folder()[source]#

Open a directory containing electrophysiology recordings (e.g. NeuroScopeIO).

staticMetaObject = PySide6.QtCore.QMetaObject("MainWindow" inherits "QMainWindow": )#
Parameters:

  • variables (dict | None)

  • layout_path (str | Path | None)

pynaviz.qt.mainwindow.scope(variables, layout_path=None, ephys_format=None)[source]#

Launch the pynaviz GUI and block until the window is closed.

Parameters:

  • variables (dict, list, tuple, or str) –

    The data to visualise. Several input formats are accepted:

    dict (recommended) — keys become the display names shown in the variable panel; values are the objects to visualise:

    viz.scope({
    "spikes": tsgroup,
    "lfp": tsdframe,
    "epochs": interval_set,
    "recording": "/path/to/video.mp4",
})

    list / tuple — names are inferred automatically from each object’s class name (TsGroup, TsdFrame, …). Duplicate class names get a numeric suffix (TsGroup_0, TsGroup_1, …):

    viz.scope([tsgroup, tsdframe, interval_set])

    str — a single file path, treated the same as a one-element list.

    Supported object types:

    • nap.Ts — spike-train / event timestamps

    • nap.Tsd — one-dimensional time series

    • nap.TsdFrame — multi-channel time series (pandas DataFrame with time index)

    • nap.TsdTensor — N-D time series (e.g. pose estimates)

    • nap.TsGroup — collection of spike trains, optionally with metadata

    • nap.IntervalSet — epoch / interval data, optionally with metadata

    • nap.NWBFile — NWB file opened with pynapple; all contained objects are unpacked and added individually

    • nap.EphysReader — Neo-backed electrophysiology reader; all contained objects are unpacked and added individually

    • str / pathlib.Path pointing to:

      • .nwb file — loaded via pynapple, objects unpacked as above

      • .npz file — loaded via pynapple, must contain a single pynapple object

      • .mp4 / .avi / .mov / .mkv — video file, displayed in a video player dock

    • VideoHandler — a pynaviz video handler instance (advanced use; allows sharing a pre-initialised decoder across docks)

    Objects that do not match any of the above are silently ignored.

  • layout_path (str or None, optional) – Path to a previously saved .json layout file. When provided the GUI restores the dock arrangement, camera views, and applied actions (group-by, sort-by, color-by, interval overlays, …) from that file. Variables in variables are matched to saved docks by their key name; docks whose variable is not found are skipped.

  • ephys_format (str or None, optional) – Neo IO class name to use when loading electrophysiology files or directories via nap.EphysReader (e.g. "PlexonIO", "NeuroScopeIO"). When None (default) the format is auto-detected from the file/directory contents.

Notes

This call blocks until the GUI window is closed. It starts (or reuses) a QApplication internally, so it is safe to call from a plain Python script or a Jupyter notebook.