SpectralData

class syncopy.SpectralData(data=None, filename=None, trialdefinition=None, samplerate=None, channel=None, taper=None, freq=None, dimord=None)[source]

Bases: syncopy.datatype.continuous_data.ContinuousData

Multi-channel, real or complex spectral data

This class can be used for representing any data with a frequency, channel, and optionally a time axis. The datatype can be complex or float.

Attributes Summary

cfg

Dictionary of previous operations on data

channel

list of recording channel names

container

data

array-like object representing data without trials

dimord

ordered list of data dimension labels

filename

freq

frequency axis in Hz

log

log of previous operations on data

mode

write mode for data, ‘r’ for read-only, ‘w’ for writable

sampleinfo

nTrials x 2 numpy.ndarray of [start, end] sample indices

samplerate

sampling rate of uniformly sampled data in Hz

tag

taper

list of window functions used

time

trigger-relative time axes of each trial

trialdefinition

]]

trialinfo

nTrials x M numpy.ndarray with numeric information about each trial

trials

list-like array of trials

Methods Summary

clear()

Clear loaded data from memory

copy([deep])

Create a copy of the data object in memory.

definetrial([trialdefinition, pre, post, …])

(Re-)define trials of a Syncopy data object

multipanelplot([trials, channels, tapers, …])

Plot contents of SpectralData objects using multi-panel figure(s)

save([container, tag, filename, overwrite, …])

Save data object as new spy container to disk (syncopy.save_data())

selectdata([trials, channels, toi, toilim, …])

Create new SpectralData object from selection

singlepanelplot([trials, channels, tapers, …])

Plot contents of SpectralData objects using single-panel figure(s)

Attributes Documentation

cfg

Dictionary of previous operations on data

channel

list of recording channel names

Type

numpy.ndarray

container
data

array-like object representing data without trials

Trials are concatenated along the time axis.

dimord

ordered list of data dimension labels

Type

list(str)

filename
freq

frequency axis in Hz

Type

numpy.ndarray

log

log of previous operations on data

Type

str

mode

write mode for data, ‘r’ for read-only, ‘w’ for writable

FIXME: append/replace with HDF5?

Type

str

sampleinfo

nTrials x 2 numpy.ndarray of [start, end] sample indices

samplerate

sampling rate of uniformly sampled data in Hz

Type

float

tag
taper

list of window functions used

Type

numpy.ndarray

time

trigger-relative time axes of each trial

Type

list(float)

trialdefinition

]]

Type

