wonambi.trans.select module

Module to select periods of interest, based on number of trials or any of the axes.

There is some overlap between Select and the Data.__call__(). The main difference is that Select takes an instance of Data as input and returns another instance of Data as output, whil Data.__call__() returns the actual content of the data.

Select should be as flexible as possible. There are quite a few cases, which will be added as we need them.

class wonambi.trans.select.Segments(dataset)[source]

Bases: object

Class containing a set of data segments for analysis, with metadata. Only contains metadata until .read_data is called.

dataset

metadata for the associated record

Type:

instance of wonambi.dataset

segments

chronological list of segment metadata. Each segment dict contains info about start and end times, stage, cycle, channel and event name, if applicable. Once read_data is called, the signal data are added to each segment dictionary under ‘data’.

Type:

list of dict

read_data(chan=[], ref_chan=[], grp_name=None, concat_chan=False, average_channels=False, max_s_freq=30000, parent=None)[source]

Read data for analysis. Adds data as ‘data’ in each dict.

Parameters:

  • chan (list of str) – active channel names as they appear in record, without ref or group If given an empty list, the channel specified in seg[‘chan’] will be read for each segment

  • ref_chan (list of str) – reference channel names as they appear in record, without group

  • grp_name (str) – name of the channel group, required in GUI

  • concat_chan (bool) – if True, data from all channels will be concatenated

  • average_channels (bool) – if True, all channels will be averaged into a single virtual channel with label ‘avg_chan’

  • max_s_freq (: int) – maximum sampling frequency

  • parent (QWidget) – for GUI only. Identifies parent widget for display of progress dialog.

wonambi.trans.select.fetch(dataset, annot, cat=(0, 0, 0, 0), evt_type=None, stage=None, cycle=None, chan_full=None, epoch=None, epoch_dur=30, epoch_overlap=0, epoch_step=None, reject_epoch=False, reject_artf=False, min_dur=0, buffer=0)[source]

Create instance of Segments for analysis, complete with info about stage, cycle, channel, event type. Segments contains only metadata until .read_data is called.

Parameters:

  • dataset (instance of Dataset) – info about record

  • annot (instance of Annotations) – scoring info

  • cat (tuple of int) – Determines where the signal is concatenated. If cat[0] is 1, cycles will be concatenated. If cat[1] is 1, different stages will be concatenated. If cat[2] is 1, discontinuous signal within a same condition (stage, cycle, event type) will be concatenated. If cat[3] is 1, events of different types will be concatenated. 0 in any position indicates no concatenation.

  • evt_type (list of str, optional) – Enter a list of event types to get events; otherwise, epochs will be returned.

  • stage (list of str, optional) – Stage(s) of interest. If None, stage is ignored.

  • cycle (list of tuple of two float, optional) – Cycle(s) of interest, as start and end times in seconds from record start. If None, cycles are ignored.

  • chan_full (list of str or None) – Channel(s) of interest, only used for events (epochs have no channel). Channel format is ‘chan_name (group_name)’. If used for epochs, separate segments will be returned for each channel; this is necessary for channel-specific artefact removal (see reject_artf below). If None, channel is ignored.

  • epoch (str, optional) – If ‘locked’, returns epochs locked to staging. If ‘unlocked’, divides signal (with specified concatenation) into epochs of duration epoch_dur starting at first sample of every segment and discarding any remainder. If None, longest run of signal is returned.

  • epoch_dur (float) – only for epoch=’unlocked’. Duration of epochs returned, in seconds.

  • epoch_overlap (float) – only for epoch=’unlocked’. Ratio of overlap between two consecutive segments. Value between 0 and 1. Overriden by step.

  • epoch_step (float) – only for epoch=’unlocked’. Time between consecutive epoch starts, in seconds. Overrides epoch_overlap/

  • reject_epoch (bool) – If True, epochs marked as ‘Poor’ quality or staged as ‘Artefact’ will be rejected (and the signal segmented in consequence). Has no effect on event selection.

  • reject_artf (bool or str or list of str) – If True, excludes events marked as ‘Artefact’. If chan_full is specified, only artefacts marked on a given channel are removed from that channel. Signal is segmented in consequence. If None, Artefact events are ignored. If str or list of str, will reject the specified event types only.

  • min_dur (float) – Minimum duration of segments returned, in seconds.

  • buffer (float) – adds this many seconds of signal before and after each segment

