AnalogData¶
-
class
syncopy.
AnalogData
(data=None, filename=None, trialdefinition=None, samplerate=None, channel=None, dimord=None)[source]¶ 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
Dictionary of previous operations on data
list of recording channel names
array-like object representing data without trials
ordered list of data dimension labels
dict with information about raw data
log of previous operations on data
write mode for data, ‘r’ for read-only, ‘w’ for writable
nTrials x 2
numpy.ndarray
of [start, end] sample indicessampling rate of uniformly sampled data in Hz
trigger-relative time axes of each trial
]]
nTrials x M
numpy.ndarray
with numeric information about each triallist-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
-
container
¶
-
data
¶ array-like object representing data without trials
Trials are concatenated along the time axis.
-
filename
¶
-
hdr
¶ dict with information about raw data
This property is empty for data created by Syncopy.
-
mode
¶ write mode for data, ‘r’ for read-only, ‘w’ for writable
FIXME: append/replace with HDF5?
- Type
-
sampleinfo
¶ nTrials x 2
numpy.ndarray
of [start, end] sample indices
-
tag
¶
-
trialdefinition
¶ ]]
- Type
nTrials x >=3
numpy.ndarray
of [start, end, offset, trialinfo[
-
trialinfo
¶ nTrials x M
numpy.ndarray
with numeric information about each trialEach 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
-
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 trialspre (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 syntheticAnalogData
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)[source]¶ 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 syntheticAnalogData
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 syntheticAnalogData
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 syntheticAnalogData
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)[source]¶ 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)[source]¶ 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 trialssamplerate (float) – sampling rate in Hz
filename + data : create hdf dataset incl. sampleinfo @filename
just data : try to attach data (error checking done by
AnalogData.data.setter()
)
See also
-
property
cfg
¶ Dictionary of previous operations on data
-
property
channel
¶ list of recording channel names
- Type
-
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
-
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 trialspre (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
filename
¶
-
property
mode
¶ write mode for data, ‘r’ for read-only, ‘w’ for writable
FIXME: append/replace with HDF5?
- Type
-
property
sampleinfo
¶ nTrials x 2
numpy.ndarray
of [start, end] sample indices
-
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
trialdefinition
¶ ]]
- Type
nTrials x >=3
numpy.ndarray
of [start, end, offset, trialinfo[
-
property
trialinfo
¶ nTrials x M
numpy.ndarray
with numeric information about each trialEach 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
-