syncopy.datatype.base_data.BaseData

class syncopy.datatype.base_data.BaseData(filename=None, dimord=None, mode='r+', **kwargs)[source]

Abstract base class for all data classes

Data classes in Syncopy manage storing array data and metadata in HDF5 and JSON files, respectively. This base class contains the fundamental functionality shared across all data classes, that is,

  • properties for arrays that have a corresponding HDF5 datasets (‘dataset properties’) and the associated I/O

  • properties for data history (BaseData.log and BaseData.cfg)

  • methods and properties for defining trials on the data

Further properties and methods are defined in subclasses, e.g. syncopy.AnalogData.

__init__(filename=None, dimord=None, mode='r+', **kwargs)[source]

Docstring

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

  2. data only

Methods

__init__([filename, dimord, mode])

Docstring

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

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

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

selectdata([trials, deepcopy])

Docstring mostly pointing to selectdata

_abc_impl

_checksum_algorithm

_classname_to_extension()

_defaultDimord

classmethod(function) -> method

_gen_filename()

_get_trial(trialno)

_hdfFileAttributeProperties

_hdfFileDatasetProperties

properties that are mapped onto HDF5 datasets

_infoFileProperties

properties that are written into the JSON file and HDF5 attributes upon save

_is_empty()

_mode

_selection

Data selection specified by Selector

_set_cfg(cfg, dct)

_set_dataset_property(dataIn, propertyName)

Set property that is streamed from HDF dataset (‘dataset property’)

_set_dataset_property_with_dataset(inData, …)

Set a dataset property with an already loaded HDF5 dataset

_set_dataset_property_with_memmap(inData, …)

Set a dataset property with a memory map

_set_dataset_property_with_ndarray(inData, …)

Set a dataset property with a NumPy array

_set_dataset_property_with_none(dataIn, …)

Set a dataset property to None

_set_dataset_property_with_str(filename, …)

Set a dataset property with a filename str

_spwCaller

_t0

Attributes

cfg

Dictionary of previous operations on data

container

dimord

ordered list of data dimension labels

filename

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

tag

trialdefinition

]]

trialinfo

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

trials

list-like array of trials

_infoFileProperties = ('dimord', '_version', '_log', 'cfg')

properties that are written into the JSON file and HDF5 attributes upon save

_hdfFileAttributeProperties = ('dimord', '_version', '_log')
_hdfFileDatasetProperties = ()

properties that are mapped onto HDF5 datasets

_checksum_algorithm = 'openssl_sha1'
_spwCaller = 'BaseData.{}'
abstract property _defaultDimord

classmethod(function) -> method

Convert a function to be a class method.

A class method receives the class as implicit first argument, just like an instance method receives the instance. To declare a class method, use this idiom:

class C:

@classmethod def f(cls, arg1, arg2, …):

It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()). The instance is ignored except for its class. If a class method is called for a derived class, the derived class object is passed as the implied first argument.

Class methods are different than C++ or Java static methods. If you want those, see the staticmethod builtin.

property cfg

Dictionary of previous operations on data

property container
_set_dataset_property(dataIn, propertyName, ndim=None)[source]

Set property that is streamed from HDF dataset (‘dataset property’)

This method automatically selects the appropriate set method according to the type of the input data (dataIn).

Parameters
  • dataIn (str, np.ndarray, np.core.memmap or h5py.Dataset) – Filename, array or HDF5 dataset to be stored in property

  • propertyName (str) – Name of the property. The actual data must reside in the attribute “_” + propertyName

  • ndim (int) – Number of expected array dimensions.

_set_dataset_property_with_none(dataIn, propertyName, ndim)[source]

Set a dataset property to None

_set_dataset_property_with_str(filename, propertyName, ndim)[source]

Set a dataset property with a filename str

Parameters
  • filename (str) – A filename pointing to a HDF5 file containing the dataset propertyName or a NPY file. NPY files are loaded as memmaps.

  • propertyName (str) – Name of the property to be filled with the dataset/memmap

  • ndim (int) – Number of expected array dimensions.

_set_dataset_property_with_ndarray(inData, propertyName, ndim)[source]

Set a dataset property with a NumPy array

If no data exists, a backing HDF5 dataset will be created.

Parameters
  • inData (numpy.ndarray) – NumPy array to be stored in property of name propertyName

  • propertyName (str) – Name of the property to be filled with inData

  • ndim (int) – Number of expected array dimensions.

_set_dataset_property_with_memmap(inData, propertyName, ndim)[source]

Set a dataset property with a memory map

The memory map is directly stored in the attribute. No backing HDF5 dataset is created. This feature may be removed in future versions.

Parameters
  • inData (numpy.memmap) – NumPy memory-map to be stored in property of name propertyName

  • propertyName (str) – Name of the property to be filled with the memory map.

  • ndim (int) – Number of expected array dimensions.

_set_dataset_property_with_dataset(inData, propertyName, ndim)[source]

Set a dataset property with an already loaded HDF5 dataset

Parameters
  • inData (h5py.Dataset) – HDF5 dataset to be stored in property of name propertyName

  • propertyName (str) – Name of the property to be filled with the dataset

  • ndim (int) – Number of expected array dimensions.

_is_empty()[source]
property tag
property _selection

Data selection specified by Selector

property trialdefinition

]]

Type

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

property sampleinfo

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

property _t0
property trials

list-like array of trials

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.

abstract selectdata(trials=None, deepcopy=False, **kwargs)[source]

Docstring mostly pointing to selectdata

abstract _get_trial(trialno)[source]
clear()[source]

Clear loaded data from memory

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

copy(deep=False)[source]

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)
save(container=None, tag=None, filename=None, overwrite=False, memuse=100)[source]

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
_gen_filename()[source]
_classname_to_extension()[source]
_set_cfg(cfg, dct)[source]
__init__(filename=None, dimord=None, mode='r+', **kwargs)[source]

Docstring

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

  2. data only

_mode = None
property mode

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

FIXME: append/replace with HDF5?

Type

str

property dimord

ordered list of data dimension labels

Type

list(str)

property filename
property log

log of previous operations on data

Type

str

_abc_impl = <_abc_data object>