singlepanelplot

syncopy.singlepanelplot(*data, trials='all', channels='all', tapers='all', toilim=None, foilim=None, avg_channels=True, avg_tapers=True, 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 single-panel figure(s)

Usage Summary

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

AnalogDatatrials, channels, toi/toilim

Examples

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

Examples

>>> fig1, fig2 = spy.singlepanelplot(data1, data2, channels=["channel1", "channel2"],
                                     tapers=[3, 0], foilim=[30, 80], avg_channels=False,
                                     avg_tapers=True, grid=True, overlay=False)
>>> cfg = spy.StructDict()
>>> cfg.trials = [1, 0, 3]; cfg.toilim = [-0.25, 0.5]; cfg.vmin=0.2; cfg.vmax=1.0
>>> fig = spy.singlepanelplot(cfg, tfData1)

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., foilim is not a valid plotting-selector for an AnalogData object.

  • trials (list (integers) or None or "all") – Trials to average across. Either list of integers representing trial numbers (can include repetitions and need not be sorted), “all” or None. If data is a (series of) AnalogData object(s), trials may be None, so that 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). For all other Syncopy data objects, trials must not be None.

  • 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. Boundaries 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 averaging is performed resulting in multiple plots, each representing a single channel.

  • avg_tapers (bool) – If True, plot SpectralData objects averaged across tapers specified by tapers. If False, no averaging is performed resulting in multiple plots, each representing a single taper.

  • 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 of the shown dataset is used. When comparing multiple contour maps, 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 the shown dataset 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 as axis panel-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.singlepanelplot(data, trials=...)
>>> cfg = spy.StructDict()
>>> cfg.trials = ...
>>> spy.singlepanelplot(cfg, data)
>>> cfg.data = data
>>> spy.singlepanelplot(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, singlepanelplot() 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 singlepanelplot class methods for detailed usage examples specific to the respective Syncopy data object type.

See also

multipanelplot()

visualize Syncopy objects using multi-panel figure(s)

syncopy.AnalogData.singlepanelplot()

singlepanelplot for AnalogData objects

syncopy.SpectralData.singlepanelplot()

singlepanelplot for SpectralData objects