syncopy.datatype.base_data.Selector#

class syncopy.datatype.base_data.Selector(data, select)[source]#

Auxiliary class for data selection

Parameters:

data (Syncopy data object) – A non-empty Syncopy data object
select (dict or StructDict or None or str) –
Dictionary or StructDict with keys specifying data selectors. Note: some keys are only valid for certain types of Syncopy objects, e.g., “freq” is not a valid selector for an AnalogData object. Supported keys are (please see selectdata() for a detailed description of each selector)
- ’trials’ : list (integers)
- ’channel’ : list (integers or strings), slice or range
- ’toi’ : list (floats)
- ’toilim’ : list (floats [tmin, tmax])
- ’foi’ : list (floats)
- ’foilim’ : list (floats [fmin, fmax])
- ’taper’ : list (integers or strings), slice or range
- ’unit’ : list (integers or strings), slice or range
- ’eventid’ : list (integers), slice or range
Any property of data that is not specifically accessed via one of the above keys is taken as is, e.g., select = {'trials': [1, 2]} selects the entire contents of trials no. 2 and 3, while select = {'channel': range(0, 50)} selects the first 50 channels of data across all defined trials. Consequently, if select is None or if select = "all" the entire contents of data is selected.

Returns:

selection – An instance of this class whose main properties are either lists or slices to be used as (fancy) indexing tuples. Note that the properties time, unit and eventid are by-trial selections, i.e., list of lists and/or slices encoding per-trial sample-indices, e.g., selection.time[0] is intended to be used with data.trials[selection.trial_ids[0]]. Addditional class attributes of note:

_useFancy : bool

If True, selection requires “fancy” (or “advanced”) array indexing
_dataClass : str

Class name of data
_samplerate : float

Samplerate of data (only relevant for objects supporting time-selections)
_timeShuffle : bool

If True, time-selection contains unordered/repeated time-points.
_allProps : list

List of all selection properties in class
_byTrialProps : list

List off by-trial selection properties (see above)
_dimProps : list

List off trial-independent selection properties (computed as self._allProps minus self._byTrialProps)

Return type:

Syncopy Selector object

Notes

Whenever possible, this class performs extensive input parsing to ensure consistency of provided selectors. Some exceptions to this rule include toi and toilim: depending on the size of data and the number of defined trials, data.time might generate a list of arrays of substantial size. To not overflow memory and slow down computations, neither toi nor toilim is checked for consistency with respect to data.time, i.e., the code does not verify that min/max of toi/toilim are within the bounds of data.time for each selected trial.

For objects that have a time property, a suitable new trialdefinition array (accessible via the identically named Selector class property) is automatically constructed based on the provided selection.

By default, each selection property tries to convert a user-provided selection to a contiguous slice-indexer so that simple NumPy array indexing can be used for best performance. However, after setting all selection indices appropriate for the input object, a consistency check is performed by _make_consistent() to ensure that the calculated indices can actually be jointly used on a multi-dimensional NumPy array without violating indexing arithmetic. Thus, if a given Selector instance ends up containing more than two conjoint index-lists, all other selection properties are converted (if necessary) to lists as well for use with numpy.ix_(). These selections require special array manipulation techniques (colloquially referred to as “fancy” or “advanced” indexing) and the Selector marks such indexers by setting the hidden self._useFancy attribute to True. Note that numpy.ix_() always creates copies of the indexed reference array, hence, the attempt to use slice-based indexing whenever possible.

Examples

See syncopy.selectdata() for usage examples.

See also

syncopy.selectdata: extract data selections from Syncopy objects

__init__(data, select)[source]#

Methods

`__init__`(data, select)
`create_get_trial`(data)	Closure to allow emulation of BaseData._get_trial

`_make_consistent`(data)	Consolidate multi-selections
`_selection_setter`(data, select, selectkey)	Converts user-provided selection key-words to indexing lists/slices

Attributes

`channel`	List or slice encoding channel-selection
`channel_i`	List or slice encoding principal channel-pair selection
`channel_j`	List or slice encoding principal channel-pair selection
`eventid`	len(self.trials) list of lists/slices encoding by-trial event-id-selection
`freq`	List or slice encoding frequency-selection
`sampleinfo`	nTrials x 2 `numpy.ndarray` of [start, end] sample indices
`taper`	List or slice encoding taper-selection
`time`	len(self.trial_ids) list of lists/slices of by-trial time-selections
`trial_ids`	Index list of selected trials
`trialdefinition`	len(self.trial_ids)-by-(3+) `numpy.ndarray` encoding trial-information of selection
`trialintervals`	nTrials x 2 `numpy.ndarray` of [start, end] times in seconds
`trials`	Returns an iterable indexing single trial arrays respecting the selection Indices are ABSOLUTE with respect to existing trial selections:
`unit`	len(self.trial_ids) list of lists/slices of by-trial unit-selections

__init__(data, select)[source]#

property trial_ids#: Index list of selected trials

property trials#

Returns an iterable indexing single trial arrays respecting the selection Indices are ABSOLUTE with respect to existing trial selections:

>>> selection.trials[11]

indexes the 11th trial of the original dataset, if and only if trial number 11 is part of the selection.

Selections must be “simple”: ordered and without repetitions

create_get_trial(data)[source]#: Closure to allow emulation of BaseData._get_trial

property channel#: List or slice encoding channel-selection

property channel_i#: List or slice encoding principal channel-pair selection

property channel_j#: List or slice encoding principal channel-pair selection

property time#: len(self.trial_ids) list of lists/slices of by-trial time-selections

property trialdefinition#: len(self.trial_ids)-by-(3+) numpy.ndarray encoding trial-information of selection

property sampleinfo#: nTrials x 2 numpy.ndarray of [start, end] sample indices

property trialintervals#: nTrials x 2 numpy.ndarray of [start, end] times in seconds

property freq#: List or slice encoding frequency-selection

property taper#: List or slice encoding taper-selection

property unit#: len(self.trial_ids) list of lists/slices of by-trial unit-selections

property eventid#: len(self.trials) list of lists/slices encoding by-trial event-id-selection

_selection_setter(data, select, selectkey)[source]#

Converts user-provided selection key-words to indexing lists/slices

Parameters:

data (Syncopy data object) – Non-empty Syncopy data object
select (dict or StructDict) – Python dictionary or Syncopy StructDict formatted for data selection. See Selector for a list of valid key-value pairs.
selectkey (str) – Name of key in select holding selection pertinent to identically named property in data

Returns:

Nothing

Return type:

None

Notes

This class method processes and (if necessary converts) user-provided selections. Valid selectors are slices, ranges, lists or arrays. If possible, all selections are converted to contiguous slices, otherwise regular Python lists are used. Selections can be unsorted and may include repetitions but must match exactly, be finite and not NaN. Converted selections are stored in the respective (hidden) class attributes (e.g., self._channel, self._unit etc.).

syncopy.datatype.base_data.Selector

Contents

syncopy.datatype.base_data.Selector#