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

See also

syncopy.selectdata()

extract data selections from Syncopy objects

_make_consistent(data)[source]

Consolidate multi-selections

Parameters

data (Syncopy data object) – Non-empty Syncopy data object

Returns

Nothing

Return type

None

Notes

This class method is called after all user-provided selections have been (successfully) processed and (if necessary) converted to lists/slices. For instances of ContinuousData child classes (i.e., AnalogData and SpectralData objects) the integrity of conjoint multi-dimensional selections is ensured. For instances of DiscreteData child classes (i.e., SpikeData and EventData objects), any selection (unit, eventid, time and channel) operates on the rows of the object’s underlying data array. Thus, multi-selections need to be synchronized (e.g., a unit selection pointing to rows [0, 1, 2] and a time selection filtering rows [1, 2, 3] are combined to [1, 2]).

See also

numpy.ix_()

Mesh-construction for array indexing