msqms.libs.pyprep.find_noisy_channels module

finds bad channels.

Summary

Classes:

NoisyChannels

Detect bad channels in an MEG recording using a range of methods.

Reference

class msqms.libs.pyprep.find_noisy_channels.NoisyChannels(raw, do_detrend=True, random_state=None, matlab_strict=False)

Bases: object

Detect bad channels in an MEG recording using a range of methods.

This class provides a number of methods for detecting bad channels across a full-session MEG recording. Specifically, this class implements all of the noisy channel detection methods used in the PREP pipeline, as described in [1]_. The detection methods in this class can be run independently, or can be run all at once using the find_all_bads() method.

At present, only MEG channels are supported and any non-MEG channels in the provided data will be ignored.

Parameters:

• raw (mne.io.Raw) – An MNE Raw object to check for bad MEG channels.

• do_detrend (bool, optional) – Whether or not low-frequency (<1.0 Hz) trends should be removed from the MEG signal prior to bad channel detection. This should always be set to True unless the signal has already had low-frequency trends removed. Defaults to True.

• random_state ({int, None, np.random.RandomState}, optional) – The seed to use for random number generation within RANSAC. This can be None, an integer, or a RandomState object. If None, a random seed will be obtained from the operating system. Defaults to None.

• matlab_strict (bool, optional) – Whether or not PyPREP should strictly follow MATLAB PREP’s internal math, ignoring any improvements made in PyPREP over the original code (see matlab-diffs for more details). Defaults to False.

References

[1]

Bigdely-Shamlo, N., Mullen, T., Kothe, C., Su, K. M., Robbins, K. A. (2015). The PREP pipeline: standardized preprocessing for large-scale EEG analysis. Frontiers in Neuroinformatics, 9, 16.

get_bads(verbose=False, as_dict=False)

Get the names of all channels currently flagged as bad.

Note that this method does not perform any bad channel detection itself, and only reports channels already detected as bad by other methods.

Parameters:

• verbose (bool, optional) – If True, a summary of the channels currently flagged as by bad per category is printed. Defaults to False.

• as_dict (bool, optional) – If True, this method will return a dict of the channels currently flagged as bad by each individual bad channel type. If False, this method will return a list of all unique bad channels detected so far. Defaults to False.

Returns:

bads – The names of all bad channels detected so far, either as a combined list or a dict indicating the channels flagged bad by each type.

Return type:

list or dict

find_all_bads(ransac=True, channel_wise=False, max_chunk_size=None)

Call all the functions to detect bad channels.

This function calls all the bad-channel detecting functions.

Parameters:

• ransac (bool, optional) – Whether RANSAC should be used for bad channel detection, in addition to the other methods. RANSAC can detect bad channels that other methods are unable to catch, but also slows down noisy channel detection considerably. Defaults to True.

• channel_wise (bool, optional) – Whether RANSAC should predict signals for chunks of channels over the entire signal length (“channel-wise RANSAC”, see max_chunk_size parameter). If False, RANSAC will instead predict signals for all channels at once but over a number of smaller time windows instead of over the entire signal length (“window-wise RANSAC”). Channel-wise RANSAC generally has higher RAM demands than window-wise RANSAC (especially if max_chunk_size is None), but can be faster on systems with lots of RAM to spare. Has no effect if not using RANSAC. Defaults to False.

• max_chunk_size ({int, None}, optional) – The maximum number of channels to predict at once during channel-wise RANSAC. If None, RANSAC will use the largest chunk size that will fit into the available RAM, which may slow down other programs on the host system. If using window-wise RANSAC (the default) or not using RANSAC at all, this parameter has no effect. Defaults to None.

find_bad_by_nan_flat()

Detect channels than contain NaN values or have near-flat signals.

A channel is considered flat if its standard deviation or its median absolute deviation from the median (MAD) are below 1e-9 microvolts.

This method is run automatically when a NoisyChannels object is initialized, preventing flat or NaN-containing channels from interfering with the detection of other types of bad channels.

find_bad_by_deviation(deviation_threshold=5.0)

Detect channels with abnormally high or low overall amplitudes.

A channel is considered “bad-by-deviation” if its amplitude deviates considerably from the median channel amplitude, as calculated using a robust Z-scoring method and the given deviation threshold.

Amplitude Z-scores are calculated using the formula (channel_amplitude - median_amplitude) / amplitude_sd, where channel amplitudes are calculated using a robust outlier-resistant estimate of the signals’ standard deviations (IQR scaled to units of SD), and the amplitude SD is the IQR-based SD of those amplitudes.

Parameters:

deviation_threshold (float, optional) – The minimum absolute z-score of a channel for it to be considered bad-by-deviation. Defaults to 5.0.

find_bad_by_hfnoise(HF_zscore_threshold=5.0)

Detect channels with abnormally high amounts of high-frequency noise.

The noisiness of a channel is defined as the amplitude of its high-frequency (>50 Hz) components divided by its overall amplitude. A channel is considered “bad-by-high-frequency-noise” if its noisiness is considerably higher than the median channel noisiness, as determined by a robust Z-scoring method and the given Z-score threshold.

Due to the Nyquist theorem, this method will only attempt bad channel detection if the sample rate of the given signal is above 100 Hz.

