multipanelplot

syncopy.multipanelplot(*data, trials='all', channels='all', tapers='all', toilim=None, foilim=None, avg_channels=False, avg_tapers=True, avg_trials=True, panels='channels', interp='spline36', cmap='plasma', vmin=None, vmax=None, title=None, grid=None, overlay=True, fig=None, **kwargs)[source]

Plot contents of Syncopy data object(s) using multi-panel figure(s)

Usage Summary

List of Syncopy data objects and respective valid plotting commands/selectors:

AnalogDatatrials, channels, toi/toilim

Examples

>>> fig = spy.multipanelplot(data, channels=["channel1", "channel2"])
>>> cfg = spy.StructDict()
>>> cfg.trials = [5, 3, 0]; cfg.toilim = [0.25, 0.5]
>>> fig = spy.multipanelplot(cfg, data1, data2, overlay=True)
SpectralDatatrials, channels, tapers, toi/toilim, foi/foilim

Examples

>>> fig1, fig2 = spy.multipanelplot(data1, data2, channels=["channel1", "channel2"])
>>> cfg = spy.StructDict()
>>> cfg.toilim = [0.25, 0.5]; cfg.foilim=[30, 80]; cfg.avg_trials = False
>>> cfg.avg_channels = True; cfg.panels = "trials"
>>> fig = spy.multipanelplot(cfg, tfData)

The parameters listed below can be provided as is or a via a cfg configuration ‘structure’, see Notes for details.