Returns:

instance of Segments – metadata for all analysis segments

wonambi.trans.select.get_times(annot, evt_type=None, stage=None, cycle=None, chan=None, exclude=False, buffer=0)[source]

Get start and end times for selected segments of data, bundled together with info.

Parameters:

  • annot (instance of Annotations) – The annotation file containing events and epochs

  • evt_type (list of str, optional) – Enter a list of event types to get events; otherwise, epochs will be returned.

  • stage (list of str, optional) – Stage(s) of interest. If None, stage is ignored.

  • cycle (list of tuple of two float, optional) – Cycle(s) of interest, as start and end times in seconds from record start. If None, cycles are ignored.

  • chan (list of str or tuple of None) – Channel(s) of interest. Channel format is ‘chan_name (group_name)’. If None, channel is ignored.

  • exclude (bool) – Exclude epochs by quality. If True, epochs marked as ‘Poor’ quality or staged as ‘Artefact’ will be rejected (and the signal segmented in consequence). Has no effect on event selection.

  • buffer (float) – adds this many seconds of signal before and after each segment

Returns:

list of dict – Each dict has times (the start and end times of each segment, as list of tuple of float), stage, cycle, chan, name (event type, if applicable)

Notes

This function returns epoch or event start and end times, bundled together according to the specified parameters. Presently, setting exclude to True does not exclude events found in Poor signal epochs. The rationale is that events would never be marked in Poor signal epochs. If they were automatically detected, these epochs would have been left out during detection. If they were manually marked, then it must have been Good signal. At the moment, in the GUI, the exclude epoch option is disabled when analyzing events, but we could fix the code if we find a use case for rejecting events based on the quality of the epoch signal.

wonambi.trans.select.resample(data, s_freq, axis='time')[source]

Downsample the data after applying a filter.

Parameters:

  • data (instance of Data) – data to downsample

  • s_freq (int or float) – desired sampling frequency

  • axis (str) – axis you want to apply downsample on (most likely ‘time’)

Returns:

instance of Data – downsampled data

wonambi.trans.select.select(data, trial=None, invert=False, **axes_to_select)[source]

Define the selection of trials, using ranges or actual values.

Parameters:

  • data (instance of Data) – data to select from.

  • trial (list of int or ndarray (dtype='i'), optional) – index of trials of interest

  • **axes_to_select – Values need to be tuple or list. If the values in one axis are string, then you need to specify all the strings that you want. If the values are numeric, then you should specify the range. To select only up to one point, you can use (None, value_of_interest). To select multiple values, you can pass a numpy array with dtype bool

  • optional – Values need to be tuple or list. If the values in one axis are string, then you need to specify all the strings that you want. If the values are numeric, then you should specify the range. To select only up to one point, you can use (None, value_of_interest). To select multiple values, you can pass a numpy array with dtype bool

  • invert (bool) – take the opposite selection

Returns:

instance, same class as input – data where selection has been applied.

wonambi.trans.select.smart_chan(dataset, simple_chan_name, test_chan=None)[source]

From a list of simple channel names, attempts to find the corresponding channel names in the dataset and returns a list (with same order). :param dataset: info about record :type dataset: instance of Dataset :param simple_chan_name: simple names for channels, e.g. [‘F3’, ‘Fp2’, ‘ECG’] :type simple_chan_name: list of str

Returns:

list – corresponding channel labels as they appear in dataset