Visualization (pyavs.visualization)

ERF/joint/sensor-space plotting and eye-tracking-on-scene-image visualization.

MEG Plotting

MEG visualization functions for pyAVS.

This module provides visualization functions for MEG data including sensor space plots, ERF plots, and joint evoked plots.

pyavs.visualization.meg.plot_evoked_joint(evoked: mne.Evoked, times: float | List[float] | str | None = None, title: str | None = None, show: bool = True, **kwargs) → Figure

Create a joint plot of evoked MEG data: topomaps above, butterfly + GFP below.

Parameters:

• evoked (mne.Evoked) – The evoked data to plot.

• times (float, list of float, "peaks", or None) – Time points (in seconds) for topomaps. If None or “peaks”, the 3 largest GFP peaks are used.

• title (str, optional) – Ignored (no titles per convention).

• show (bool, optional) – Whether to call plt.show() (default: True).

Returns:

fig

Return type:

matplotlib.figure.Figure

pyavs.visualization.meg.plot_median_erf(epochs: mne.Epochs, event_type: str | None = None, ch_type: str = 'mag', times: float | List[float] | None = None, title: str | None = None, show: bool = True, **kwargs) → Figure

Plot median ERF (Event-Related Field) for MEG sensor space data.

This function computes the median across epochs and creates a joint plot showing both the time series and topographic maps.

Parameters:

• epochs (mne.Epochs) – The epochs data to plot

• event_type (str, optional) – Type of event to plot (if None, uses all epochs)

• ch_type (str, optional) – Channel type to plot (‘mag’, ‘grad’, or ‘meg’) (default: ‘mag’)

• times (float, list of float, or None) – Time points for topographic maps. If None, uses peak times

• title (str, optional) – Title for the plot

• show (bool, optional) – Whether to show the plot (default: True)

• **kwargs – Additional arguments passed to plot_joint

Returns:

fig – The figure object

Return type:

matplotlib.figure.Figure

pyavs.visualization.meg.plot_sensor_space_overview(epochs: mne.Epochs, event_types: List[str] | None = None, ch_type: str = 'mag', figsize: Tuple[int, int] = (12, 8), show: bool = True) → Figure

Create an overview plot of sensor space MEG data.

This function creates a comprehensive overview showing ERF plots for different event types in a grid layout.

Parameters:

• epochs (mne.Epochs) – The epochs data to plot

• event_types (list of str, optional) – List of event types to plot. If None, plots all available event types

• ch_type (str, optional) – Channel type to plot (‘mag’, ‘grad’, or ‘meg’) (default: ‘mag’)

• figsize (tuple, optional) – Figure size (width, height) (default: (12, 8))

• show (bool, optional) – Whether to show the plot (default: True)

Returns:

fig – The figure object

Return type:

matplotlib.figure.Figure

Eye-Tracking-on-Scene Plotting

Streamlined script to visualize eye tracking data on scene images.

Author: Philip Sulewski

class pyavs.visualization.events_on_scene.EyeTrackingPlotter(subjects: int | List[int], sessions: int | List[int], config: PyAVSConfig, data_path: str | None = None)

Bases: object

__init__(subjects: int | List[int], sessions: int | List[int], config: PyAVSConfig, data_path: str | None = None)

Initialize EyeTrackingPlotter with pyavs data loading.

Parameters:

• subjects (int or list of int) – Subject ID(s) to load data for

• sessions (int or list of int) – Session number(s) to load data for

• config (PyAVSConfig) – Configuration object with visual system parameters (required)

• data_path (str, optional) – Path to data directory. If None, uses config’s data path

load_scene(scene_id)

Load and scale scene image, fetching it on demand from COCO if not shipped/cached locally.

plot_scene(scene_id, subject=None, figsize=(10, 8), save_path=None, show_sequence=True, show_duration=False)

Plot fixations on a single scene.

plot_heatmap(scene_id, subjects=None, figsize=(12, 8), save_path=None, sigma=30, alpha=0.6, cmap='hot', levels=10, method='gaussian')

Plot professional fixation heatmap for a scene (pysaliency-style).

Parameters:

• scene_id (int) – Scene ID to plot

• subjects (list, optional) – List of subjects to include. If None, uses all subjects

• figsize (tuple, optional) – Figure size

• save_path (str, optional) – Path to save figure

• sigma (float, optional) – Gaussian blur sigma for heatmap smoothing

• alpha (float, optional) – Transparency of heatmap overlay

• cmap (str, optional) – Colormap for heatmap

• levels (int, optional) – Number of contour levels

• method (str, optional) – Heatmap method (‘gaussian’, ‘kde’, ‘histogram’)

plot_multi_subject_heatmap(scene_id, figsize=(15, 10), save_path=None, sigma=30, alpha=0.6, cmap='hot', show_individual=True)

Plot heatmaps for multiple subjects on the same scene.

Parameters:

• scene_id (int) – Scene ID to plot

• figsize (tuple, optional) – Figure size

• save_path (str, optional) – Path to save figure

• sigma (float, optional) – Gaussian blur sigma for heatmap smoothing

• alpha (float, optional) – Transparency of heatmap overlay

• cmap (str, optional) – Colormap for heatmap

• show_individual (bool, optional) – Whether to show individual subject heatmaps

plot_overview(n_scenes=6, save_path=None, show_heatmaps=False)

Plot overview grid of multiple scenes.

pyavs.visualization.events_on_scene.main()