AnalogData

class syncopy.AnalogData(data=None, filename=None, trialdefinition=None, samplerate=None, channel=None, dimord=None)

Bases: syncopy.datatype.continuous_data.ContinuousData

Multi-channel, uniformly-sampled, analog (real float) data

This class can be used for representing any analog signal data with a time and a channel axis such as local field potentials, firing rates, eye position etc.

The data is always stored as a two-dimensional array on disk. On disk, Trials are concatenated along the time axis.

Data is only read from disk on demand, similar to memory maps and HDF5 files.

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
hdr	dict with information about raw data
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
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, toilim, …])	Plot contents of AnalogData 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 AnalogData object from selection
singlepanelplot([trials, channels, toilim, …])	Plot contents of AnalogData 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

hdr

dict with information about raw data

This property is empty for data created by Syncopy.

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

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', toilim=None, avg_channels=False, avg_trials=True, title=None, grid=None, fig=None, **kwargs)

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

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

Examples

Use generate_artificial_data() to create two synthetic AnalogData objects.

>>> from syncopy.tests.misc import generate_artificial_data
>>> adata = generate_artificial_data(nTrials=10, nChannels=32)
>>> bdata = generate_artificial_data(nTrials=5, nChannels=16)

Show overview of first 5 channels, averaged across trials 2, 4, and 6:

>>> fig = spy.multipanelplot(adata, channels=range(5), trials=[2, 4, 6])

Overlay last 5 channels, averaged across trials 1, 3, 5:

>>> fig = spy.multipanelplot(adata, channels=range(27, 32), trials=[1, 3, 5], fig=fig)

Do not average trials:

>>> fig = spy.multipanelplot(adata, channels=range(27, 32), trials=[1, 3, 5], avg_trials=False)

Plot adata and bdata simultaneously in two separate figures:

>>> fig1, fig2 = spy.multipanelplot(adata, bdata, channels=range(5), overlay=False)

Overlay adata and bdata; use channel and trial selections that are valid for both datasets:

>>> fig3 = spy.multipanelplot(adata, bdata, channels=range(5), trials=[1, 2, 3], avg_trials=False)

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)

Create new AnalogData object from selection

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

Examples

>>> ang2chan = ang.selectdata(channels=["channel01", "channel02"])

See also

syncopy.selectdata()

create new objects via deep-copy selections

singlepanelplot(trials='all', channels='all', toilim=None, avg_channels=True, title=None, grid=None, fig=None, **kwargs)

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

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

Examples

Use generate_artificial_data() to create two synthetic AnalogData objects.

>>> from syncopy.tests.misc import generate_artificial_data
>>> adata = generate_artificial_data(nTrials=10, nChannels=32)
>>> bdata = generate_artificial_data(nTrials=5, nChannels=16)

Plot an average of the first 16 channels, averaged across trials 2, 4, and 6:

>>> fig = spy.singlepanelplot(adata, channels=range(16), trials=[2, 4, 6])

Overlay average of latter half of channels, averaged across trials 1, 3, 5:

>>> fig = spy.singlepanelplot(adata, channels=range(16,32), trials=[1, 3, 5], fig=fig)

Do not average channels:

>>> fig = spy.singlepanelplot(adata, channels=range(16,32), trials=[1, 3, 5], avg_channels=False)

Plot adata and bdata simultaneously in two separate figures:

>>> fig1, fig2 = spy.singlepanelplot(adata, bdata, overlay=False)

Overlay adata and bdata; use channel and trial selections that are valid for both datasets:

>>> fig3 = spy.singlepanelplot(adata, bdata, channels=range(16), trials=[1, 2, 3])

See also

syncopy.singlepanelplot()

visualize Syncopy data objects using single-panel plots

singlepanelplot(trials='all', channels='all', toilim=None, avg_channels=True, title=None, grid=None, fig=None, **kwargs)

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

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

Examples

Use generate_artificial_data() to create two synthetic AnalogData objects.

>>> from syncopy.tests.misc import generate_artificial_data
>>> adata = generate_artificial_data(nTrials=10, nChannels=32)
>>> bdata = generate_artificial_data(nTrials=5, nChannels=16)

Plot an average of the first 16 channels, averaged across trials 2, 4, and 6:

>>> fig = spy.singlepanelplot(adata, channels=range(16), trials=[2, 4, 6])

Overlay average of latter half of channels, averaged across trials 1, 3, 5:

>>> fig = spy.singlepanelplot(adata, channels=range(16,32), trials=[1, 3, 5], fig=fig)

Do not average channels:

>>> fig = spy.singlepanelplot(adata, channels=range(16,32), trials=[1, 3, 5], avg_channels=False)

Plot adata and bdata simultaneously in two separate figures:

>>> fig1, fig2 = spy.singlepanelplot(adata, bdata, overlay=False)

Overlay adata and bdata; use channel and trial selections that are valid for both datasets:

>>> fig3 = spy.singlepanelplot(adata, bdata, channels=range(16), trials=[1, 2, 3])

See also

syncopy.singlepanelplot()

visualize Syncopy data objects using single-panel plots

multipanelplot(trials='all', channels='all', toilim=None, avg_channels=False, avg_trials=True, title=None, grid=None, fig=None, **kwargs)

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

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

Examples

Use generate_artificial_data() to create two synthetic AnalogData objects.

>>> from syncopy.tests.misc import generate_artificial_data
>>> adata = generate_artificial_data(nTrials=10, nChannels=32)
>>> bdata = generate_artificial_data(nTrials=5, nChannels=16)

Show overview of first 5 channels, averaged across trials 2, 4, and 6:

>>> fig = spy.multipanelplot(adata, channels=range(5), trials=[2, 4, 6])

Overlay last 5 channels, averaged across trials 1, 3, 5:

>>> fig = spy.multipanelplot(adata, channels=range(27, 32), trials=[1, 3, 5], fig=fig)

Do not average trials:

>>> fig = spy.multipanelplot(adata, channels=range(27, 32), trials=[1, 3, 5], avg_trials=False)

Plot adata and bdata simultaneously in two separate figures:

>>> fig1, fig2 = spy.multipanelplot(adata, bdata, channels=range(5), overlay=False)

Overlay adata and bdata; use channel and trial selections that are valid for both datasets:

>>> fig3 = spy.multipanelplot(adata, bdata, channels=range(5), trials=[1, 2, 3], avg_trials=False)

See also

syncopy.multipanelplot()

visualize Syncopy data objects using multi-panel plots

property hdr

dict with information about raw data

This property is empty for data created by Syncopy.

selectdata(trials=None, channels=None, toi=None, toilim=None)

Create new AnalogData object from selection

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

Examples

>>> ang2chan = ang.selectdata(channels=["channel01", "channel02"])

See also

syncopy.selectdata()

create new objects via deep-copy selections

__init__(data=None, filename=None, trialdefinition=None, samplerate=None, channel=None, dimord=None)

Initialize an AnalogData object.

Parameters

• data (2D :class:numpy.ndarray or HDF5 dataset) – multi-channel time series data with uniform sampling

• filename (str) – path to target filename that should be used for writing

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

• samplerate (float) – sampling rate in Hz

• channel (str or list/array(str)) –

• dimord (list(str)) – ordered list of dimension labels

1. filename + data : create hdf dataset incl. sampleinfo @filename

2. just data : try to attach data (error checking done by AnalogData.data.setter())

See also

syncopy.definetrial()

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