nTrials x >=3 numpy.ndarray of [start, end, offset, trialinfo[

trialinfo

nTrials x M numpy.ndarray with numeric information about each trial

Each trial can have M properties (condition, original trial no., …) coded by numbers. This property are the fourth and onward columns of BaseData._trialdefinition.

trials

list-like array of trials

Methods Documentation

clear()

Clear loaded data from memory

Calls flush method of HDF5 dataset or memory map. Memory maps are deleted and re-instantiated.

copy(deep=False)

Create a copy of the data object in memory.

Parameters

deep (bool) – If True, a copy of the underlying data file is created in the temporary Syncopy folder.

Returns

in-memory copy of data object

Return type

Syncopy data object

See also

syncopy.save()

definetrial(trialdefinition=None, pre=None, post=None, start=None, trigger=None, stop=None, clip_edges=False)

(Re-)define trials of a Syncopy data object

Data can be structured into trials based on timestamps of a start, trigger and end events:

            start    trigger    stop
|---- pre ----|--------|---------|--- post----|
Parameters
  • obj (Syncopy data object (BaseData-like)) –

  • trialdefinition (EventData object or Mx3 array) – [start, stop, trigger_offset] sample indices for M trials

  • pre (float) – offset time (s) before start event

  • post (float) – offset time (s) after end event

  • start (int) – event code (id) to be used for start of trial

  • stop (int) – event code (id) to be used for end of trial

  • trigger – event code (id) to be used center (t=0) of trial

  • clip_edges (bool) – trim trials to actual data-boundaries.

Returns

Return type

Syncopy data object (BaseData-like))

Notes

definetrial() supports the following argument combinations:

>>> # define M trials based on [start, end, offset] indices
>>> definetrial(obj, trialdefinition=[M x 3] array)
>>> # define trials based on event codes stored in <:class:`EventData` object>
>>> definetrial(obj, trialdefinition=<EventData object>,
                pre=0, post=0, start=startCode, stop=stopCode,
                trigger=triggerCode)
>>> # apply same trial definition as defined in <:class:`EventData` object>
>>> definetrial(<AnalogData object>,
                trialdefinition=<EventData object w/sampleinfo/t0/trialinfo>)
>>> # define whole recording as single trial
>>> definetrial(obj, trialdefinition=None)
multipanelplot(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, fig=None, **kwargs)

Plot contents of SpectralData objects using multi-panel figure(s)

Please refer to syncopy.multipanelplot() for detailed usage information.

Examples

Use 16 panels to show frequency range 30-80 Hz of first 16 channels in freqData averaged across trials 2, 4, and 6:

>>> fig = spy.multipanelplot(freqData, trials=[2, 4, 6], channels=range(16),
                             foilim=[30, 80], panels="channels")

Same settings, but each panel represents a trial:

>>> fig = spy.multipanelplot(freqData, trials=[2, 4, 6], channels=range(16),
                             foilim=[30, 80], panels="trials", avg_trials=False,
                             avg_channels=True)

Plot time-frequency contents of channels ‘ecog_mua1’ and ‘ecog_mua2’ of tfData

>>> fig = spy.multipanelplot(tfData, channels=['ecog_mua1', 'ecog_mua2'])

Note that multi-panel overlay plotting is not supported for SpectralData objects.

See also

syncopy.multipanelplot()

visualize Syncopy data objects using multi-panel plots

save(container=None, tag=None, filename=None, overwrite=False, memuse=100)

Save data object as new spy container to disk (syncopy.save_data())

FIXME: update docu

Parameters
  • container (str) – Path to Syncopy container folder (*.spy) to be used for saving. If omitted, a .spy extension will be added to the folder name.

  • tag (str) – Tag to be appended to container basename

  • filename (str) – Explicit path to data file. This is only necessary if the data should not be part of a container folder. An extension (*.<dataclass>) will be added if omitted. The tag argument is ignored.

  • overwrite (bool) – If True an existing HDF5 file and its accompanying JSON file is overwritten (without prompt).

  • memuse (scalar) – Approximate in-memory cache size (in MB) for writing data to disk (only relevant for VirtualData or memory map data sources)

Examples

>>> save_spy(obj, filename="session1")
>>> # --> os.getcwd()/session1.<dataclass>
>>> # --> os.getcwd()/session1.<dataclass>.info
>>> save_spy(obj, filename="/tmp/session1")
>>> # --> /tmp/session1.<dataclass>
>>> # --> /tmp/session1.<dataclass>.info
>>> save_spy(obj, container="container.spy")
>>> # --> os.getcwd()/container.spy/container.<dataclass>
>>> # --> os.getcwd()/container.spy/container.<dataclass>.info
>>> save_spy(obj, container="/tmp/container.spy")
>>> # --> /tmp/container.spy/container.<dataclass>
>>> # --> /tmp/container.spy/container.<dataclass>.info
>>> save_spy(obj, container="session1.spy", tag="someTag")
>>> # --> os.getcwd()/container.spy/session1_someTag.<dataclass>
>>> # --> os.getcwd()/container.spy/session1_someTag.<dataclass>.info
selectdata(trials=None, channels=None, toi=None, toilim=None, foi=None, foilim=None, tapers=None)[source]

Create new SpectralData object from selection

Please refer to syncopy.selectdata() for detailed usage information.

Examples

>>> spcBand = spc.selectdata(foilim=[10, 40])

See also

syncopy.selectdata()

create new objects via deep-copy selections

singlepanelplot(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, fig=None, **kwargs)

Plot contents of SpectralData objects using single-panel figure(s)

Please refer to syncopy.singlepanelplot() for detailed usage information.

Examples

Show frequency range 30-80 Hz of channel ‘ecog_mua2’ averaged across trials 2, 4, and 6:

>>> fig = spy.singlepanelplot(freqData, trials=[2, 4, 6], channels=["ecog_mua2"],
                              foilim=[30, 80])

Overlay channel ‘ecog_mua3’ with same settings:

>>> fig2 = spy.singlepanelplot(freqData, trials=[2, 4, 6], channels=['ecog_mua3'],
                               foilim=[30, 80], fig=fig)

Plot time-frequency contents of channel ‘ecog_mua1’ present in both objects tfData1 and tfData2 using the ‘viridis’ colormap, a plot grid, manually defined lower and upper color value limits and no interpolation

>>> fig1, fig2 = spy.singlepanelplot(tfData1, tfData2, channels=['ecog_mua1'],
                                     cmap="viridis", vmin=0.25, vmax=0.95,
                                     interp=None, grid=True, overlay=False)

Note that overlay plotting is not supported for time-frequency objects.

See also

syncopy.singlepanelplot()

visualize Syncopy data objects using single-panel plots

singlepanelplot(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, fig=None, **kwargs)

Plot contents of SpectralData objects using single-panel figure(s)

Please refer to syncopy.singlepanelplot() for detailed usage information.

Examples

Show frequency range 30-80 Hz of channel ‘ecog_mua2’ averaged across trials 2, 4, and 6:

>>> fig = spy.singlepanelplot(freqData, trials=[2, 4, 6], channels=["ecog_mua2"],
                              foilim=[30, 80])

Overlay channel ‘ecog_mua3’ with same settings:

>>> fig2 = spy.singlepanelplot(freqData, trials=[2, 4, 6], channels=['ecog_mua3'],
                               foilim=[30, 80], fig=fig)

Plot time-frequency contents of channel ‘ecog_mua1’ present in both objects tfData1 and tfData2 using the ‘viridis’ colormap, a plot grid, manually defined lower and upper color value limits and no interpolation

>>> fig1, fig2 = spy.singlepanelplot(tfData1, tfData2, channels=['ecog_mua1'],
                                     cmap="viridis", vmin=0.25, vmax=0.95,
                                     interp=None, grid=True, overlay=False)

Note that overlay plotting is not supported for time-frequency objects.

See also

syncopy.singlepanelplot()

visualize Syncopy data objects using single-panel plots

multipanelplot(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, fig=None, **kwargs)

Plot contents of SpectralData objects using multi-panel figure(s)

Please refer to syncopy.multipanelplot() for detailed usage information.

Examples

Use 16 panels to show frequency range 30-80 Hz of first 16 channels in freqData averaged across trials 2, 4, and 6:

>>> fig = spy.multipanelplot(freqData, trials=[2, 4, 6], channels=range(16),
                             foilim=[30, 80], panels="channels")

Same settings, but each panel represents a trial:

>>> fig = spy.multipanelplot(freqData, trials=[2, 4, 6], channels=range(16),
                             foilim=[30, 80], panels="trials", avg_trials=False,
                             avg_channels=True)

Plot time-frequency contents of channels ‘ecog_mua1’ and ‘ecog_mua2’ of tfData

>>> fig = spy.multipanelplot(tfData, channels=['ecog_mua1', 'ecog_mua2'])

Note that multi-panel overlay plotting is not supported for SpectralData objects.

See also

syncopy.multipanelplot()

visualize Syncopy data objects using multi-panel plots

property cfg

Dictionary of previous operations on data

property channel

list of recording channel names

Type

numpy.ndarray

clear()

Clear loaded data from memory

Calls flush method of HDF5 dataset or memory map. Memory maps are deleted and re-instantiated.

property container
copy(deep=False)

Create a copy of the data object in memory.

Parameters

deep (bool) – If True, a copy of the underlying data file is created in the temporary Syncopy folder.

Returns

in-memory copy of data object

Return type

Syncopy data object

See also

syncopy.save()

property data

array-like object representing data without trials

Trials are concatenated along the time axis.

definetrial(trialdefinition=None, pre=None, post=None, start=None, trigger=None, stop=None, clip_edges=False)

(Re-)define trials of a Syncopy data object

Data can be structured into trials based on timestamps of a start, trigger and end events:

            start    trigger    stop
|---- pre ----|--------|---------|--- post----|
Parameters
  • obj (Syncopy data object (BaseData-like)) –

  • trialdefinition (EventData object or Mx3 array) – [start, stop, trigger_offset] sample indices for M trials

  • pre (float) – offset time (s) before start event

  • post (float) – offset time (s) after end event

  • start (int) – event code (id) to be used for start of trial

  • stop (int) – event code (id) to be used for end of trial

  • trigger – event code (id) to be used center (t=0) of trial

  • clip_edges (bool) – trim trials to actual data-boundaries.

Returns

Return type

Syncopy data object (BaseData-like))

