Visualization#

Matplotlib plots for inspecting stimulus timing and neural activity. This API is separate from vneurotk.vision, which extracts DNN representations from images. Install plotting support with vneurotk[viz]; see the visualization guide for runnable examples.

Supported data and units#

BaseData.plot supports continuous recordings and pre-epoched epochs; epochs are flattened across trial and time for display. It rejects patterns because aggregated pattern rows have no time axis. Neural data and a positive, finite neuro_info["sfreq"] must be available. Configured trial metadata is optional: an unconfigured time-series can still show neural activity, while configured stimulus labels, trial IDs, and trial windows add the trial-setting panel.

For both public entry points, display-window bound types determine units:

  • integral bounds, including NumPy integer scalars, are sample indices;

  • non-integral real bounds, including values such as 2.0, are seconds and are converted with sfreq;

  • the two finite bounds must be ordered and overlap the recording.

This makes 2 sample 2, but 2.0 two seconds. A trial window follows the same integer-samples/non-integral-real-seconds convention.

BaseData.plot#

The convenience method uses the recording’s neural data, sampling frequency, labels, trial IDs, and trial window. It returns a caller-owned Matplotlib Figure for annotation, saving, or closing. Plotting requires Matplotlib from the viz extra.

BaseData.plot(window=(0.0, 5.0), figsize=(6, 3), cmap_neuro='Greys', cmap_ontime='summer', color_offtime='black', marker_size=40)

Plot neural activity alongside stimulus labels.

Parameters:
windowtuple of float | int

Display window. Float values are seconds, int values are samples.

figsizetuple of float

Figure size (width, height).

cmap_neurostr

Colormap for neural heatmap.

cmap_ontimestr

Colormap for in-trial time.

color_offtimestr

Color for off-trial points.

marker_sizefloat

Scatter marker size.

Returns:
matplotlib.figure.Figure
Raises:
ValueError

If data_mode="patterns", which has no time axis.

Parameters:

  • window (tuple[float | int, float | int])

  • figsize (tuple[float, float])

  • cmap_neuro (str)

  • cmap_ontime (str)

  • color_offtime (str)

  • marker_size (float)

plot_data#

Use the lower-level function for arrays that are not wrapped in BaseData. neuro must be a nonempty two-dimensional array shaped (n_samples, n_channels); visual must be a one-dimensional label array with one value per sample; and sfreq must be positive and finite. Null visual values represent no stimulus.

trial and trial_window are optional but must be supplied together. trial must contain one null or nonnegative integer trial ID per sample. trial_window may be one shared ordered pair or one pair per referenced trial ID. Trial windows must span at least one sample.

vneurotk.viz.data.plot_data(neuro, visual, sfreq, trial=None, trial_window=None, figsize=(6, 3), window=(0.0, 5.0), cmap_neuro='Greys', cmap_ontime='summer', color_offtime='black', marker_size=40)#

Plot neural activity alongside stimulus labels.

Parameters:
neuronp.ndarray

Neural data, shape (n_samples, n_channels).

visualnp.ndarray

Label vector, shape (n_samples,).

sfreqfloat

Sampling frequency in Hz.

trialnp.ndarray or None

Trial-ID vector, shape (n_samples,). When provided together with trial_window, every in-trial timepoint is scatter-plotted and coloured by its position inside the trial window.

trial_windowlist of real, list of two-value lists, or None

A single [start, end] relative to stimulus onset, or one such window per trial ID. Per-trial windows support epochs whose stimulus onset differs between trials. Real non-integral values are interpreted as seconds and integral values as samples (the same numeric convention used by configure()).

figsizetuple of float

Figure size (width, height) in inches.

windowtuple of float | int

Display window (start, end). float values are interpreted as seconds, int values as samples.

cmap_neurostr

Colormap for the neural activity heatmap.

cmap_ontimestr

Colormap for in-trial time of stimulus labels.

color_offtimestr

Color for non-stimulus time points.

marker_sizefloat

Marker size for scatter points.

Returns:
matplotlib.figure.Figure

The generated figure.

Parameters:

  • neuro (ndarray)

  • visual (ndarray)

  • sfreq (float)

  • trial (ndarray | None)

  • trial_window (Sequence[int | float | integer | floating] | Sequence[Sequence[int | float | integer | floating]] | None)

  • figsize (tuple[float, float])

  • window (tuple[float, float])

  • cmap_neuro (str)

  • cmap_ontime (str)

  • color_offtime (str)

  • marker_size (float)

Return type:

matplotlib.pyplot.Figure

See the visualization example for a complete synthetic evoked-response workflow and the DNN vision API when the goal is image feature extraction rather than plotting.