nnsa.artefacts package

Submodules

nnsa.artefacts.artefact_detection module

Module for exclusion of artefacts.

Functions:

`check_amplitude`(x[, n, std_factor, axis])	Return a mask with True at samples where the amplitude falls within a moving average +- 3*moving std.
`check_amplitude_mad`(x[, threshold, n, axis])	Check amplitude based on median absolute deviation.
`check_max_diff`(x, n[, fs, std_factor, ...])	Return a mask with True at samples where the diff with prev and next sample is < 3*moving std.
`default_eeg_sample_quality_criteria`([fs])	Return dictionary with default criteria for EEG sample quality.
`default_eeg_signal_quality_criteria`([fs])	Return dictionary with default criteria for EEG signal quality.
`default_oxygen_sample_quality_criteria`([fs])	Return dictionary with default criteria for oxygen signal quality.
`detect_anomalous_channels`(x, window[, fs, ...])	Simple method to detect anomalous high-frequency/amplitude channels by setting a threshold on the line length.
`detect_artefact_samples`(x[, min_amp, ...])	Detect samples in x along the specified axis that do not meet the sample quality criteria.
`detect_artefact_signals`(x[, min_std, ...])	Detect signal(s) in x along the specified axis that do not meet the signal quality criteria.
`detect_flatlines`(x[, n_flatline, ...])	Detect flatlines, i.e. signal segments where the signal does not change for at least n_flatline consecutive samples.
`detect_high_amplitudes`(amp[, af_mask])	Detect high amplitude segments.
`remove_flatlines`(x[, inplace])	Detect flatlines and replace by np.nan.
`signal_quality`(x[, axis, demean, keepdims])	Return quality indices of the signal(s) in x along the specified axis.

nnsa.artefacts.artefact_detection.check_amplitude(x, n=-1, std_factor=3, axis=-1)[source]

Return a mask with True at samples where the amplitude falls within a moving average +- 3*moving std.

Parameters:

x (np.ndarray) – time series array.
n (int) – window size of moving average/std. If None or -1, the global average/std is taken.
std_factor (int, optional) – the number of stds that the amplitude can differ from the mean. Defaults to 3.
axis (int, optional) – time axis. Defaults to -1.

Returns:

amp_ok (np.ndarray) – boolean mask of same size as x, where True means that the amplitude is ok.

nnsa.artefacts.artefact_detection.check_amplitude_mad(x, threshold=3, n=-1, axis=-1)[source]

Check amplitude based on median absolute deviation.

See https://www.influxdata.com/blog/anomaly-detection-with-median-absolute-deviation/

nnsa.artefacts.artefact_detection.check_max_diff(x, n, fs=1, std_factor=3, which='std', min_max_diff=None, axis=-1)[source]

Return a mask with True at samples where the diff with prev and next sample is < 3*moving std.

Parameters:

x (np.ndarray) – time series array.
n (int) – window size of moving std. If None or -1, the global std is taken.
fs (float) – sample frequency of x.
std_factor (int, optional) – the number of stds that the diff can be. Defaults to 3.
which (str, optional) –
which metric to use for std. Choose from: - ‘std’ or ‘SD’: for standard deviation. - ‘mad’ or ‘MAD’: for median absolute deviation (alternative to std robust to outliers).

Only recommended for stationary series.
min_max_diff (float) – lower limit on the maximum diff. E.g. to prevent diff to go towards zero during a flatline.
axis (int, optional) – time axis. Defaults to -1.

Returns:

diff_ok (np.ndarray) – boolean mask of same size as x, where True means that the diff is ok.

nnsa.artefacts.artefact_detection.default_eeg_sample_quality_criteria(fs=250)[source]

Return dictionary with default criteria for EEG sample quality.

Parameters:: fs (float, optional) – sample frequency of EEG in Hz. Defaults to 250.
Returns:: criteria (dict) – dictionary with default criteria for sample quality.

nnsa.artefacts.artefact_detection.default_eeg_signal_quality_criteria(fs=250)[source]

Return dictionary with default criteria for EEG signal quality.

Returns:: criteria (dict) – dictionary with default criteria for signal quality.

nnsa.artefacts.artefact_detection.default_oxygen_sample_quality_criteria(fs=1)[source]

Return dictionary with default criteria for oxygen signal quality.