Notes

definetrial() supports the following argument combinations:

>>> # define M trials based on [start, end, offset] indices
>>> definetrial(obj, trialdefinition=[M x 3] array)
>>> # define trials based on event codes stored in <:class:`EventData` object>
>>> definetrial(obj, trialdefinition=<EventData object>,
                pre=0, post=0, start=startCode, stop=stopCode,
                trigger=triggerCode)
>>> # apply same trial definition as defined in <:class:`EventData` object>
>>> definetrial(<AnalogData object>,
                trialdefinition=<EventData object w/sampleinfo/t0/trialinfo>)
>>> # define whole recording as single trial
>>> definetrial(obj, trialdefinition=None)
property dimord

ordered list of data dimension labels

Type

list(str)

property filename
property log

log of previous operations on data

Type

str

property mode

write mode for data, ‘r’ for read-only, ‘w’ for writable

FIXME: append/replace with HDF5?

Type

str

property sampleinfo

nTrials x 2 numpy.ndarray of [start, end] sample indices

property samplerate

sampling rate of uniformly sampled data in Hz

Type

float

save(container=None, tag=None, filename=None, overwrite=False, memuse=100)

Save data object as new spy container to disk (syncopy.save_data())

FIXME: update docu

Parameters
  • container (str) – Path to Syncopy container folder (*.spy) to be used for saving. If omitted, a .spy extension will be added to the folder name.

  • tag (str) – Tag to be appended to container basename

  • filename (str) – Explicit path to data file. This is only necessary if the data should not be part of a container folder. An extension (*.<dataclass>) will be added if omitted. The tag argument is ignored.

  • overwrite (bool) – If True an existing HDF5 file and its accompanying JSON file is overwritten (without prompt).

  • memuse (scalar) – Approximate in-memory cache size (in MB) for writing data to disk (only relevant for VirtualData or memory map data sources)

