msqms.libs.osl.osl_wrappers module

msqms.libs.osl.osl_wrappers module#

Wrappers for MNE functions to perform preprocessing.

Summary#

Functions:#

detect_artefacts

Detect bad observations or segments in a dataset

detect_badchannels

Set bad channels in an MNE Raw object as defined by the Generalized ESD test in osl.preprocessing.osl_wrappers.gesd.

detect_badsegments

Set bad segments in an MNE Raw object as defined by the Generalized ESD test in osl.preprocessing.osl_wrappers.gesd.

detect_maxfilt_zeros

This function tries to load the maxfilter log files in order

drop_bad_epochs

Drop bad epochs in an MNE Epochs object as defined by the Generalized ESD test in osl.preprocessing.osl_wrappers.gesd.

gesd

Detect outliers using Generalized ESD test

Reference#

msqms.libs.osl.osl_wrappers.gesd(x, alpha=0.05, p_out=0.1, outlier_side=0)[source]#

Detect outliers using Generalized ESD test

xvector

Data set containing outliers

alphascalar

Significance level to detect at (default = 0.05)

p_outint

Maximum number of outliers to detect (default = 10% of data set)

outlier_side{-1,0,1}
Specify sidedness of the test

  • outlier_side = -1 -> outliers are all smaller

  • outlier_side = 0 -> outliers could be small/negative or large/positive (default)

  • outlier_side = 1 -> outliers are all larger

Returns:

  • idx (boolean vector) – Boolean array with TRUE wherever a sample is an outlier

  • x2 (vector) – Input array with outliers removed

References

B. Rosner (1983). Percentage Points for a Generalized ESD Many-Outlier Procedure. Technometrics 25(2), pp. 165-172. http://www.jstor.org/stable/1268549?seq=1

msqms.libs.osl.osl_wrappers.detect_artefacts(X, axis=None, reject_mode='dim', metric_func=<function std>, segment_len=100, gesd_args=None, ret_mode='bad_inds')[source]#

Detect bad observations or segments in a dataset

Parameters:

  • X (ndarray) – Array to find artefacts in.

  • axis (int) – Index of the axis to detect artefacts in

  • reject_mode ({'dim' | 'segments'}) – Flag indicating whether to detect outliers across a dimension (dim; default) or whether to split a dim into segments and detect outliers in the them (segments)

  • metric_func (function) – Function defining metric to detect outliers on. Defaults to np.std but can be any function taking an array and returning a single number.

  • segement_len (int > 0) – Integer window length of dummy epochs for bad_segment detection

  • gesd_args (dict) – Dictionary of arguments to pass to gesd

  • ret_mode ({'good_inds','bad_inds','zero_bads','nan_bads'}) – Flag indicating whether to return the indices for good observations, indices for bad observations (default), the input data with outliers removed (zero_bads) or the input data with outliers replaced with nans (nan_bads)

Returns:

If ret_mode is 'bad_inds' or 'good_inds', this returns a boolean vector of length X.shape[axis] indicating good or bad samples. If ret_mode is 'zero_bads' or 'nan_bads' this returns an array copy of the input data X with bad samples set to zero or np.nan respectively.

Return type:

ndarray

msqms.libs.osl.osl_wrappers.detect_maxfilt_zeros(raw)[source]#
This function tries to load the maxfilter log files in order

to annotate zeroed out data in the mne.io.Raw object. It assumes that the log file is in the same directory as the raw file and has the same name, but with the extension .log.

Parameters:

raw (mne.io.Raw) – MNE raw object.

Returns:

bad_inds – Boolean array indicating which time points are zeroed out.

Return type:

np.array of bool (n_times,) or None

msqms.libs.osl.osl_wrappers.detect_badsegments(raw, picks, segment_len=1000, significance_level=0.05, metric='std', ref_meg='auto', mode=None, detect_zeros=True, annotate=False)[source]#

Set bad segments in an MNE Raw object as defined by the Generalized ESD test in osl.preprocessing.osl_wrappers.gesd.