Parameters:: fs (float, optional) – sample frequency of the oxygen signal in Hz. Default to 1.
Returns:: criteria (dict) – dictionary with default criteria for sample quality.

nnsa.artefacts.artefact_detection.detect_anomalous_channels(x, window, fs=1, std_factor=8, p_trim=0.25, shape_mode='error')[source]

Simple method to detect anomalous high-frequency/amplitude channels by setting a threshold on the line length.

The log line length of the (1-p_strip)*n_channels with lowest line lengts is used to determine mean and std and if any channel exceeds mean + `std_factor`*std, then it is flagged as artefact. This is done per window.

Parameters:

x (np.ndarray) – multichannel signal with dimensions (n_channels, n_samples).
window (float) – the window length (in seconds if fs is given, else in samples) in which to compute line length.
fs (float) – sampling frequency of x.
std_factor (float) – the factor for std determining the threshold (mean+`std_factor*std).
p_trim (float) – the relative amount of channels to strip before computing the mean and std. The channels with the highest line lengths are stripped/excluded.
shape_mode (str) – what to do with unexpected input shape (see check_eeg_is_wide()).

Returns:

mask_anomamly (np.ndarray) – boolean array with same shape as x containing True at locations of anomalies.

Examples

>>> # Create dummy signal with 8 channels and an anomaly somewhere in the third channel.
>>> rng = np.random.RandomState(43)
>>> x = rng.random((8, 1000))
>>> x[2, 301:600] *= 10
>>> # Detect anomaly
>>> mask = detect_anomalous_channels(x, window=20)
>>> print(np.where(np.any(mask, axis=1))[0])
[2]
>>> onsets, offsets = get_onsets_offsets(mask[2])
>>> print(onsets)
[301]
>>> print(offsets)
[600]

nnsa.artefacts.artefact_detection.detect_artefact_samples(x, min_amp=-inf, max_amp=inf, max_diff=inf, num_artefact_free_neighbouring_samples=1, custom_functions=None, axis=-1, demean=False)[source]

Detect samples in x along the specified axis that do not meet the sample quality criteria.

Parameters:

x (np.ndarray) – array containing signal(s) along the specified axis.
min_amp (float, optional) – minimum accepted amplitude.
max_amp (float, optional) – maximum accepted amplitude.
max_diff (float, optional) – maximum accepted absolute difference with neighbouring sample.
num_artefact_free_neighbouring_samples (int, optional) – number of samples around the current sample that need to be artefact-free to consider the current sample artefact free. The number includes the current samples, so if it is 1, no neighbours are checked. If its 3, the previous and next sample are checked, etc. E.g. if this parameter is set to 5, the 2 samples before the current sample, the current sample itself and the 2 samples after the current sample need all to be artefact-free to consider the current sample to be artefact free.
custom_functions (list, optional) – list with functions that yield true for samples that are ok (i.e. non-artefact). Is applied after nans have been inserted based on min_amp, max_amp, max_diff.
axis (int, optional) – the axis corresponding to the time dimension of the signal(s) in x.
demean (bool, optional) – if True, subtracts the mean of the signal(s) from the signal(s) before assessing the sample quality. If False, does not subtract the mean. Defaults to False.

Returns:

artefact_mask (bool or np.ndarray) – boolean array where True entries correspond to samples that are artefacts, False entries correspond to non artefact sample. The shape of the array is the same as the shape of x.

nnsa.artefacts.artefact_detection.detect_artefact_signals(x, min_std=0, max_std=inf, min_amp=-inf, max_amp=inf, max_diff=inf, max_nan_frac=1, max_fraction_of_artefact_channels=1, axis=-1, channel_axis=0, demean=False, keepdims=False)[source]

Detect signal(s) in x along the specified axis that do not meet the signal quality criteria.

Parameters:

x (np.ndarray) – array containing signal(s) along the specified axis. For each signal in x a bool will be computed specifying whether the signal is an artefact or not.
min_std (float, optional) – minimum accepted standard deviation in signal.
max_std (flaot, optional) – maximum accepted standard deviation in signal.
min_amp (float, optional) – minimum accepted amplitude in signal,
max_amp (float, optional) – maximum accepted amplitude in signal.
max_diff (float, optional) – maximum accepted absolute difference between consecutive samples in signal.
max_nan_frac (float, optional) – maximum accepted fraction of nan samples (in time dimension).
max_fraction_of_artefact_channels (float, optional) – maximum accepted fraction of channels/signals in data array that may be artefacted (if the number of artefacted channels is higher, all channels are classified as artefacts).
axis (int, optional) – the axis corresponding to the time dimension of the signal(s) in x.
channel_axis (int, optional) – the axis corresponding to channels.
demean (bool, optional) – if True, subtracts the mean of the signal(s) from the signal(s) before assessing the signal quality. If False, does not subtract the mean. Defaults to True.
keepdims (bool, optional) – if True, the axes which are reduced are left in the output as dimensions with size 1. If False, the dimension corresponding to the specified axis is removed in the output. Defaults to False.

Returns:

artefact_mask (bool or np.ndarray) – boolean array where True entries correspond to signals that are artefacts, False entries correspond to non artefact signals. The shape of the array is the same as the shape of x, except along the specified axis (this axis is removed or reduced to 1, depending on keepdims).

nnsa.artefacts.artefact_detection.detect_flatlines(x, n_flatline='auto', flatline_range=None, fs=None, axis=-1, tol=1e-14)[source]

Detect flatlines, i.e. signal segments where the signal does not change for at least n_flatline consecutive samples.

Parameters:

x (np.array) – array with signal(s).
n_flatline (int or str, optional) – minimal number of consecutive non-changing samples to be considered a flatline segment. If fs is given, this is in unit of seconds. If ‘auto’, a sensible number of samples is automatically determined per signal.
flatline_range (list, optional) – [min, max] range of signal values that can be considered a potential flatline. Only flatlines with values inside this range are considered real flatlines. If None, all values can be a flatline. Defaults to None.
fs (float, optional) – sampling frequency in Hz. If given, n_flatline is in seconds. If fs is not specified, n_flatline is in samples.
axis (int, optional) – axis of the time dimension in x. Defaults to -1.
tol (float, optional) – tolerance for finding non changing samples. Defaults to 1e-14.

Returns:

mask (np.array) – boolean mask for input x where True values correspond to samples that belong to a flatline.

Examples

>>> x = [0, 0, 0, 1, 2, 3, 3, 2, 10, 10, 10, 10, 2, 2, 2, 2, 2, 1, 0]
>>> detect_flatlines(x, n_flatline=3, flatline_range=None)
array([ True,  True,  True, False, False, False, False, False,  True,
        True,  True,  True,  True,  True,  True,  True,  True, False,
       False])
>>> detect_flatlines(x, n_flatline=3, flatline_range=[0, 5])
array([ True,  True,  True, False, False, False, False, False, False,
       False, False, False,  True,  True,  True,  True,  True, False,
       False])

nnsa.artefacts.artefact_detection.detect_high_amplitudes(amp, af_mask=None)[source]

Detect high amplitude segments.

Parameters:

amp (np.ndarray) – (n_segments, n_channels)
af_mask (np.ndarray) – (n_segments, n_channels)

Returns:

is_high_amp (np.ndarray) – (n_segments, n_channels)

nnsa.artefacts.artefact_detection.remove_flatlines(x, inplace=False, **kwargs)[source]

Detect flatlines and replace by np.nan.

Parameters:

x (np.array) – array with signal(s).
inplace (bool) – whether to change x inplace or not.
**kwargs (optional) – keyword arguments for detect_flatlines().

Returns:

xn (np.array) – if not inplace: a copy of the original array x, but with np.nans at flatline segments.

nnsa.artefacts.artefact_detection.signal_quality(x, axis=-1, demean=True, keepdims=False)[source]

Return quality indices of the signal(s) in x along the specified axis.

Parameters:

x (np.ndarray) – array containing signal(s) along the specified axis. For each signal in x the quality indices will be computed.
axis (int, optional) – the axis corresponding to the time dimension of the signal(s) in x.
demean (bool, optional) – if True, subtracts the mean of the signal(s) from the signal(s) before computing the signal quality. If False, does not subtract the mean. Defaults to True.
keepdims (bool, optional) – if True, the axes which are reduced are left in the output as dimensions with size 1. If False, the dimension corresponding to the specified axis is removed in the output. Defaults to False.

Returns:

quality (dict) – dictionary with quality indices as keys and arrays containing the values of those indices for all signals in x as values.

nnsa.artefacts.clean_detector_cnn module

Classes:

CleanDetectorCnn([multi_channel, chunk_length])

Interface for applying clean EEG detection using a trained Convolutional Neural Network.

class nnsa.artefacts.clean_detector_cnn.CleanDetectorCnn(multi_channel=True, chunk_length=3600, **kwargs)[source]

Bases: ClassWithParameters

Interface for applying clean EEG detection using a trained Convolutional Neural Network.

References

T. Hermans et al., “A multi-task and multi-channel convolutional neural network for semi-supervised neonatal artefact detection,” Journal of Neural Engineering, vol. 20, no. 2, p. 26013, Mar. 2023, doi: 10.1088/1741-2552/acbc4b. https://pubmed.ncbi.nlm.nih.gov/36791462/

Parameters:

multi_channel (bool) – if True, use the multi-channel model, which requires a specific montage and order of channels (see self.data_requirements). If False, use the single-channel model (no specific montage required).
chunk_length (int, float) – number of seconds of EEG to process at once (EEG will be divided in chunks with maximal length chunk_size, predicted and then merged together). It is to prevent memory problems. If the RAM is large enough, you can set chunk_length to None to not process into chunks.

Examples

# TODO Load some raw eeg data, referenced to Cz.

# Initiate artefact detector object. cd = CleanDetectorCnn()

# Use the predict method to predict the clean mask for the eeg array. clean_mask, clean_prob = cd.predict(eeg, fs=fs))

Attributes:

`data_requirements`	Return some data requirements.
`fs_output`	Return sampling frequency of output.
`is_clean_detector`	Returns: (bool): True if the model is a clean EEG detector (instead of an artefact detector).
`model`	Return keras model.
`model_settings`	Returns dict with settings.
`normpars`	Returns tuple with mean, sd and channel labels.

Methods:

`default_parameters`()	Return the default parameters as a dictionary.
`predict`(eeg, fs[, preprocess, detect_flats, ...])	Detect clean parts in Cz-referenced EEG using the CNN model.
`preprocess_eeg`(eeg, fs[, axis, verbose])	Preprocess EEG data.

property data_requirements: Return some data requirements.

static default_parameters()[source]

Return the default parameters as a dictionary.

Returns:: (dict or Parameters) – a default set of parameters for the object.

property fs_output: Return sampling frequency of output.

property is_clean_detector: Returns: (bool): True if the model is a clean EEG detector (instead of an artefact detector).

property model: Return keras model.

property model_settings: Returns dict with settings.

property normpars: Returns tuple with mean, sd and channel labels.

predict(eeg, fs, preprocess=None, detect_flats=False, detect_peaks=False, verbose=1, **predict_kwargs)[source]

Detect clean parts in Cz-referenced EEG using the CNN model.

Parameters:

eeg (np.ndarray) – multichannel EEG referenced to Cz. Array with shape (n_time, n_channels). If using the multi-channel model, the order of the channels should be: [‘Fp1’, ‘Fp2’, ‘C3’, ‘C4’, ‘T3’, ‘T4’, ‘O1’, ‘O2’].
fs (flaot) – sampling frequency of eeg in Hz.
preprocess (bool) – specify whether the EEG needs to be preprocessed (filtered, resampled). Set to True if eeg is raw data (but note that it should still be referenced to Cz). If not specified, preprocessing will be done if fs is not 128, otherwise not.
detect_flats (bool) – if True, computes moving std in short windows and if its below a threshold, the sample is marked as artefact (since the CNN might not catch this).
detect_peaks (bool) – if True, computes moving max abs amplitude in short windows and if its above a threshold, the sample is marked as artefact (since the CNN might not catch this).
verbose (int) – verbosity level.
**predict_kwargs – kwargs for self.model.predict().

Returns:

mask (np.ndarray) – array with shape (n_time, n_channels) containing 1 at locations of clean EEG and 0 at artefacts.
prob (np.ndarray) – array with shape (n_samples, n_channels, n_classes) containing probabilies for artefact and clean. Note that n_samples depends on the output frequency (it is not the same as n_time of eeg).

static preprocess_eeg(eeg, fs, axis=0, verbose=1)[source]

Preprocess EEG data.

Parameters:

eeg (np.ndarray) – EEG data.
fs (float, int) – sampling frequency of eeg in Hz.
axis (int) – time axis. of eeg array.
verbose (int) – verbose level.

Returns:

eeg_out (np.ndarray) – preprocessed EEG data.
fs_out (int) – sampling frequency of preprocessed EEG.

Module contents

Module for artefact detection and correction.