Examples

>>> save_spy(obj, filename="session1")
>>> # --> os.getcwd()/session1.<dataclass>
>>> # --> os.getcwd()/session1.<dataclass>.info
>>> save_spy(obj, filename="/tmp/session1")
>>> # --> /tmp/session1.<dataclass>
>>> # --> /tmp/session1.<dataclass>.info
>>> save_spy(obj, container="container.spy")
>>> # --> os.getcwd()/container.spy/container.<dataclass>
>>> # --> os.getcwd()/container.spy/container.<dataclass>.info
>>> save_spy(obj, container="/tmp/container.spy")
>>> # --> /tmp/container.spy/container.<dataclass>
>>> # --> /tmp/container.spy/container.<dataclass>.info
>>> save_spy(obj, container="session1.spy", tag="someTag")
>>> # --> os.getcwd()/container.spy/session1_someTag.<dataclass>
>>> # --> os.getcwd()/container.spy/session1_someTag.<dataclass>.info
property tag
property time

trigger-relative time axes of each trial

Type

list(float)

property trialdefinition

]]

Type

nTrials x >=3 numpy.ndarray of [start, end, offset, trialinfo[

property trialinfo

nTrials x M numpy.ndarray with numeric information about each trial

Each trial can have M properties (condition, original trial no., …) coded by numbers. This property are the fourth and onward columns of BaseData._trialdefinition.

property trials

list-like array of trials

selectdata(trials=None, channels=None, toi=None, toilim=None, foi=None, foilim=None, tapers=None)[source]

Create new SpectralData object from selection

Please refer to syncopy.selectdata() for detailed usage information.

Examples

>>> spcBand = spc.selectdata(foilim=[10, 40])

See also

syncopy.selectdata()

create new objects via deep-copy selections

__init__(data=None, filename=None, trialdefinition=None, samplerate=None, channel=None, taper=None, freq=None, dimord=None)[source]

Docstring

  1. filename + data = create HDF5 file at filename with data in it

  2. data only

property freq

frequency axis in Hz

Type

numpy.ndarray

property taper

list of window functions used

Type

numpy.ndarray