User Guide

This comprehensive guide covers all features and configuration options of LiveNeuro based on the actual implementation.

Getting Started

Basic Workflow

Create visualization object with desired parameters
Launch with run()
Interact with hover, click, and zoom
Export static images if needed

from liveneuro import LiveNeuro

# Step 1: Create
viz = LiveNeuro(display_mode="lyr")

# Step 2: Launch
viz.run()  # Auto inline in Jupyter; external browser otherwise

# Step 3: Interact (in browser/notebook)
# Step 4: Export
viz.export_images(output_dir="./plots", time_idx=30)

Run Modes

Note

In IPython shells (outside notebooks), explicitly pass mode="external" to run() to start a visualization that can be accessed in a browser.

Interpreter / shell: uses built-in MNE sample data if y is omitted; launches a server on a random port (explicit mode="external" recommended).
```
viz = LiveNeuro()
viz.run(mode="external")
```

Notebook: auto-selects mode="inline" (embedded IFrame). Choose explicitly if you want a browser or a Lab tab.

viz = LiveNeuro()
viz.run()                    # inline by default in notebooks; use mode="external" for shells
# viz.run(mode="jupyterlab")  # open in JupyterLab tab
# viz.run(mode="external")    # force external browser

Understanding Display Modes

Display modes control which anatomical views are shown and in what order.

Anatomical Coordinate System

X-axis (Sagittal): Side view, left-right through brain
Y-axis (Coronal): Front view, front-back through brain
Z-axis (Axial): Top view, top-bottom through brain
L: Left hemisphere lateral view
R: Right hemisphere lateral view

Single View Modes

Use single letters for individual views:

viz = LiveNeuro(display_mode="x")  # Sagittal only
viz = LiveNeuro(display_mode="y")  # Coronal only
viz = LiveNeuro(display_mode="z")  # Axial only
viz = LiveNeuro(display_mode="l")  # Left hemisphere only
viz = LiveNeuro(display_mode="r")  # Right hemisphere only

Multi-View Modes

Combine letters for multiple views:

# Orthogonal views (special keyword)
viz = LiveNeuro(display_mode="ortho")  # x + y + z

# Hemisphere combinations
viz = LiveNeuro(display_mode="lr")     # Left + Right
viz = LiveNeuro(display_mode="lyr")    # Left + Coronal + Right (default)
viz = LiveNeuro(display_mode="lzr")    # Left + Axial + Right

# Axis combinations
viz = LiveNeuro(display_mode="xz")     # Sagittal + Axial
viz = LiveNeuro(display_mode="yx")     # Coronal + Sagittal
viz = LiveNeuro(display_mode="yz")     # Coronal + Axial

Four-View Modes

For comprehensive anatomical coverage:

# Four views in different orders
viz = LiveNeuro(display_mode="lyrz")   # L + Coronal + R + Axial
viz = LiveNeuro(display_mode="lzry")   # L + Axial + R + Coronal

Note: Order of letters determines display order of anatomical projections (left-to-right).

Layout Modes

Vertical Layout (Default)

When to use:

General use, including 1–4 projections
When the detailed activity time course should be prominent
When you want more horizontal space per projection

Characteristics:

Detailed activity time course on top
Brain projections arranged beneath
Good for multiple projections while preserving horizontal space

viz = LiveNeuro(
    display_mode="lyr",
    layout_mode="vertical"  # Default
)

Horizontal Layout

When to use:

Wide screens or presentations
When spatial layout (left-to-right comparison) is the focus

Characteristics:

Detailed activity time course on the left
Brain projections arranged to the right

viz = LiveNeuro(
    display_mode="lyrz",
    layout_mode="horizontal"
)

Arrow Visualization

Understanding Arrows

Arrows represent vector fields in brain data:

Direction: Shows orientation of activity (e.g., current flow)
Length: Indicates magnitude (controlled by arrow_scale)
Visibility: Filtered by arrow_threshold

Arrow Scale Parameter

The arrow_scale parameter (default: 1.0) controls arrow length:

# Short arrows for dense data
viz = LiveNeuro(arrow_scale=0.5)

# Default balanced length
viz = LiveNeuro(arrow_scale=1.0)

# Long arrows for sparse data
viz = LiveNeuro(arrow_scale=2.0)

Recommendations:

Dense vector fields: 0.5 - 0.8
Moderate density: 1.0 (default)
Sparse fields: 1.2 - 2.0

Arrow Threshold Parameter

The arrow_threshold parameter filters arrows by magnitude:

# Show all arrows
viz = LiveNeuro(arrow_threshold=None)

# Auto threshold (10% of maximum magnitude)
viz = LiveNeuro(arrow_threshold='auto')

# Custom threshold
viz = LiveNeuro(arrow_threshold=0.15)

When to use:

None: Small datasets or when all vectors are important
'auto': Good default for most cases
float: Fine-tune based on data characteristics

Combined Arrow Optimization

For best results, combine both parameters:

# Dense data with many small vectors
viz = LiveNeuro(
    arrow_scale=0.7,
    arrow_threshold='auto'
)

# Sparse data with clear patterns
viz = LiveNeuro(
    arrow_scale=1.5,
    arrow_threshold=0.05
)

Color Mapping

Built-in Colormaps

LiveNeuro supports Plotly’s built-in colorscales:

# Sequential colormaps
viz = LiveNeuro(cmap='YlOrRd')    # Yellow-Orange-Red (default)
viz = LiveNeuro(cmap='Hot')       # Hot (red/orange/yellow)
viz = LiveNeuro(cmap='Viridis')   # Perceptually uniform
viz = LiveNeuro(cmap='OrRd')      # Orange-Red
viz = LiveNeuro(cmap='Reds')      # Red scale

See https://plotly.com/python/builtin-colorscales/ for all options.

Custom Colormaps

Create custom colorscales with transparency:

# Custom gradient with transparency
custom_cmap = [
    [0, 'rgba(255,255,0,0.5)'],    # Yellow, 50% transparent
    [0.5, 'rgba(255,165,0,0.8)'],  # Orange, 80% opaque
    [1, 'rgba(255,0,0,1.0)']       # Red, fully opaque
]

viz = LiveNeuro(cmap=custom_cmap)

Color Range:

Automatically scaled to data range (min to max)
Consistent across all views and time points
Unified colorbar shows current scaling
Override manually with vmin / vmax to lock the range

viz = LiveNeuro(vmin=-2.0, vmax=2.0)

Activity Time Course Plot Modes

Full Mode (Default)

Shows a sampled set of source traces plus statistics (random subset for readability):

viz = LiveNeuro(show_max_only=False)

Displays:

Random subset of source activity traces
Mean activity
Maximum activity across all sources

Simplified Mode

Shows only summary statistics:

viz = LiveNeuro(show_max_only=True)

Displays:

Mean activity
Maximum activity

When to use:

You want a clean summary without individual traces
Presentations or screenshots where mean/max is enough

Interactive Features

Hover Information

Brain Plots:

Hover over any voxel to see activity value
Shows magnitude at current time point

Detailed activity time course:

Hover over time axis to see max and min activity
Displays values for all visible traces

Zoom and Pan

Mouse Controls:

Mouse Wheel: Zoom in/out
Click + Drag: Box zoom (default drag mode)
Pan: Select the pan tool in the toolbar, then drag to move the view
Double-click: Reset to original view

Data Input

Using Built-in MNE Sample Data

Simplest option for testing and learning:

# Use built-in MNE sample data
viz = LiveNeuro(y=None)

Characteristics:

1589 sources in volumetric source space
76 time points (-100ms to 400ms)
Vector data (3D current dipoles)
Requires Eelbrain installed

Using Eelbrain NDVar

For your own data:

from eelbrain import datasets
from liveneuro import LiveNeuro

# Load Eelbrain data
data_ds = datasets.get_mne_sample(src='vol', ori='vector')
y = data_ds['src']  # NDVar with dimensions (case, time, source, space)

# Visualize
viz = LiveNeuro(y=y)

Expected Dimensions:

Vector data: ([case,] time, source, space)
Scalar data: ([case,] time, source)
If case dimension present: mean is computed automatically

Using MNE VolVectorSourceEstimate

For MNE volume vector source estimates, pass the source estimate together with the matching source space. The source estimate provides vector data and time values; the source space provides the 3D coordinates needed for projections.

from pathlib import Path

import mne
from mne.minimum_norm import apply_inverse, read_inverse_operator

from liveneuro import LiveNeuro

sample_dir = Path(mne.datasets.sample.data_path())
data_dir = sample_dir / "MEG" / "sample"
subjects_dir = sample_dir / "subjects"

evoked = mne.read_evokeds(
    data_dir / "sample_audvis-ave.fif",
    condition="Left Auditory",
    baseline=(None, 0),
    proj=True,
)

inverse_operator = read_inverse_operator(
    data_dir / "sample_audvis-meg-vol-7-meg-inv.fif"
)
stc = apply_inverse(
    evoked,
    inverse_operator,
    lambda2=1.0 / 9.0,
    method="MNE",
    pick_ori="vector",
)
src = mne.read_source_spaces(
    subjects_dir / "sample" / "bem" / "volume-7mm-src.fif"
)

viz = LiveNeuro(y=stc, src=src)

Running the Application

Browser Mode

Opens in external browser:

viz = LiveNeuro()
viz.run(mode="external")  # Random port; defaults to inline in notebooks, external browser otherwise