Parameters:

  • raw (mne.io.Raw) – MNE raw object.

  • picks (str) – Channel types to pick. See Notes for recommendations.

  • segment_len (int) – Window length to divide the data into (non-overlapping).

  • significance_level (float) – Significance level for detecting outliers. Must be between 0-1.

  • metric (str) – Metric to use. Could be 'std', 'var' or 'kurtosis'.

  • ref_meg (str) – ref_meg argument to pass with mne.pick_types.

  • mode (str) – Should be None 'diff' or 'maxfilter'. When mode='diff' we calculate a difference time series before detecting bad segments. When mode='maxfilter' we only mark the segments with zeros from MaxFiltering as bad.

  • detect_zeros (bool) – Should we detect segments of zeros based on the maxfilter files?

  • annotate (bool) – add annotations to the Raw object.

Returns:

  • if annotate is False – bad segments : the dict of bad segments(including onset and duration).

  • if annotate is True –

    rawmne.io.Raw

    MNE raw object with bad segments annotated.

Notes

Note that for Elekta/MEGIN data, we recommend using picks: 'mag' or picks: 'grad' separately (in no particular order).

Note that with CTF data, mne.pick_types will return:

~274 axial grads (as magnetometers) if {picks: 'mag', ref_meg: False} ~28 reference axial grads if {picks: 'grad'}. Thus, it is recommended to use picks:'mag' in combination with ref_mag: False, and picks:'grad' separately (in no particular order).

msqms.libs.osl.osl_wrappers.detect_badchannels(raw, picks, ref_meg='auto', significance_level=0.05, annotate=False)[source]#

Set bad channels in an MNE Raw object as defined by the Generalized ESD test in osl.preprocessing.osl_wrappers.gesd.

Parameters:

  • raw (mne.io.Raw) – MNE raw object.

  • picks (str) – Channel types to pick. See Notes for recommendations.

  • ref_meg (str) – ref_meg argument to pass with mne.pick_types.

  • significance_level (float) – Significance level for detecting outliers. Must be between 0-1.

  • annotate (bool) – add annotations to the Raw object.

Returns:

  • if annotate is False – bad_channels : the list of bad channels.

  • if annotate is True –

    rawmne.io.Raw

    MNE raw object with bad channels annotated.

Notes

Note that for Elekta/MEGIN data, we recommend using picks:'mag' or picks:'grad' separately (in no particular order).

Note that with CTF data, mne.pick_types will return:

~274 axial grads (as magnetometers) if {picks: 'mag', ref_meg: False} ~28 reference axial grads if {picks: 'grad'}. Thus, it is recommended to use picks:'mag' in combination with ref_mag: False, and picks:'grad' separately (in no particular order).

msqms.libs.osl.osl_wrappers.drop_bad_epochs(epochs, picks, significance_level=0.05, max_percentage=0.1, outlier_side=0, metric='std', ref_meg='auto', mode=None)[source]#

Drop bad epochs in an MNE Epochs object as defined by the Generalized ESD test in osl.preprocessing.osl_wrappers.gesd.

Parameters:

  • epochs (mne.Epochs) – MNE Epochs object.

  • picks (str) – Channel types to pick.

  • significance_level (float) – Significance level for detecting outliers. Must be between 0-1.

  • max_percentage (float) – Maximum fraction of the epochs to drop. Should be between 0-1.

  • outlier_side (int) –

    Specify sidedness of the test:

    • outlier_side = -1 -> outliers are all smaller

    • outlier_side = 0 -> outliers could be small/negative or large/positive (default)

    • outlier_side = 1 -> outliers are all larger

  • metric (str) – Metric to use. Could be 'std', 'var' or 'kurtosis'.

  • ref_meg (str) – ref_meg argument to pass with mne.pick_types.

  • mode (str) – Should be 'diff' or None. When mode='diff' we calculate a difference time series before detecting bad segments.

Returns:

epochs – MNE Epochs object with bad epoches marked.

Return type:

mne.Epochs

Notes

Note that with CTF data, mne.pick_types will return:

~274 axial grads (as magnetometers) if {picks: 'mag', ref_meg: False} ~28 reference axial grads if {picks: 'grad'}.