API Reference

This page contains the complete API reference for LiveNeuro.

Main Class

class liveneuro.LiveNeuro(y: NDVar | mne.VolVectorSourceEstimate | SampleDataNDVar | None = None, cmap: str | list = 'YlOrRd', vmin: float | None = None, vmax: float | None = None, show_max_only: bool = False, arrow_threshold: float | str | None = None, arrow_scale: float = 1.0, realtime: bool = False, layout_mode: str = 'horizontal', display_mode: str = 'lyr', show_labels: bool = False, src: mne.SourceSpaces | None = None)[source]

Bases: object

Interactive 2D brain visualization for brain data using Plotly and Dash.

Visualization for 3D vector field time series. Provides activity time course with interactive 2D projections of brain volume vector data.

Parameters:

  • y – Data to plot ([case,] time, source[, space]). If y has a case dimension, the mean is plotted. If y has a space dimension, the norm is plotted. If None, uses MNE sample data for demonstration. Pass an Eelbrain NDVar, an MNE VolVectorSourceEstimate with src, or the sample data object returned by liveneuro.create_sample_brain_data().

  • cmap – Plotly colorscale for heatmaps. Can be: - Built-in colorscale name (e.g., ‘YlOrRd’, ‘OrRd’, ‘Reds’, ‘Viridis’) - Custom colorscale list (e.g., [[0, ‘white’], [1, ‘red’]]) Default is ‘YlOrRd’ (Yellow-Orange-Red) which works well with white background and doesn’t obscure arrows. See https://plotly.com/python/builtin-colorscales/ for all available options.

  • vmin – Optional lower bound for the color range. If provided, locks the minimum for all projections and time points.

  • vmax – Optional upper bound for the color range. If provided, locks the maximum for all projections and time points.

  • show_max_only – If True, butterfly plot shows only mean and max traces. If False, butterfly plot shows individual source traces, mean, and max. Default is False.

  • arrow_threshold – Threshold for displaying arrows in brain projections. Only arrows with magnitude greater than this value will be displayed. If None, all arrows are shown. If ‘auto’, uses 10% of the maximum magnitude as threshold. Default is None.

  • arrow_scale – Relative scale factor for arrow length in brain projections. The default value of 1.0 provides a good balance for most datasets. Use 0.5 for half the length, 2.0 for double the length, etc. Useful for adjusting visualization clarity when vectors have large magnitudes or high density. Default is 1.0. Typical range: 0.5 (short) to 2.0 (long).

  • layout_mode – Layout arrangement mode for the visualization interface. Options: - ‘vertical’: Traditional layout with butterfly plot on top, brain views below - ‘horizontal’: Compact layout with butterfly plot on left, brain views on right (default) Default is ‘horizontal’.

  • display_mode – Anatomical view mode for brain projections. Options: - ‘ortho’: Orthogonal views (sagittal + coronal + axial) - Default - ‘x’: Sagittal view only - ‘y’: Coronal view only - ‘z’: Axial view only - ‘xz’: Sagittal + Axial views - ‘yx’: Coronal + Sagittal views - ‘yz’: Coronal + Axial views - ‘l’: Left hemisphere view only - ‘r’: Right hemisphere view only - ‘lr’: Both hemisphere views (left + right) - ‘lzr’: Left + Axial + Right hemispheres - ‘lyr’: Left + Coronal + Right (GlassBrain default - best for hemisphere comparison) - ‘lzry’: Left + Axial + Right + Coronal (4-view comprehensive) - ‘lyrz’: Left + Coronal + Right + Axial (4-view comprehensive) Default is ‘lyr’ (GlassBrain standard) for optimal hemisphere comparison.

  • show_labels – If True, shows plot titles and legends (e.g., ‘Source Activity Time Series’, ‘Source 0’, ‘Source 1’, etc.). If False, hides all titles and legends for a cleaner visualization. Default is False.

  • src – Matching MNE SourceSpaces object when y is an mne.VolVectorSourceEstimate. Required for MNE source estimates because the source estimate stores vertex ids while LiveNeuro needs 3D source coordinates.

Notes

Expected input format

  • For vector data: NDVar with dimensions ([case,] time, source, space)

  • For scalar data: NDVar with dimensions ([case,] time, source)

  • For MNE vector volume data: VolVectorSourceEstimate plus matching src

  • If case dimension present: mean across cases is plotted

  • If space dimension present: norm across space is plotted for butterfly plot

  • create_sample_brain_data returns a minimal NDVar-like object compatible with the y parameter for quick demos

The main visualization class for interactive 2D brain projections with activity time-course plots.

run(port: int | None = None, debug: bool = False, mode: str | None = None) → None[source]

Run the interactive visualization.

Parameters:

  • port – Port number for the server. If None, uses a random port.

  • debug – Enable Dash debug mode.

  • mode – Display mode. If None, auto-selects based on environment. Common values are "inline", "jupyterlab", and "external".

export_images(output_dir: str = './images', time_idx: int | None = None, format: str = 'png') → dict[str, object][source]

Export plots as image files.

Parameters:

  • output_dir – Directory to save image files.

  • time_idx – Time index to export. If None, uses 0.

  • format – Image format (e.g., "png", "jpg", "svg", "pdf").

Returns:

Dictionary with export status and file paths.

Return type:

dict

Sample Data Module

liveneuro.create_sample_brain_data(n_sources: int = 200, n_times: int = 50, has_vector_data: bool = True, random_seed: int = 42) → SampleDataNDVar[source]

Create synthetic brain data for visualization testing.

Parameters:

  • n_sources (int, default 200) – Number of brain sources/vertices.

  • n_times (int, default 50) – Number of time points.

  • has_vector_data (bool, default True) – Whether to include vector (3D) data or just scalar data.

  • random_seed (int, default 42) – Random seed for reproducible data.

Returns:

Minimal NDVar-like object with the fields LiveNeuro expects: data (array), coords (array), times (array), has_vector_data (bool), n_sources (int), n_times (int).

Return type:

SampleDataNDVar

Data Format

Input Data Expectations

Vector Data (with direction and magnitude):

  • Eelbrain NDVar with dimensions: ([case,] time, source, space)

  • MNE VolVectorSourceEstimate with matching src SourceSpaces object

  • Built-in MNE sample data object returned by create_sample_brain_data()

Scalar Data (magnitude only):

  • Eelbrain NDVar with dimensions: ([case,] time, source)

  • Single value per source at each time point

  • Sample-data object returned by create_sample_brain_data(has_vector_data=False)

Built-in Sample Data:

  • 1589 sources in volumetric source space

  • 76 time points (-100ms to 400ms)

  • Vector data (3D current dipoles)

Exceptions

The library may raise the following exceptions:

ValueError

  • Invalid display_mode string

  • Invalid layout_mode (not “vertical” or “horizontal” and not registered in LAYOUTS)

  • Invalid parameter values

ImportError

  • Missing required dependencies

  • Eelbrain not installed when using eelbrain-specific features

RuntimeError

  • Data processing errors

  • Visualization rendering errors