# Or specify port
viz.run(port=8888, mode="external")  # Force browser if inline is detected

Jupyter Modes (Default)

Multiple options for Jupyter notebooks:

# Inline display (embedded in notebook) - auto size
viz.run()

# JupyterLab tab (opens in separate tab)
viz.run(mode='jupyterlab')

Exporting Images

Basic Export

Export current view as static image:

result = viz.export_images(
    output_dir="./images",
    time_idx=30,
    format="png"
)

if result["status"] == "success":
    for plot_type, filepath in result["files"].items():
        print(f"{plot_type}: {filepath}")

Exports:

All brain projection views
Activity Time Course plot
Separate files for each

Supported Formats

# PNG (default, best for presentations)
viz.export_images(format="png")

# JPEG (smaller file size)
viz.export_images(format="jpg")

# SVG (vector, scalable)
viz.export_images(format="svg")

# PDF (publication quality)
viz.export_images(format="pdf")

Performance Optimization

For Large Datasets

Use arrow threshold:

viz = LiveNeuro(arrow_threshold='auto')

Simplify detailed activity time course:
```
viz = LiveNeuro(show_max_only=True)
```

Use focused display modes:

viz = LiveNeuro(display_mode="lr")  # Fewer views

Combined Optimization

# Optimized for large dataset
viz = LiveNeuro(
    display_mode="lr",          # Only 2 views
    layout_mode="horizontal",   # Better layout
    arrow_scale=0.7,            # Smaller arrows
    arrow_threshold='auto',     # Filter weak vectors
    show_max_only=True,         # Simplified time course
    cmap='Hot'
)

Best Practices

For Presentations

viz = LiveNeuro(
    display_mode="lyr",          # Standard comparison view
    layout_mode="horizontal",    # Wide screen friendly
    arrow_scale=1.2,            # Slightly larger arrows
    arrow_threshold='auto',     # Clean visualization
    show_max_only=True,         # Focus on patterns
    cmap='Hot'                  # High contrast
)

viz.run(mode='external')  # Full screen

For Publications

viz = LiveNeuro(
    display_mode="lyr",
    arrow_scale=1.0,
    arrow_threshold='auto',
    cmap='YlOrRd'               # Publication-friendly
)

# Export high-quality images
viz.export_images(
    output_dir="./publication_figures",
    time_idx=30,
    format="pdf"  # Vector format for publications
)

For Interactive Exploration

viz = LiveNeuro(
    display_mode="lyrz",         # Comprehensive views
    layout_mode="horizontal",    # Better for exploration
    arrow_scale=1.0,
    arrow_threshold=None,        # See all vectors initially
    show_max_only=False,         # Full time-course information
    cmap='Viridis'
)

viz.run()  # Enable debug with debug=True when troubleshooting

Troubleshooting

Common Issues

Issue: Random port is inconvenient

Solution:

viz.run(port=8888)  # Use fixed port

Issue: Arrows too dense or unclear

Solution:

viz = LiveNeuro(
    arrow_scale=0.7,            # Reduce size
    arrow_threshold='auto'      # Filter weak ones
)

Issue: Detailed activity time course too cluttered

Solution:

viz = LiveNeuro(show_max_only=True)

Issue: Slow performance

Solution:

viz = LiveNeuro(
    display_mode="lr",          # Fewer views
    arrow_threshold='auto',     # Fewer arrows
    show_max_only=True         # Simpler time course
)

Issue: Export fails

Check:

Output directory exists or can be created
Kaleido is installed (included in dependencies, upgrade if needed): pip install -U kaleido
Sufficient disk space

Debug Mode

Debug mode is off by default for a clean UI. Enable it when troubleshooting:

viz.run(debug=True)

This provides:

Detailed console output
Error tracebacks
Performance information

User Guide

Getting Started

Basic Workflow

Run Modes

Understanding Display Modes

Anatomical Coordinate System

Single View Modes

Multi-View Modes

Four-View Modes

Layout Modes

Vertical Layout (Default)

Horizontal Layout

Arrow Visualization

Understanding Arrows

Arrow Scale Parameter

Arrow Threshold Parameter

Combined Arrow Optimization

Color Mapping

Built-in Colormaps

Custom Colormaps

Activity Time Course Plot Modes

Full Mode (Default)

Simplified Mode

Interactive Features

Hover Information

Time Navigation

Zoom and Pan

Data Input

Using Built-in MNE Sample Data

Using Eelbrain NDVar

Using MNE VolVectorSourceEstimate

Running the Application

Browser Mode

Jupyter Modes (Default)

Exporting Images

Basic Export

Supported Formats

Performance Optimization

For Large Datasets

Combined Optimization

Best Practices

For Presentations

For Publications

For Interactive Exploration

Troubleshooting

Common Issues

Debug Mode