Parameters
  • data (Syncopy data object(s)) – One or more non-empty Syncopy data object(s). Note: if multiple datasets are provided, they must be all of the same type (e.g., AnalogData) and should contain the same or at least comparable channels, trials etc. Consequently, some keywords are only valid for certain types of Syncopy objects, e.g., “freqs” is not a valid plotting-selector for an AnalogData object.

  • trials (list (integers) or None or "all") – Either list of integers representing trial numbers (can include repetitions and need not be sorted), “all” or None. If trials is None, no trial information is used and the raw contents of provided input dataset(s) is plotted (Warning: depending on the size of the supplied dataset(s), this might be very memory-intensive).

  • channels (list (integers or strings), slice, range or "all") – Channel-selection; can be a list of channel names (['channel3', 'channel1']), a list of channel indices ([3, 5]), a slice (slice(3, 10)) or range (range(3, 10)). Selections can be unsorted and may include repetitions. If multiple input objects are provided, channels needs to be a valid selector for all supplied datasets.

  • tapers (list (integers or strings), slice, range or "all") – Taper-selection; can be a list of taper names (['dpss-win-1', 'dpss-win-3']), a list of taper indices ([3, 5]), a slice (slice(3, 10)) or range (range(3, 10)). Selections can be unsorted and may include repetitions but must match exactly, be finite and not NaN. If multiple input objects are provided, tapers needs to be a valid selector for all supplied datasets.

  • toilim (list (floats [tmin, tmax]) or None) – Time-window [tmin, tmax] (in seconds) to be extracted from each trial. Window specifications must be sorted and not NaN but may be unbounded. Edges tmin and tmax are included in the selection. If toilim is None, the entire time-span in each trial is selected. If multiple input objects are provided, toilim needs to be a valid selector for all supplied datasets. Note toilim is only a valid selector if trials is not None.

  • foilim (list (floats [fmin, fmax]) or "all") – Frequency-window [fmin, fmax] (in Hz) to be extracted from each trial; Window specifications must be sorted and not NaN but may be unbounded. Boundaries fmin and fmax are included in the selection. If foilim is None or all frequencies are selected for plotting. If multiple input objects are provided, foilim needs to be a valid selector for all supplied datasets.

  • avg_channels (bool) – If True, plot input dataset(s) averaged across channels specified by channels. If False no channel-averaging is performed.

  • avg_tapers (bool) – If True, plot SpectralData objects averaged across tapers specified by tapers. If False, no averaging is performed.

  • avg_trials (bool) – If True, plot input dataset(s) averaged across trials specified by trials. Specific panel allocation depends on value of avg_channels and avg_tapers (if applicable). For AnalogData objects setting avg_trials to True but trials to None triggers a SPYValueError.

  • panels (str) – Panel specification. Only valid for SpectralData objects. Can be “channels”, “trials”, or “tapers”. Panel specification and averaging flags have to align, i.e., if panels is trials then avg_trials must be False, otherwise the code issues a SPYWarning and exits. Note that a multi-panel visualization of time-frequency datasets requires averaging across two out of three data dimensions (i.e., two of the flags avg_channels, avg_tapers and avg_trials must be True).

  • interp (str or None) – Interpolation method used for plotting two-dimensional contour maps such as time-frequency power spectra. To see a list of available interpolation methods use the command list(mpl.image._interpd_.keys()). Please consult the matplotlib documentation for more details. Has no effect on line-plots.

  • cmap (str) – Colormap used for plotting two-dimensional contour maps such as time-frequency power spectra. To see a list of available color-maps use the command list(mpl.cm._cmap_registry.keys()). Pleasee consult the matplotlib documentation for more details. Has no effect on line-plots.

  • vmin (float or None) – Lower bound of data-range covered by colormap when plotting two-dimensional contour maps such as time-frequency power spectra. If vmin is None the minimal (absolute) value across all shown panels is used. When comparing multiple objects, all visualizations should use the same vmin to ensure quantitative similarity of peak values.

  • vmax (float or None) – Upper bound of data-range covered by colormap when plotting two-dimensional contour maps such as time-frequency power spectra. If vmax is None the maximal (absolute) value of all shown panels is used. When comparing multiple contour maps, all visualizations should use the same vmin to ensure quantitative similarity of peak values.

  • title (str or None) – If str, title specifies figure title, if None, an auto-generated title is used.

  • grid (bool or None) – If True, grid-lines are drawn, if None or False no grid-lines are rendered.

  • overlay (bool) – If True, and multiple input objects were provided, supplied datasets are plotted on top of each other (in the order of submission). If a single object was provided, overlay = True and fig is a Figure, the supplied dataset is overlaid on top of any existing plot(s) in fig. Note 1: using an existing figure to overlay dataset(s) is only supported for figures created with this routine. Note 2: overlay-plotting is not supported for time-frequency SpectralData objects.

  • fig (matplotlib.figure.Figure or None) – If None, new Figure instance(s) are created for provided input dataset(s). If fig is a Figure, the code attempts to overlay provided input dataset(s) on top of existing plots in fig. Note: overlay-plots are only supported for figures generated with this routine. Only a single figure can be provided. Thus, in case of multiple input datasets with overlay = False, any supplied fig is ignored.

Returns

fig – Either single figure (single input dataset or multiple input datasets with overlay = True) or list of figures (multiple input datasets and overlay = False).

Return type

(list of) matplotlib.figure.Figure instance(s)

Notes

This function can be either called providing its input arguments directly or via a cfg configuration ‘structure’. For instance, the following function calls are equivalent

>>> spy.multipanelplot(data, trials=...)
>>> cfg = spy.StructDict()
>>> cfg.trials = ...
>>> spy.multipanelplot(cfg, data)
>>> cfg.data = data
>>> spy.multipanelplot(cfg)

Please refer to Syncopy for FieldTrip Users for further details.

This function uses matplotlib to render data visualizations. Thus, usage of Syncopy’s plotting capabilities requires a working matplotlib installation.

The actual rendering is performed by class methods specific to the provided input object types (e.g., AnalogData). Thus, multipanelplot() is mainly a convenience function and management routine that invokes the appropriate drawing code.

Data subset selection for plotting is performed using selectdata(), thus additional in-place data-selection via a select keyword is not supported.

Examples

Please refer to the respective multipanelplot class methods for detailed usage examples specific to the respective Syncopy data object type.

See also

singlepanelplot()

visualize Syncopy objects using single-panel figure(s)

syncopy.AnalogData.multipanelplot()

multipanelplot for AnalogData objects

syncopy.SpectralData.multipanelplot()

multipanelplot for SpectralData objects