Parameters:

HF_zscore_threshold (float, optional) – The minimum noisiness z-score of a channel for it to be considered bad-by-high-frequency-noise. Defaults to 5.0.

find_bad_by_correlation(correlation_secs=1.0, correlation_threshold=0.4, frac_bad=0.01)

Detect channels that sometimes don’t correlate with any other channels.

Channel correlations are calculated by splitting the recording into non-overlapping windows of time (default: 1 second), getting the absolute correlations of each usable channel with every other usable channel for each window, and then finding the highest correlation each channel has with another channel for each window (by taking the 98th percentile of the absolute correlations).

A correlation window is considered “bad” for a channel if its maximum correlation with another channel is below the provided correlation threshold (default: 0.4). A channel is considered “bad-by-correlation” if its fraction of bad correlation windows is above the bad fraction threshold (default: 0.01).

This method also detects channels with intermittent dropouts (i.e., regions of flat signal). A channel is considered “bad-by-dropout” if its fraction of correlation windows with a completely flat signal is above the bad fraction threshold (default: 0.01).

Parameters:

• correlation_secs (float, optional) – The length (in seconds) of each correlation window. Defaults to 1.0.

• correlation_threshold (float, optional) – The lowest maximum inter-channel correlation for a channel to be considered “bad” within a given window. Defaults to 0.4.

• frac_bad (float, optional) – The minimum proportion of bad windows for a channel to be considered “bad-by-correlation” or “bad-by-dropout”. Defaults to 0.01 (1% of all windows).

find_bad_by_SNR()

Detect channels that have a low signal-to-noise ratio.

Channels are considered “bad-by-SNR” if they are bad by both high-frequency noise and bad by low correlation.

find_bad_by_ransac(n_samples=50, sample_prop=0.25, corr_thresh=0.75, frac_bad=0.4, corr_window_secs=5.0, channel_wise=False, max_chunk_size=None)

Detect channels that are predicted poorly by other channels.

This method uses a random sample consensus approach (RANSAC, see [1]_, and a short discussion in [2]) to try and predict what the signal should be for each channel based on the signals and spatial locations of other currently-good channels. RANSAC correlations are calculated by splitting the recording into non-overlapping windows of time (default: 5 seconds) and correlating each channel’s RANSAC-predicted signal with its actual signal within each window.

A RANSAC window is considered “bad” for a channel if its predicted signal vs. actual signal correlation falls below the given correlation threshold (default: 0.75). A channel is considered “bad-by-RANSAC” if its fraction of bad RANSAC windows is above the given threshold (default: 0.4).

Due to its random sampling component, the channels identified as “bad-by-RANSAC” may vary slightly between calls of this method. Additionally, bad channels may vary between different montages given that RANSAC’s signal predictions are based on the spatial coordinates of each electrode.

This method is a wrapper for the find_bad_by_ransac() function.

Warning

For optimal performance, RANSAC requires that channels bad by deviation, correlation, and/or dropout have already been flagged. Otherwise RANSAC will attempt to use those channels when making signal predictions, decreasing accuracy and thus increasing the likelihood of false positives.

Parameters:

• n_samples (int, optional) – Number of random channel samples to use for RANSAC. Defaults to 50.

• sample_prop (float, optional) – Proportion of total channels to use for signal prediction per RANSAC sample. This needs to be in the range [0, 1], where 0 would mean no channels would be used and 1 would mean all channels would be used (neither of which would be useful values). Defaults to 0.25 (e.g., 16 channels per sample for a 64-channel dataset).

• corr_thresh (float, optional) – The minimum predicted vs. actual signal correlation for a channel to be considered good within a given RANSAC window. Defaults to 0.75.

• frac_bad (float, optional) – The minimum fraction of bad (i.e., below-threshold) RANSAC windows for a channel to be considered bad-by-RANSAC. Defaults to 0.4.

• corr_window_secs (float, optional) – The duration (in seconds) of each RANSAC correlation window. Defaults to 5 seconds.

• channel_wise (bool, optional) – Whether RANSAC should predict signals for chunks of channels over the entire signal length (“channel-wise RANSAC”, see max_chunk_size parameter). If False, RANSAC will instead predict signals for all channels at once but over a number of smaller time windows instead of over the entire signal length (“window-wise RANSAC”). Channel-wise RANSAC generally has higher RAM demands than window-wise RANSAC (especially if max_chunk_size is None), but can be faster on systems with lots of RAM to spare. Defaults to False.

• max_chunk_size ({int, None}, optional) – The maximum number of channels to predict at once during channel-wise RANSAC. If None, RANSAC will use the largest chunk size that will fit into the available RAM, which may slow down other programs on the host system. If using window-wise RANSAC (the default), this parameter has no effect. Defaults to None.

References

[1]

Fischler, M.A., Bolles, R.C. (1981). Random sample consensus: A Paradigm for Model Fitting with Applications to Image Analysis and Automated Cartography. Communications of the ACM, 24, 381-395

[2]

Jas, M., Engemann, D.A., Bekhti, Y., Raimondo, F., Gramfort, A. (2017). Autoreject: Automated Artifact Rejection for MEG and EEG Data. NeuroImage, 159, 417-429