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., “freqs” 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)
- ’channels’ : list (integers or strings), slice or range
- ’toi’ : list (floats)
- ’toilim’ : list (floats [tmin, tmax])
- ’foi’ : list (floats)
- ’foilim’ : list (floats [fmin, fmax])
- ’tapers’ : list (integers or strings), slice or range
- ’units’ : list (integers or strings), slice or range
- ’eventids’ : 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 = {'channels': 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.trials[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 be 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. For unsorted time-selections with or without repetitions, the timepoints property encodes the timing of the selected (discrete) points. To permit this functionality, the input object’s samplerate is stored in the identically named hidden attribute _samplerate. In addition, the hidden _timeShuffle attribute is a binary flag encoding whether selected time-points are unordered and/or contain repetitions (Selector._timeShuffle = True).

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]¶: Initialize self. See help(type(self)) for accurate signature.

Methods

__init__(data, select)

Initialize self.

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

Attributes

`channel`	List or slice encoding channel-selection
`eventid`	len(self.trials) list of lists/slices encoding by-trial event-id-selection
`freq`	List or slice encoding frequency-selection
`taper`	List or slice encoding taper-selection
`time`	len(self.trials) list of lists/slices of by-trial time-selections
`timepoints`	len(self.trials) list of lists encoding actual (not sample indices!) timing information of unordered toi selections
`trialdefinition`	len(self.trials)-by-(3+) `numpy.ndarray` encoding trial-information of selection
`trials`	Index list of selected trials
`unit`	len(self.trials) list of lists/slices of by-trial unit-selections

__init__(data, select)[source]¶: Initialize self. See help(type(self)) for accurate signature.

property trials¶: Index list of selected trials

property channel¶: List or slice encoding channel-selection

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

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

property timepoints¶: len(self.trials) list of lists encoding actual (not sample indices!) timing information of unordered toi selections

property freq¶: List or slice encoding frequency-selection

property taper¶: List or slice encoding taper-selection

property unit¶: len(self.trials) 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, dataprop, 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.
dataprop (str) – Name of property in data to select from
selectkey (str) – Name of key in select holding selection pertinent to dataprop

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.).