nnsa.feature_extraction package

Subpackages

Submodules

nnsa.feature_extraction.aeeg module

Code related to amplitude-integrated EEG (aEEG) computation. Contains multiple algorithms for aEEG computation, some based on MATLAB code. compute_aeeg_tw fully runs in Python, which should make it the fastest.

Classes:

`AmplitudeEeg`([eng])	Class for emulating an amplitude-integrated (aEEG) signal from single channel continuous EEG.
`AmplitudeEegResult`(aeeg, fs, ...[, label, ...])	High-level interface for processing the results of aEEG computation as created by nnsa.AmplitudeEeg().

Functions:

`compute_aeeg_cc`(eeg, fs[, eng])	Compute amplitude-integrated EEG (aEEG) from single channel continuous EEG.
`compute_aeeg_neat`(eeg, fs[, gain])	Compute amplitude-integrated EEG (aEEG) from single channel continuous EEG.
`compute_aeeg_tw`(eeg, fs[, gain, rma_win])	Compute amplitude-integrated EEG (aEEG) from single channel continuous EEG.
`filter_aeeg_zhang`(x, fs[, correct_delay])	Apply an assymetric FIR filter with specifications as proposed by Zhang and Ding, 2013.

class nnsa.feature_extraction.aeeg.AmplitudeEeg(eng=None, **kwargs)[source]

Bases: ClassWithParameters

Class for emulating an amplitude-integrated (aEEG) signal from single channel continuous EEG.

Multiple different algorithms can be used, see self.default_parameters().

Main method: amplitude_eeg() or process().

Parameters:

eng (matlab.engine.matlabengine.MatlabEngine, optional) – Deprecated. MATLAB engine to use for calling MATLAB functions. The required paths must already have been initialized (see self.eng()). Only relevant if an algorithm that requires MATLAB is used. If None, a new MATLAB engine will be started (which takes some time). Defaults to None.
**kwargs (optional) – see nnsa.ClassWithParameters.

Examples

>>> fs = 256
>>> t = 1/fs*np.arange(100000)
>>> x = 4 * np.sin(t)
>>> AEEG = AmplitudeEeg(method='neat', dtype=np.float32)
>>> print(type(AEEG.parameters).__name__)
Parameters

>>> result = AEEG.wct(x, fs=fs, verbose=0)
>>> print(type(result).__name__)
AmplitudeEegResult

>>> result.aeeg
array([0.21567792, 0.21360768, 0.21153691, ..., 0.08440158, 0.0844016 ,
       0.08440162], dtype=float32)

Methods:

`amplitude_eeg`(eeg, fs[, label, verbose])	Compute the aEEG signal.
`default_parameters`()	Return the default parameters.
`process`(args, *kwargs)	Shortcut to main function.

Attributes:

eng

Return a MATLAB engine.

amplitude_eeg(eeg, fs, label='aEEG', verbose=0)[source]

Compute the aEEG signal.

Samples that are nan in the input will be nan in the output.

Parameters:

eeg (np.ndarray) – single channel EEG signal.
fs (float) – sample frequency of eeg in Hz.
label (str, optional) – label for the aEEG signal. Defaults to ‘aEEG’.
verbose (int, optional) – verbose level. Defaults to 0.

Returns:

(nnsa.AmplitudeEegResult) – object containing the aEEG.

static default_parameters()[source]

Return the default parameters.

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

property eng

Return a MATLAB engine.

Returns:: (matlab.engine.matlabengine.MatlabEngine) – MATLAB engine.

process(*args, **kwargs)[source]: Shortcut to main function.

class nnsa.feature_extraction.aeeg.AmplitudeEegResult(aeeg, fs, algorithm_parameters, label=None, data_info=None, time_offset=0)[source]

Bases: ResultBase

High-level interface for processing the results of aEEG computation as created by nnsa.AmplitudeEeg().

Parameters:

aeeg (np.ndarray) – the aEEG signal with sample frequency fs in semilog-scale (amplitudes 0-10 linear and amplitude > 10 logarithmic).
fs (float) – sample frequency of aeeg.
algorithm_parameters (nnsa.Parameters) – see ResultBase.
label (str, optional) – label of the aEEG signal. Defaults to ‘aEEG’.
data_info (str, optional) – see ResultBase.

Methods:

`extract_margins`([segment_length, fs, ...])	Extract upper and lower margin amplitudes by extracting the low and high percentiles in (overlapping) segments.
`plot`([plot_margins, ax])	Plot the envelope.
`to_time_series`([which, unit])	Create a TimeSeries object from the aEEG data.

Attributes:

num_segments

Return the number of segments (number of samples).

extract_margins(segment_length=None, fs=None, q_lower=10, q_upper=90, max_nan=0.5, correct_delay=False)[source]

Extract upper and lower margin amplitudes by extracting the low and high percentiles in (overlapping) segments.

Parameters:

segment_length (float, optional) – length of the segments/moving window to compute the margins in (in seconds). If None, a default value is taken based on the aEEG conversion method used. Defaults to None.
fs (float) – desired sample frequency of the returned margins in Hz. If None, a default value is taken based on the aEEG conversion method used. Defaults to None.
q_lower (float, optional) – percentile for the lower margin (0-100). Defaults to 10.
q_upper (float, optional) – percentile for the upper margin (0-100). Defaults to 90.
max_nan (float, optional) – maximum fraction (0-1) of nan values in a segment. If the fraction of nan samples exceeds max_nan, the margins are nan for that segment. Defaults to 0.5.
correct_delay (bool) – whether to correct for delay by padding.

Returns:

aeeg_lower (np.ndarray) – lower margin amplitudes with frequency fs_margins.
aeeg_upper (np.ndarray) – upper margin amplitudes with frequency fs_margins.
fs (float) – sample frequency of aeeg_lower and aeeg_upper in Hz.

property num_segments

Return the number of segments (number of samples).

Returns:: (int) – number of segments/samples.

plot(plot_margins=True, ax=None, **kwargs)[source]

Plot the envelope.

Parameters:

plot_margins (bool, optional) – if True, plots the upper and lower margin amplitudes as dark fat lines. If False, does not plot the margins. Defaults to True.
ax (plt.axes, optional) – axes to plot in. If None, will plot in a new figure. Defaults to None.
**kwargs (optional) – keyword arguments for nnsa.TimeSeries.plot().

to_time_series(which='bandwidth', unit='uV', **kwargs)[source]

Create a TimeSeries object from the aEEG data.

Parameters:

which (str, optional) –
which signal to export to a time series. Choose from:

’raw’ ‘LMA’ (lower margin amplitude), ‘UMA’ (upper margin amplitude), ‘bandwidth’ (UMA - LMA).

Defaults to ‘bandwidth’.
unit (str, optional) – unit of the aEEG data. Defaults to ‘uV’.
**kwargs (optional) – optional keyword arguments for the TimeSeries object.

Returns:

ts (nnsa.TimeSeries) – TimeSeries containing the aEEG data.

nnsa.feature_extraction.aeeg.compute_aeeg_cc(eeg, fs, eng=None)[source]

Compute amplitude-integrated EEG (aEEG) from single channel continuous EEG.

Algorithm by Amir Ansari, Georgios Lazaridis and and Christos Chatzichristos @ KU Leuven, 2013.

Runs on MATLAB in the background.

Parameters:

eeg (np.ndarray) – single channel EEG signal.
fs (float) – sample frequency of eeg in Hz.
eng (matlabengine, optional) – started matlab engine. If None, a new matlab engine will be started. Defaults to None.

Returns:

aeeg (np.ndarray) – the aEEG signal with sample frequency fs (linear scale).

nnsa.feature_extraction.aeeg.compute_aeeg_neat(eeg, fs, gain=1.631)[source]

Compute amplitude-integrated EEG (aEEG) from single channel continuous EEG.

Algorithm ported from the Neonatal EEG Analysis Toolbox (NEAT) for MATLAB.

References

Z. A. Vesoulis, P. G. Gamble, S. Jain, N. M. E. Ters, S. M. Liao, and A. M. Mathur, “WU-NEAT: A clinically validated, open- source MATLAB toolbox for limited-channel neonatal EEG analysis,” 2018-05-11.

Parameters:

eeg (np.ndarray) – single channel EEG signal (not filtered).
fs (float) – sample frequency of eeg in Hz.
gain (float, optional) – filter gain. Defaults to 1.631

Returns:

aeeg (np.ndarray) – the aEEG signal with sample frequency fs (linear scale).

nnsa.feature_extraction.aeeg.compute_aeeg_tw(eeg, fs, gain=5, rma_win=3)[source]

Compute amplitude-integrated EEG (aEEG) from single channel continuous EEG.

Algorithm emulates aEEG as generated by Olympic CFM 6000 system, as described in Tobias Werther et al.

References

T. Werther, M. Olischar, G. Naulaers, P. Deindl, K. Klebermass-Schrehof, and N. Stevenson, “Are All Amplitude-Integrated Electroencephalogram Systems Equal?,” Neonatology, vol. 112, no. 4, pp. 394–401, 2017, doi: 10.1159/000480008.

Parameters:

eeg (np.ndarray) – single channel EEG signal.
fs (float) – sample frequency of eeg in Hz.
gain (float, optional) – filter gain. Defaults to 5.
rma_win (float, optional) – rectangular moving average (RMA) window (in seconds). Defaults to 3.

Returns:

aeeg (np.ndarray) – the aEEG signal with sample frequency fs (linear scale).)

nnsa.feature_extraction.aeeg.filter_aeeg_zhang(x, fs, correct_delay=True)[source]

Apply an assymetric FIR filter with specifications as proposed by Zhang and Ding, 2013.

This filter is an approximation of a filter to compute aEEG from continuous EEG.

References

D. Zhang and H. Ding, “Calculation of compact amplitude-integrated EEG tracing and upper and lower margins using raw EEG data,” Health, vol. 05, no. 05, pp. 885–891, 2013, doi: 10.4236/health.2013.55116.

Parameters:

x (np.ndarray) – (single channel EEG) signal.
fs (float) – sample frequency of x` in Hz.
correct_delay (bool, optional) – if True, corrects for the delay introduced by the FIR filter. If False, no correction is applied.

Returns:

y (np.ndarray) – filtered signal.

nnsa.feature_extraction.brain_age module

Classes:

`BrainAge`(**kwargs)	Class for prediction of the (functional) brain age based on EEG-data.
`BrainAgeResult`(brain_age, algorithm_parameters)	Result class for (ensemble of) brain age estimates.

class nnsa.feature_extraction.brain_age.BrainAge(**kwargs)[source]

Bases: ClassWithParameters

Class for prediction of the (functional) brain age based on EEG-data.

References: K. Pillay, A. Dereymaeker, K. Jansen, G. Naulaers, and M. D. Vos, “Applying a data-driven approach to quantify EEG maturational deviations in preterms with normal and abnormal neurodevelopmental outcomes,” Scientific Reports, vol. 10, no. 1, Apr. 2020, doi: 10.1038/s41598-020-64211-0.

Parameters:: **kwargs (optional) – see nnsa.ClassWithParameters.

Examples

TODO

Methods:

`brain_age`(data_matrix, fs, channel_labels[, ...])	Predict the brain age.
`default_parameters`()	Return the default parameters.
`process`(args, *kwargs)

brain_age(data_matrix, fs, channel_labels, verbose=1)[source]

Predict the brain age.

Parameters:

data_matrix (np.ndarray) – EEG data (channels, time), see check_multichannel_data_matrix().
fs (float) – sample frequency of EEG data.
channel_labels (list) – list with channels labels of data_matrix, see check_multichannel_data_matrix().
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

result (BrainAgeResult) – the predicted brain age result.

static default_parameters()[source]

Return the default parameters.

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

process(*args, **kwargs)[source]

class nnsa.feature_extraction.brain_age.BrainAgeResult(brain_age, algorithm_parameters, fs=None, is_novelty=None, novelty_scores=None, model_names=None, data_info=None, segment_start_times=None, segment_end_times=None, time_offset=0)[source]

Bases: ResultBase

Result class for (ensemble of) brain age estimates.

Parameters:

brain_age (np.ndarray) – array with shape (n_segment, n_models). If only one model is used, n_models can be 1.
algorithm_parameters (nnsa.Parameters) – see ResultBase.
fs (float) – 1/segment length in Hz.
is_novelty (np.ndarray, None) – optional boolean array with shape (n_segments,) indicating which segmentes were classified as novelties (out-of-data).
novelty_scores (np.ndarray, None) – optional array with shape (n_segments,) containing novelty scores.
model_names (list) – optional list with names for models. Should have length n_models.
data_info (str, optional) – see ResultBase.
segment_start_times (np.ndarray, optional) – see ResultBase.
segment_end_times (np.ndarray, optional) – see ResultBase.

Attributes:

`num_segments`	Return the number of segments.
`time_axis`
`y_pred`

Methods:

`plot`([time_scale, color, ax, novelty_kwargs])	Simple plot of brain age.
`remove_unreliabilities`(aci_per_seg[, ...])	Return an array with FBA estimates for each segment and model, but without the segments containing (too much) artefacts and novelties.
`robust_fba`([aci_per_seg, verbose])	Robust FBA prediction by selecting segments without artefacts or novelties.
`to_df`()	Convert segment-wise results to pandas DataFrame.

property num_segments

Return the number of segments.

Returns:: (int) – number of segments.

plot(time_scale=None, color=None, ax=None, novelty_kwargs=None, **kwargs)[source]

Simple plot of brain age.

Parameters:

time_scale (str, optional) – time scale, see nnsa.data.plotting.convert_time_scale(). Defaults to ‘hours’.
color (str) – color to plot in.
ax (plt.Axes, optional) – axes object to plot in. If None, plots in the current axes. Defaults to None
novelty_kwargs (dict) – kwargs for plt.scatter for indicating novelties.
kwargs – for plt.plot().

remove_unreliabilities(aci_per_seg, aci_thres=50, min_num_segments=3, how='remove', verbose=1)[source]

Return an array with FBA estimates for each segment and model, but without the segments containing (too much) artefacts and novelties.

Parameters:

aci_per_seg (np.ndarray) – array with length n_segments containing the artefact contamination index (%) for each segment. If None, does not check for artefacts (only novelties).
aci_thres (float) – threshold for ACI (%).
min_num_segments (int) – minimum number of consecutive reliable segments.
how (str) – what to do with unreliabilities. ‘remove’: removes the segments from the array. ‘nan’: replaces the unreliable segments with nan.
verbose (int) – verbosity level.

Returns:

y_pred_ens (np.ndarray) – array with shape (n_segments, n_models) containing selected FBA estimates (novelties, artefact segments removed).

robust_fba(aci_per_seg=None, verbose=1)[source]

Robust FBA prediction by selecting segments without artefacts or novelties.

Parameters:

aci_per_seg (np.ndarray) – array with length n_segments containing the artefact contamination index (%) for each segment. If None, only the novelties are used for robust FBA.
verbose (int) – verbosity level.

Returns:

data (pd.Series) – results (median, some quantiles, and the FBAs of the selected segments).

property time_axis

to_df()[source]: Convert segment-wise results to pandas DataFrame.

property y_pred

nnsa.feature_extraction.brain_age_cnn module

Classes:

`BrainAgeResult`(brain_age, algorithm_parameters)	Result class for (ensemble of) brain age estimates.
`BrainAgeSinc`([which, detect_novelties])	Deep shared inception ensemble model for brain age estimation.

class nnsa.feature_extraction.brain_age_cnn.BrainAgeResult(brain_age, algorithm_parameters, fs=None, is_novelty=None, novelty_scores=None, model_names=None, data_info=None, segment_start_times=None, segment_end_times=None, time_offset=0)[source]

Bases: ResultBase

Result class for (ensemble of) brain age estimates.

Parameters:

brain_age (np.ndarray) – array with shape (n_segment, n_models). If only one model is used, n_models can be 1.
algorithm_parameters (nnsa.Parameters) – see ResultBase.
fs (float) – 1/segment length in Hz.
is_novelty (np.ndarray, None) – optional boolean array with shape (n_segments,) indicating which segmentes were classified as novelties (out-of-data).
novelty_scores (np.ndarray, None) – optional array with shape (n_segments,) containing novelty scores.
model_names (list) – optional list with names for models. Should have length n_models.
data_info (str, optional) – see ResultBase.
segment_start_times (np.ndarray, optional) – see ResultBase.
segment_end_times (np.ndarray, optional) – see ResultBase.

Attributes:

`num_segments`	Return the number of segments.
`time_axis`
`y_pred`

Methods:

`plot`([time_scale, color, ax, novelty_kwargs])	Simple plot of brain age.
`remove_unreliabilities`(aci_per_seg[, ...])	Return an array with FBA estimates for each segment and model, but without the segments containing (too much) artefacts and novelties.
`robust_fba`([aci_per_seg, verbose])	Robust FBA prediction by selecting segments without artefacts or novelties.
`to_df`()	Convert segment-wise results to pandas DataFrame.

property num_segments

Return the number of segments.

Returns:: (int) – number of segments.

plot(time_scale=None, color=None, ax=None, novelty_kwargs=None, **kwargs)[source]

Simple plot of brain age.

Parameters:

time_scale (str, optional) – time scale, see nnsa.data.plotting.convert_time_scale(). Defaults to ‘hours’.
color (str) – color to plot in.
ax (plt.Axes, optional) – axes object to plot in. If None, plots in the current axes. Defaults to None
novelty_kwargs (dict) – kwargs for plt.scatter for indicating novelties.
kwargs – for plt.plot().

remove_unreliabilities(aci_per_seg, aci_thres=50, min_num_segments=3, how='remove', verbose=1)[source]

Return an array with FBA estimates for each segment and model, but without the segments containing (too much) artefacts and novelties.

Parameters:

aci_per_seg (np.ndarray) – array with length n_segments containing the artefact contamination index (%) for each segment. If None, does not check for artefacts (only novelties).
aci_thres (float) – threshold for ACI (%).
min_num_segments (int) – minimum number of consecutive reliable segments.
how (str) – what to do with unreliabilities. ‘remove’: removes the segments from the array. ‘nan’: replaces the unreliable segments with nan.
verbose (int) – verbosity level.

Returns:

y_pred_ens (np.ndarray) – array with shape (n_segments, n_models) containing selected FBA estimates (novelties, artefact segments removed).

robust_fba(aci_per_seg=None, verbose=1)[source]

Robust FBA prediction by selecting segments without artefacts or novelties.

Parameters:

aci_per_seg (np.ndarray) – array with length n_segments containing the artefact contamination index (%) for each segment. If None, only the novelties are used for robust FBA.
verbose (int) – verbosity level.

Returns:

data (pd.Series) – results (median, some quantiles, and the FBAs of the selected segments).

property time_axis

to_df()[source]: Convert segment-wise results to pandas DataFrame.

property y_pred

class nnsa.feature_extraction.brain_age_cnn.BrainAgeSinc(which='v2', detect_novelties=True, **kwargs)[source]

Bases: ClassWithParameters

Deep shared inception ensemble model for brain age estimation.

References

A. Ansari et al., “Brain age as an estimator of neurodevelopmental outcome: A deep learning approach for neonatal cot-side monitoring,” Jan. 2023, doi: 10.1101/2023.01.24.525361

Parameters:

which (str) – string specifying which model to use. Options: - ‘v1’: the one trained by Ansari and Pillay as available on (as of June 2022): https://github.com/amirans65/brainagemodel/tree/c948967d7a42e237fa6cc8991b696b662300f6e2/brainagemodel/pretrained - ‘v2’: the one retrained by Hermans including more older neonates.
**kwargs – see default_parameters().

Attributes:

`all_models`	Return the model.
`data_requirements`	Return a dictionary with requirements for the input of the CNN.
`normalization_parameters`	Return the normalization parameters.

Methods:

`brain_age_sinc`(eeg_ds[, verbose])	TODO
`default_parameters`()	Return the default parameters as a dictionary.
`preprocess`(eeg, fs[, axis, verbose])	Preprocess, normalize, segment.
`process`(eeg, fs[, batch_size, axis, verbose])	Predict brain age.

property all_models

Return the model.

Returns:: (nnsa.model or keras.model) – model object.

brain_age_sinc(eeg_ds, verbose=1)[source]

TODO

Parameters:

x (np.ndarray) – TODO
verbose (int, optional) – verbose level (0 or 1). Default to 1.

Returns:

(BrainAgeSincResult) – nnsa object containing the results of the CNN brain age predictor.

property data_requirements

Return a dictionary with requirements for the input of the CNN.

Returns:: data_requirements (dict) – a dictionary with requirements for the input of the CNN (channel order, fs, segment length).

static default_parameters()[source]

Return the default parameters as a dictionary.

Returns:: (nnsa.Parameters) – a default set of parameters for the model.

property normalization_parameters

Return the normalization parameters.

Returns:: (tuple) – normalization parameters.

preprocess(eeg, fs, axis=1, verbose=1)[source]

Preprocess, normalize, segment.

Parameters:: self.process(). (see) –
Returns:: x (np.ndarray) – array with shape (n_seg, n_time, n_channels).

process(eeg, fs, batch_size=None, axis=-1, verbose=1)[source]

Predict brain age.

Includes preprocessing (filtering, segmentation, normalization)

Note that the channel order in eeg must be according to self.data_requirements[‘channel_order’].

Parameters:

eeg (np.ndarray) – 2D-array with raw (multichannel) EEG data. The channel order must be the same as specified in self.data_requirements.
fs (float) – sampling frequency of EEG.
batch_size (int, None) – number of segments to proces at once. If None, processes all segments at once, but in case of memory issues (for long recordings), you may set this value to e.g. 7200 to process 7200 segments (1h of EEG) at a time.
axis (int) – the time axis of eeg.
verbose (int) – verbosity level.

Returns:

(BrainAgeResult) – nnsa object containing the results of the brain age predictor.

nnsa.feature_extraction.common module

Common functions for the feature extraction algorithms.

Functions:

`aggregate_channel_events`(detected[, ...])	Aggregate the event masks of all channels into one global event mask.
`aggregate_channel_features`(data[, axis])	Aggregate features per channel to one global feature.
`aggregate_channel_segment_features`(data, ...)	Helper function to aggregate features consisting of (channels, segments).
`aggregate_segment_features`(data[, axis])	Aggregate features per segment to one global feature.
`baseline_correction_min`(x, window_length)	Do a baseline correction on x, by subtracting the minimum value in x in a window preceding x.
`check_multichannel_data_matrix`(data_matrix)	Check data_matrix, which is the input of most feature_extraction methods.
`get_channel_index`(channel_labels, channels)	Return the row index/indices of the specified channel(s) in channel_labels.
`local_to_global_features`(features, ...[, ...])	Helper function to go from local features (per channel, per segment) to global features.
`prepare_postfix`(postfix)	Helper function to prepare a postfix.
`preprocess_segment`(seg, fs[, ...])	Preprocess an EEG segment.
`print_init_message`(obj)	Print message when feature extraction algorithm initiates.

nnsa.feature_extraction.common.aggregate_channel_events(detected, min_channels=None, min_channels_elong=None)[source]

Aggregate the event masks of all channels into one global event mask.

Handles np.nan values by assigning np.nan to indices where all channels in detected are np.nan.

Parameters:

detected (np.ndarray) – array with dimensions (channels, time) containing 1s at samples with detected events and 0s at samples without the event (e.g. burst mask).
min_channels (int, optional) – minimum number of channels to detected the event in order to consider the event detected glabally (after aggregation). If None, the value is set to the total number of channels available in the input array. Defaults to None.
min_channels_elong (int, optional) – minimum number of channels that must detect the event when elongating the globally detected events. If None, the detected global events are not elongated. Defaults to None.

Returns:

detected_agg (np.ndarray) – array with shape (detected.shape[1]) containing 1s at samples with detected global events (across multiple channels) and 0s at samples without the event (e.g. burst mask). The type is float, since it may contain np.nan values (if present in detected input).

Examples

>>> detected = np.array([[1, 1, 0, 0, 0, 1, 1, 1, 0, 0], [1, 1, 0, 1, 0, 0, 1, 0, 1, 0]])
>>> print(detected)
[[1 1 0 0 0 1 1 1 0 0]
 [1 1 0 1 0 0 1 0 1 0]]
>>> aggregate_channel_events(detected, min_channels=2)
array([1., 1., 0., 0., 0., 0., 1., 0., 0., 0.])
>>> aggregate_channel_events(detected, min_channels=2, min_channels_elong=1)
array([1., 1., 0., 0., 0., 1., 1., 1., 1., 0.])

nnsa.feature_extraction.common.aggregate_channel_features(data, axis=0)[source]

Aggregate features per channel to one global feature.

This is a shortcut, called by most feature extraction classes, so changing this function, affects most features.

Parameters:

data (np.ndarray) – data array where one axis corresponds to channels.
axis (int, optional) – the axis in data corresponding to the channels. Defaults to 0.

Returns:

(np.ndarray) – array containing the aggregated data with the same shape as data, expect for axis. The axis dimension has been removed.

nnsa.feature_extraction.common.aggregate_channel_segment_features(data, feature_name, aggregate_segments=<function aggregate_segment_features>, aggregate_channels=<function aggregate_channel_features>, channel_labels=None, postfix=None)[source]

Helper function to aggregate features consisting of (channels, segments).

Parameters:

data (np.ndarray) – array with dimensions corresponding to (channels, segments).
feature_name (str) – name of the feature.
aggregate_segments (function, optional) – function that takes an array of segment features as input and returns one aggregate value. Defaults to aggregate_segment_features.
aggregate_channels (function or None, optional) – function that takes an array of channel features and returns one aggregate values. If None, the channels are not aggregated, i.e. the feature values each channel are returned per channel. Defaults to aggregate_channel_features.
channel_labels (list or None, optional) – list of strings representing labels corresponding to the first dimension of data. Can only be None if aggregate_channels is not None. Defaults to None.
postfix (str, optional) – postfix for the feature name. If None, no postfix will be added. Defaults to None.

Returns:

features (dict) – dictionary with aggregated features. The keys include the feature_name and optionally the channel label (if aggregate_channels is None) and postfix if not None.

nnsa.feature_extraction.common.aggregate_segment_features(data, axis=-1)[source]

Aggregate features per segment to one global feature.

This is a shortcut, called by most feature extraction classes, so changing this function, affects most features.

Parameters:

data (np.ndarray) – data array where one axis corresponds to segments.
axis (int, optional) – the axis in data corresponding to the segments. Defaults to -1.

Returns:

(np.ndarray) – array containing the aggregated data with the same shape as data, expect for axis. The axis dimension has been removed.

nnsa.feature_extraction.common.baseline_correction_min(x, window_length)[source]

Do a baseline correction on x, by subtracting the minimum value in x in a window preceding x.

x_corrected[i] = x[i] - min{x[j] | j in{i - window_length, …, i}}.

For the first window_length samples, the minimum value in this segment is used as baseline.

Parameters:

x (np.ndarray) – 1D array with signal.
window_length (int) – length of the window to look for the minimum.

Returns:

x_corrected (np.ndarray) – 1D array of the same size as x.

Examples

>>> x = np.array([5, 4, 6, 2, 4, 3, 5, 6, 1, 0, 8, 9, 7, 9])
>>> print(x)
[5 4 6 2 4 3 5 6 1 0 8 9 7 9]
>>> x_corrected = baseline_correction_min(x, window_length=4)
>>> baseline = x - x_corrected
>>> print(baseline)
[2 2 2 2 2 2 2 3 1 0 0 0 0 7]
>>> print(x_corrected)
[3 2 4 0 2 1 3 3 0 0 8 9 7 2]

nnsa.feature_extraction.common.check_multichannel_data_matrix(data_matrix, channel_labels=None)[source]

Check data_matrix, which is the input of most feature_extraction methods.

Parameters:

data_matrix (np.ndarray) – 2D array with dimensions (channels, time) containing multichannel data. If data_matrix has only one dimension, it is automatically converted to shape (1, len(data_matrix)).
channel_labels (list of str, optional) – optional list of labels for the channels in data_matrix. Defaults to None.

Returns:

data_matrix (np.ndarray) – data_matrix, possibly reshaped.
channel_labels (list, optional) – channel_labels, possibly converted from string to list.

Raises:

ValueError –

if matrix.ndim is not 1 or 2. - if the size of the first axis exceeds the size of the second axis in data_matrix (assume we have more time points than channels). - if the number of channel labels specified does not correspond with the size of the first axis of data_matrix.

nnsa.feature_extraction.common.get_channel_index(channel_labels, channels)[source]

Return the row index/indices of the specified channel(s) in channel_labels.

If channel is a list, this function is called recursively on each element.

Parameters:

channel_labels (list) – list of channel labels that define the index.
channels (str or int or list) – (list of) label(s) of the channel(s) to get the index of.

Returns:

idx (int or list) – (list of) index/indices corresponding to the specified channel(s).

nnsa.feature_extraction.common.local_to_global_features(features, segment_start_times, segment_end_times, sleep_stages=None, aggregate_segments=<function aggregate_segment_features>, aggregate_channels=<function aggregate_channel_features>, channel_labels=None)[source]

Helper function to go from local features (per channel, per segment) to global features.

Optionally returns the aggregate feature values per sleep stage if sleep_stages is given.

Parameters:

features (dict) – dict with local features. Keys are the names of the features. Values are arrays with feature values with dimension corresponding to (channels, segments).
segment_start_times (np.ndarray) – start times of the segments corresponding to the arrays in features.
segment_end_times (np.ndarray) – end times of the segments corresponding to the arrays in features.
sleep_stages (nnsa.SleepStagesResult, optional) – object containing sleep stages result. Used to report global feature values per sleep stage. If None, all data is used (no distinction is made for sleep stage). Defaults to None.
aggregate_segments (function, optional) – function that takes an array of segment features as input and returns one aggregate value. Defaults to nnsa.aggregate_segment_features.
aggregate_channels (function or None, optional) – function that takes an array of channel features and returns one aggregate values. If None, the channels are not aggregated, i.e. the feature values each channel are returned per channel. Defaults to nnsa.aggregate_channel_features.
channel_labels (list or None, optional) – list of strings representing labels corresponding to the first dimension of the arrays in features. Can only be None if aggregate_channels is not None. Defaults to None.

Returns:

global_features (dict) – dictionary containing the feature name and value pairs.

nnsa.feature_extraction.common.prepare_postfix(postfix)[source]

Helper function to prepare a postfix.

Add an underscore if the postfix does not start with it. Returns an empty string if postfix is None.

Parameters:: postfix (str or None) – postfix.
Returns:: postfix (str) – postfix strating with underscore or an empty string if input is None.

nnsa.feature_extraction.common.preprocess_segment(seg, fs, filter_specification=None, artefact_criteria=None, demean=True, preprocess_fun=None)[source]

Preprocess an EEG segment.

Parameters:

seg (np.ndarray) – EEG signal with dimensions (channels, time).
fs (float) – sample frequency.
filter_specification (str, FilterBase or None) – if a string, it is interpreted as a filter_name of a saved filter (see nnsa.filter_saved_filter()). If a FilterBase object, the objects filtfilt() function is used to do the filtering. If None, no filtering is applied to the segment.
artefact_criteria (dict) – parameters for artefact detection, see detect_artefact_signals(). If None, no artefact detection is performed (exclude mask contains only False).
demean (bool, optional) – if True, the mean of the segment is subtracted (per channel). If False, the mean is not subtracted. Defaults to True.
preprocess_fun (function) – function evaluated on seg and fs and outputting processed seg.

Returns:

seg (np.ndarray) – processed EEG signal with dimensions (channels, time).
exclude_mask (np.ndarray) – boolean array of shape (n_channels, ) where True values correspond to channels to exclude.

nnsa.feature_extraction.common.print_init_message(obj)[source]: Print message when feature extraction algorithm initiates.

nnsa.feature_extraction.connectivity module

Algorithms for extraction of connectivity features.

Classes:

`CoherenceGraph`(**kwargs)	Class for computing a connectivity graph of multi-channel EEG based on coherence.
`CoherenceGraphResult`(mean_coh, im_coh, ...)	High-level interface for processing the results of a coherence analysis as created by nnsa.CoherenceGraph().

Functions:

`compute_average_path_length`(con_matrix, ...)	Compute the average path length of connectivity matrix.
`compute_dist_matrix`(adj_matrix[, weighted])	Compute the matrix containing the shortest paths between nodes in the graph with given adjacency matrix.
`draw_graph`(G)

class nnsa.feature_extraction.connectivity.CoherenceGraph(**kwargs)[source]

Bases: ClassWithParameters

Class for computing a connectivity graph of multi-channel EEG based on coherence.

References

This code was partly ported from Mario Lavanga and Ofelie de Wel’s MATLAB code.

@Article{LAVANGA2018,: author = {M Lavanga and O De Wel and A Caicedo and K Jansen and A Dereymaeker and G Naulaers and S Van Huffel}, title = {A brain-age model for preterm infants based on functional connectivity}, journal = {Physiological Measurement}, year = {2018}, volume = {39}, number = {4}, pages = {044006}, month = {apr}, abstract = {Objective: In this study, the development of EEG functional connectivity during early development has been investigated in order to provide a predictive age model for premature infants. Approach: The functional connectivity has been assessed via the coherency function (its imaginary part (ImCoh) and its mean squared magnitude (MSC)), the phase locking value () and the Hilbert–Schimdt dependence (HSD) in a dataset of 30 patients, partially described and employed in previous studies (Koolen et al 2016 Neuroscience 322 298–307; Lavanga et al 2017 Complexity 2017 1–13). Infants’ post-menstrual age (PMA) ranges from 27 to 42 weeks. The topology of the EEG couplings has been investigated via graph-theory indices. Main results: Results show a sharp decrease in ImCoh indices in θ, (4–8) Hz and α, (8–16) Hz bands and MSC in β, (16–32) Hz band with maturation, while a more modest positive correlation with PMA is found for HSD, and MSC in , θ, α bands. The best performances for the PMA prediction were mean absolute error equal to 1.51 weeks and adjusted coefficient of determination equal to 0.8. Significance: The reported findings suggest a segregation of the cortex connectivity, which favours a diffused tasks architecture on the brain scalp. In summary, the results indicate that the neonates’ brain development can be described via lagged-interaction network features.}, doi = {10.1088/1361-6579/aabac4}, file = {:LAVANGA2018 - A Brain Age Model for Preterm Infants Based on Functional Connectivity.pdf:PDF}, publisher = {{IOP} Publishing}, url = {https://doi.org/10.1088%2F1361-6579%2Faabac4},

}

Main method: coherence_graph()

Examples

>>> np.random.seed(0)
>>> x = np.random.rand(8, 10000)
>>> cg = CoherenceGraph()
>>> print(type(cg.parameters).__name__)
Parameters

>>> cg_result = cg.coherence_graph(x, fs=250, verbose=0)
>>> print(type(cg_result).__name__)
CoherenceGraphResult

>>> cg_result.mean_coh['theta'][1, 0, 0]
0.07487598638814418

Methods:

`coherence_graph`(args, *kwargs)	Alias for self.process().
`default_parameters`()	Return the default parameters.
`process`(data_matrix, fs[, channel_labels, ...])	Compute the coherence graph of multichannel data as designed by Mario Lavanga and Ofelie De Wel.

coherence_graph(*args, **kwargs)[source]: Alias for self.process().

static default_parameters()[source]

Return the default parameters.

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

process(data_matrix, fs, channel_labels=None, verbose=1)[source]

Compute the coherence graph of multichannel data as designed by Mario Lavanga and Ofelie De Wel.

Code was ported from MATLAB and constsist of 6 steps: 1) Segmentation 2) Optional filtering 3) Artefact exclusion 4) PSD estimation 5) Computation of coherence in specified frequency bands per segment 6) Averaging the coherence in the specified frequency bands

Parameters:

data_matrix (np.ndarray) – see check_multichannel_data_matrix().
fs (float) – sample frequency of the EEG signals.
channel_labels (list of str, optional) – see check_multichannel_data_matrix().
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(nnsa.CoherenceGraphResult) – object containing the adjacency matrices per frequency band per segment,
where the channels are the nodes.

class nnsa.feature_extraction.connectivity.CoherenceGraphResult(mean_coh, im_coh, algorithm_parameters, channel_labels=None, data_info=None, segment_start_times=None, segment_end_times=None, fs=None)[source]

Bases: ResultBase

High-level interface for processing the results of a coherence analysis as created by nnsa.CoherenceGraph().

Parameters:

mean_coh (dict) – dictionary with frequency band labels as keys and (channels, channels, segments) arrays with channel-wise absolute squared coherence as values.
im_coh (dict) – dictionary with frequency band labels as keys and (channels, channels, segments) arrays with imaginary part of the channel-wise coherence as values.
algorithm_parameters (nnsa.Parameters) – see ResultBase.
channel_labels (list of str, optional) – labels of the channels corresponding to the rows of the values in power. If None, default labels will be created. Default is None.
data_info (str, optional) – see ResultBase.
segment_start_times (np.array, optional) – see ResultBase.
segment_end_times (np.array, optional) – see ResultBase.
fs (flaot, optional) – see ResultBase.

Methods:

`compute_average_coherence`(graph_name)	Compute average coherence value across channels per segment.
`compute_average_path_lengths`(graph_name, ...)	Compute average path lengths of the graphs.
`compute_global_features`(**kwargs)	Compute global features.
`extract_global_features`([sleep_stages, ...])	Extract features that characterize the entire recording.
`plot`(which)	Plot abs(mean_coh), abs(im_coh) and binary im_coh graph (averaged over segments) in the current figure.

Attributes:

num_segments

Return the number of segments.

compute_average_coherence(graph_name)[source]

Compute average coherence value across channels per segment.

Parameters:: graph_name (str) – see self._get_graphs().
Returns:: averages (dict) – average coherence values of graphs per frequency band per segment. The items in the dict correspond to the frequency bands. The arrays in the dict are 1D with the dimension corresponding to the segments.

compute_average_path_lengths(graph_name, graph_type)[source]

Compute average path lengths of the graphs.

Parameters:

graph_name (str) – name of the graphs to analyze: ‘mean_coh’ or ‘im_coh’.
graph_type (str) – see compute_average_path_length().

Returns:

path_lengths (dict) – average path lengths of graphs per frequency band per segment. The items in the dict correspond to the frequency bands. The arrays in the dict are 1D with the dimension corresponding to the segments.

compute_global_features(**kwargs)[source]

Compute global features.

Parameters:: **kwargs (optional) – keyword arguments for pd.DataFrame.
Returns:: df (pd.DataFrame) – dataframe with one row, and feature values in columns.

extract_global_features(sleep_stages=None, aggregate_segments=<function aggregate_segment_features>)[source]

Extract features that characterize the entire recording.

Parameters:

sleep_stages (nnsa.SleepStagesResult) – object containing sleep stages result. Used to report global feature values per sleep stage. If None, no sleep stage dependent feature values are returned. Defaults to None.
aggregate_segments (function, optional) – function that takes an array of segment features as input and returns one aggregate value. Note: this function may be feeded np.nan values. Defaults to nnsa.aggregate_segment_features.

Returns:

global_features (dict) – dictionary containing the feature name and value pairs.

property num_segments

Return the number of segments.

Returns:: (int) – number of segments.

plot(which)[source]

Plot abs(mean_coh), abs(im_coh) and binary im_coh graph (averaged over segments) in the current figure.

Parameters:: which (str) – which result to plot. Should be one of the keys in self.mean_coh and self.im_coh dicts.

nnsa.feature_extraction.connectivity.compute_average_path_length(con_matrix, graph_type)[source]

Compute the average path length of connectivity matrix.

Parameters:

con_matrix (np.ndarray) – connectivity matrix.
graph_type (str) – specify type of graph: ‘functional’, ‘effective’, ‘binary’.

Returns:

path_length (float) – average path length.

Notes

For ‘functional’ graph_type, the weights in the connectivity matrix are inverted, i.e. w -> 1/w. For ‘binary’ graph_type, positive weights are converted to ones and zero and negative weights to zero.

nnsa.feature_extraction.connectivity.compute_dist_matrix(adj_matrix, weighted=True)[source]

Compute the matrix containing the shortest paths between nodes in the graph with given adjacency matrix.

Parameters:

adj_matrix (np.ndarray) – adjacency matrix of the graph.
weighted (bool) – if True, use the Dijkstra algorithm for a weighted graph. If False, use the breath-first search algorithm for an unweighted graph. Defaults to True.

Returns:

dist_matrix (np.ndarray) – distance matrix of the graph (same shape as adj_matrix).

Notes

Distances between disconnected nodes are set to Inf. Distances on the main diagonal are 0.

nnsa.feature_extraction.connectivity.draw_graph(G)[source]

nnsa.feature_extraction.correlation module

Functions:

delay_correlation(x, y, delays)

Compute the correlation between signals x and y, for specifc delays of x wrt y.

nnsa.feature_extraction.correlation.delay_correlation(x, y, delays)[source]

Compute the correlation between signals x and y, for specifc delays of x wrt y.

Does not include zero-padding, instead cuts off a piece of the signals to apply the delay. For each delay, the same part of x is used.

Ignores nan values.

Parameters:

x (array-like) – 1D array.
y (array-like) – 1D array.
delays (array-like) – 1D array with delays to apply.

Returns:

corr (np.ndarray) – correlation values corresponding to delays.

Examples

>>> t = np.linspace(6, 100)
>>> x = np.sin(t)
>>> y = np.sin(t)
>>> delays = np.arange(-15, 8)
>>> corr = delay_correlation(x, y, delays)
>>> best_delay = delays[np.argmax(corr)]
>>> print(best_delay)
0

nnsa.feature_extraction.discontinuity module

Algorithms related to analysis of discontinuity of the EEG.

Classes:

`BurstDetection`(**kwargs)	Class for burst detection.
`BurstDetectionResult`(bursts, ibis, ...[, ...])	High-level interface for processing the results of burst detection analysis as created by nnsa.BurstDetection().
`IbiFeaturesResult`(df, args, *kwargs)	High-level interface for processing IbiFeatures.
`SuppressionCurve`(suppression, window_length)	High-level object containing the suppression curve (Dereymaeker et al. 2015).

class nnsa.feature_extraction.discontinuity.BurstDetection(**kwargs)[source]

Bases: ClassWithParameters

Class for burst detection.

Main method: burst_detection().

Parameters:: nnsa.ClassWithParameters. (see) –

Examples

>>> np.random.seed(0)
>>> x = np.random.rand(10, 100000)
>>> bd = BurstDetection()
>>> print(type(bd.parameters).__name__)
Parameters

>>> result = bd.burst_detection(x, fs=256, verbose=0)
>>> print(type(result).__name__)
BurstDetectionResult

>>> result.bursts[0, 20000]
0.0

Methods:

`burst_detection`(data_matrix, fs[, ...])	Perform burst detection on multichannel data.
`default_parameters`()	Return the default parameters.
`dibi_burst_detection`(data_matrix, fs[, verbose])	Burst detection method as proposed by Vladimir Matic.
`envelope_burst_detection`(data_matrix, fs[, ...])	Detect bursts using the signal envelope (signal energy).
`line_length_burst_detection`(data_matrix, fs)	Detect bursts using the line length as introduced by Koolen et al.
`nleo_burst_detection`(data_matrix, fs[, lc, ...])	Detect bursts using the non-linear energy operator (NLEO) as introduced by Palmu et al.
`otoole_burst_detection`(data_matrix, fs[, ...])	Burst detection method as implemented by O'Toole in MATLAB.

burst_detection(data_matrix, fs, channel_labels=None, verbose=1)[source]

Perform burst detection on multichannel data.

Parameters:

data_matrix (np.ndarray) – EEG data. See check_multichannel_data_matrix(). The data might be filtered before, depending on the method for burst detection. Most methods, do their own specific filtering. See the documentation and code of the specific methods.
fs (float) – sample frequency of the EEG signals.
channel_labels (list of str, optional) – see check_multichannel_data_matrix().
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(nnsa.BurstDetectionResult) – object containing the burst detection result per channel.

static default_parameters()[source]

Return the default parameters.

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

static dibi_burst_detection(data_matrix, fs, verbose=1)[source]

Burst detection method as proposed by Vladimir Matic.

See detect_dibi() for details.

Parameters:

data_matrix (np.ndarray) – unfiltered EEG data, see check_multichannel_data_matrix().
fs (float) – sample frequency of the EEG signals.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

bursts (np.ndarray) – array with dimensions (1, time) containing 1s at locations of bursts and 0s at locations of non-bursts.
ibis (np.ndarray) – array with dimensions (1, time) containing 1s at locations of inter-burst-intervals (IBIs) and 0s at locations of non-IBIs.

static envelope_burst_detection(data_matrix, fs, lc=0.5, hc=32, notch=50, amplitude_thr_high=30, channel_thr_high=2, min_ibi_dur=1, max_burst_dur=20, amplitude_thr_low=30, channel_thr_low=None)[source]

Detect bursts using the signal envelope (signal energy).

Implementation of the algorithm described by Jennekens et al. 2011.

Notes

The default parameters are the optimal values according to the papaer by Jennekens et al. 2011.

References

Jennekens W , Ruijs LS , Lommen CML , Niemarkt HJ , Pasman JW , van Kranen–Mastenbroek VM , et al. Automatic burst detection for the EEG of the preterm infant. Physiol Meas 2011;32(10):1623–37 .

Parameters:

data_matrix (np.ndarray) – unfiltered EEG data (in uV), see check_multichannel_data_matrix().
fs (float) – sample frequency of the EEG signals.
lc (float, optional) – low cut-off filter frequency (LC) in Hz. Defaults to 0.5.
hc (float, optional) – high cut-off filter frequency (HC) in Hz. Defaults to 32.
notch (float, optional) – notch filter frequency in Hz. Defaults to 50.
amplitude_thr_high (float, optional) – amplitude-threshold-high in uV (ATH). Sample points with an envelope value equal to or above ATH are considered high-voltage activity. Defaults to 30.
channel_thr_high (int, optional) – channel-threshold-high (CTH). If the number of channels with high voltage is >= CTH, the global EEG-activity is considered as high-voltage activity. Defaults to 2.
min_ibi_dur (float, optional) – the minimum separation between 2 bursts in seconds. If two detected periods of high-voltage activity appear within min_ibi_dur after each other it is assumed that they belong together and form one period. Defaults to 1.
max_burst_dur (float, optional) – the maximum duration of bursts in seconds. High-voltage periods >=max_burst_dur are classified as continuous patterns while periods < max_burst_dur are classified as bursts. Defaults to 20.
amplitude_thr_low (float, optional) – amplitude-threshold low in uV (ATL). If the envelope value is lower than the ATL, the corresponding sample is a candidate for IBI. Defaults to 30.
channel_thr_low (int, optional) – channel-threshold-low (CTL). The minimum number of channels with low voltage activity for the sample to be considered an IBI. If None, the total number of channels in the input data_matrix is used. Defaults to None.

Returns:

bursts (np.ndarray) – array with dimensions (1, time) containing 1s at locations of bursts and 0s at locations of non-bursts.
ibis (np.ndarray) – array with dimensions (1, time) containing 1s at locations of inter-burst-intervals (IBIs) and 0s at locations of non-IBIs.

static line_length_burst_detection(data_matrix, fs, F_1=0.85, F_2=0.4, threshold_window=None, min_ibi_dur=2, min_burst_amp=30, verbose=1, **line_length_kwargs)[source]

Detect bursts using the line length as introduced by Koolen et al.

Notes

The default parameters are the optimal values according to the paper by Koolen et al. 2014. In that paper, the algorithm was optimized for unipolar multi-channel EEG sampled at 250 Hz. If the given signals have a different sample frequency, the signals are resampled to 250 Hz.

The postprocessing that checks whether the high energy parts are valid bursts is a bit simpler than mentioned in the paper and also differs from the original Matlab code. In this code, high energy periods (candidates for bursts) are considered burst only if they contain a (normalized) line length value higher than some threshold (controlled by F_2 parameter) AND a high voltage ampltiude in any channel of the original signal (controlled by min_burst_amp parameter). More specifically for this first criterion: the median normalized line length (me_LL) in a high energy period must reach at least F_1*mean(me_LL) + F_2*std(me_LL) to be a burst (in Koolen et al., this is referred to as a ‘pronounced peak’).

References

Koolen, N. et al. Line length as a robust method to detect high-activity events: Automated burst detection in premature EEG recordings. Clinical Neurophysiology 125, 1985{1994 (2014).

Parameters:

data_matrix (np.ndarray) – (filtered) EEG data, see check_multichannel_data_matrix(). Koolen et al. originally used EEG signals bandpass filtered between 1 - 20 Hz.
fs (float) – sample frequency of the EEG signals. Must be 250 Hz or higher.
F_1 (float, optional) – scale factor for the burst detection (F in Eq. 4 of the paper). Defaults to 0.85.
F_2 (float, optional) – scale factor for the standard deviation (used to detect pronounced peaks in me_LL). Defaults to 0.40.
threshold_window (float, optional) – window for the adaptive threshold in seconds. The threshold is adapted in periods of threshold_window seconds, using a moving average of the given window size. If set to None, the threshold is fixed for the entire signal. Defaults to None.
min_ibi_dur (float, optional) – the minimum separation between 2 bursts in seconds. If two detected periods of high-voltage activity appear within min_ibi_dur after each other it is assumed that they belong together and form one burst period. Defaults to 2.
min_burst_amp (float, optional) – the minimum maximum EEG amplitude of a high energy period to be considered a burst. Defaults to 30.
verbose (int, optional) – verbose level. Defaults to 1.
**line_length_kwargs (optional) – keyword arguments with parameters for nnsa.LineLength(**line_length_kwargs). See nnsa.LineLength().

Returns:

bursts (np.ndarray) – array containing 1s at locations of bursts and 0s at locations of non-bursts.
ibis (np.ndarray) – array containing 1s at locations of inter-burst-intervals (IBIs) and 0s at locations of non-IBIs.
fs_LL (float) – sample frequency of corresponding to the output arrays.

static nleo_burst_detection(data_matrix, fs, lc=0.5, hc=10, max_ripple=1, min_attenuation=40, window_avg=1.5, window_baseline=60, sat_thr=1.5, min_duration=1, verbose=1)[source]

Detect bursts using the non-linear energy operator (NLEO) as introduced by Palmu et al.

Notes

The default parameters are the optimal values according to the papaer by Palmu et al. 2010. Here, the NLEO algorithm was optimized for the P3-P4 bipolar channel, using data sampled at 256 Hz. However, since the first step of the algorithm is bandpass filtering between 0.5-10 Hz, sampling frequencies >= 25 Hz are accepted. Then after filtering, the signal is upsampled to 256 Hz.

References

Palmu K , Stevenson N , Wikström S , Hellström-Westas L , Vanhatalo S , Palva JM . Optimization of an NLEO-based algorithm for automated detec- tion of spontaneous activity transients in early preterm EEG. Physiol Meas 2010;31(11):N85–93 .

Parameters:

data_matrix (np.ndarray) – unfiltered EEG data (in uV), see check_multichannel_data_matrix().
fs (float) – sample frequency of the EEG signals.
lc (float, optional) – low cut-off filter frequency (LC) in Hz. Defaults to 0.5.
hc (float, optional) – high cut-off filter frequency (HC) in Hz. Defaults to 10.
max_ripple (float, optional) – max ripple in dB for the low pass elliptic filter, see scipy.signal.ellip(). Note that this value was not mentioned in the paper. Defaults to 1.
min_attenuation (float, optional) – min attenuation in dB for the low pass elliptic filter, see scipy.signal.ellip(). Note that this value was not mentioned in the paper. Defaults to 40.
window_avg (float, optional) – window in seconds for averaging the absolute value of the NLEO output (g). Defaults to 1.5.
window_baseline (float, optional) – window in seconds for finding the baseline value (the minimum value in this window is the baseline value, which is subtracted). Defaults to 60.
sat_thr (float, optional) – threshold on x_nleo (in uV^2) for detection of bursts. Defaults to 1.5.
min_duration (float, optional) – minimum duration of bursts in seconds. Defaults to 1.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

bursts (np.ndarray) – array containing 1s at locations of bursts and 0s at locations of non-bursts.
ibis (np.ndarray) – array containing 1s at locations of inter-burst-intervals (IBIs) and 0s at locations of non-IBIs.
fs (float) – sample frequency of corresponding to the output arrays.

static otoole_burst_detection(data_matrix, fs, verbose=1)[source]

Burst detection method as implemented by O’Toole in MATLAB.

Notes

This method was developed for the following bipolar montgage: F3-C3, F4-C4, C3-O1, C4-O2, C3-T3, C4-T4, Cz-C3, and C4-Cz.

References

JM O’ Toole, GB Boylan, RO Lloyd, RM Goulding, S Vanhatalo, and NJ Stevenson, “Detecting Bursts in the EEG of Very and Extremely Premature Infants Using a Multi-Feature Approach”, Medical Engineering and Physics, vol. 45, pp. 42–50, 2017. DOI:10.1016/j.medengphy.2017.04.003

https://github.com/otoolej/burst_detector

Notes

The algorithm was developed with EEG data using the bipolar montage F4-C4, C4-O2, F3- C3, C3-O1, T4-C4, C4-Cz, Cz-C3, and C3-T3. Therefore, the input of this algorithm should be EEG data from one of these bipolar channels.

The parameters of this algorithm are hardcoded in the bd_parameters.m file (in the nnsa/matlab/burst_detector directory).

Parameters:

data_matrix (np.ndarray) – unfiltered EEG data (bipolar), see check_multichannel_data_matrix().
fs (float) – sample frequency of the EEG signals.
verbose (int, optional) – verbose level. Defaults to 1.
TODO – pass matlab engine as kwarg.

Returns:

bursts (np.ndarray) – array with the same size as data_matrix containing 1s at locations of bursts and 0s at locations of non-bursts.
ibis (np.ndarray) – array with the same size as data_matrix containing 1s at locations of inter-burst-intervals (IBIs) and 0s at locations of non-IBIs.

class nnsa.feature_extraction.discontinuity.BurstDetectionResult(bursts, ibis, algorithm_parameters, fs, nan_mask=None, channel_labels=None, data_info=None, segment_start_times=None, segment_end_times=None)[source]

Bases: ResultBase

High-level interface for processing the results of burst detection analysis as created by nnsa.BurstDetection().

Parameters:

bursts (np.ndarray) – array with dimensions (channels, time) containing 1s or True at locations of bursts and 0s or False at locations of non-bursts. May also contain np.nan for indicating missing values.
ibis (np.ndarray) – array with dimensions (channels, time) containing 1s or True at locations of inter-burst-intervals (IBIs) and 0s or False at locations of non-IBIs. May also contain np.nan for indicating missing values.
algorithm_parameters (nnsa.Parameters) – see ResultBase.
fs (float) – sample frequency corresponding to the bursts and ibis arrays.
nan_mask (np.array, optional) – boolean array with True at locations of missing values and False at locations without missing values. If not None, this nan_mask is applied to bursts and ibis to set missing values to np.nan. This way, the bursts and ibis arrays can be saved as boolean arrays, even if there are missing values (memory efficient). Must have the same shape as bursts and ibis. Defaults to None.
channel_labels (list of str, optional) – labels of the channels corresponding to the channel dimensions of the arrays. If None, default labels will be created. Defaults to None.
data_info (str, optional) – see ResultBase.
segment_start_times (np.ndarray, optional) – see ResultBase.
segment_end_times (np.ndarray, optional) – see ResultBase.

Methods:

`aggregate_bursts`([min_channels_frac, ...])	Combine the burst detection of all channels to get an aggregate, global brust detection array.
`aggregate_ibis`([min_channels_frac, ...])	Combine the IBI detection of all channels to get an aggregate, global IBI detection array.
`class_numbers`()	Return a 1D array with 2s at locations of bursts, 1s at IBIs and np.nan elsewhere.
`compute_event_durations`(detected, fs)	Compute the durations of events in detected.
`compute_event_occurrences`(detected)	Compute the number of occurences in detected.
`compute_event_percentage`(detected)	Compute the time-percentage of detected events.
`compute_features`(bursts, ibis, channel_labels)	Compute burst/IBI features for each channel.
`compute_global_features`(**kwargs)	Compute global features.
`compute_global_features_per_sleep_stage`(...)	Compute global features in specific sleep stages.
`extract_epoch`([begin, end, inplace])	TODO :param begin: in seconds.
`extract_global_features`([...])	Extract features that characterize the entire recording.
`plot`()	Plot the occurence of bursts/ibis as a function of time.
`shade_axis`(*args[, channel])	Shade the current axis based on bursts and IBIs.
`to_aggregate_result`()	Compute the aggregate result by combining the burst detection of all channels.
`to_annotation_set`([channel])	Convert to AnnotationSet object.

Attributes:

`burst_id`	Return the class number for bursts.
`burst_label`	Return the class label for bursts.
`class_labels`	Return the class labels corresponding to self.class_numbers().
`duration`	Return the total duration of the recorded samples.
`ibi_id`	Return the class number for ibis.
`ibi_label`	Return the class label for ibis.
`num_segments`	Return the number of segments (number of samples).

aggregate_bursts(min_channels_frac=0.25, min_channels_elong_frac=0.125)[source]

Combine the burst detection of all channels to get an aggregate, global brust detection array.

Parameters:

min_channels_frac (int, optional) – minimum fraction of channels that must detect a burst in order to consider it a global burst (after aggregation). See aggregate_channel_events(). Defaults to 2/8.
min_channels_elong_frac (int, optional) – minimum fraction of channels that must detect a burst when elongating the globally detected bursts. See aggregate_channel_events(). Defaults to 1/8.

Returns:

bursts (np.ndarray); array with dimensions corresponding to (1, time) – time instants where bursts occur.

aggregate_ibis(min_channels_frac=1, min_channels_elong_frac=1)[source]

Combine the IBI detection of all channels to get an aggregate, global IBI detection array.

Parameters:

min_channels_frac (int, optional) – minimum fraction of channels that must detect an IBI in order to consider it a global IBI (after aggregation). See aggregate_channel_events(). Defaults to 1.
min_channels_elong_frac (int, optional) – minimum fraction of channels that must detect an IBI when elongating the globally detected IBIs. See aggregate_channel_events(). Defaults to 1.

Returns:

ibis (np.ndarray); array with dimensions corresponding to (1, time) – time instants where IBIs occur.

property burst_id

Return the class number for bursts.

Returns:: (int) – class number for bursts.

property burst_label

Return the class label for bursts.

Returns:: (str) – class label for bursts.

property class_labels

Return the class labels corresponding to self.class_numbers().

Returns:: class_labels (dict) – dictionary that maps a class number to a class label.

class_numbers()[source]

Return a 1D array with 2s at locations of bursts, 1s at IBIs and np.nan elsewhere.

Returns:: class_numbers (np.ndarray) – 1D array with same shape as self.bursts and self.ibis. 2s in the array correspond to bursts, 1s to IBIs.

static compute_event_durations(detected, fs)[source]

Compute the durations of events in detected.

Ignores incomplete events (events surrounded by nans).

Parameters:

detected (np.ndarray) – 2D array with 1s (detected) and 0s (not-detected). Dimensions correspond to (channels, time).
fs (float) – sample frequency of detected in Hz.

Returns:

out (tuple) – tuple of arrays with the durations of the detected events in seconds (per channel).

Examples

>>> BurstDetectionResult.compute_event_durations(np.array([[1, 1, 1, 0, 0, 1, 1, 0]]), fs=1)
(array([2.]),)
>>> BurstDetectionResult.compute_event_durations(np.array([[0, 1, 1, 1, 0, 1, 1, 0]]), fs=1)
(array([3., 2.]),)
>>> BurstDetectionResult.compute_event_durations(np.array([[1, 1, 1, 0, 0, np.nan, np.nan]]), fs=1)
(array([0]),)
>>> BurstDetectionResult.compute_event_durations(np.array([[np.nan, 1, 1, 0, 0, np.nan, np.nan]]), fs=1)
(array([0]),)
>>> BurstDetectionResult.compute_event_durations(np.array([[np.nan, 0, 1, 1, 1, 0]]), fs=1)
(array([3.]),)
>>> BurstDetectionResult.compute_event_durations(np.array([[np.nan, 0, 1, np.nan, 1, 0]]), fs=1)
(array([0]),)

static compute_event_occurrences(detected)[source]

Compute the number of occurences in detected.

Counts the number of onsets.

Handles np.nan values by substituting them by zeros using np.nan_to_num().

Parameters:: detected (np.ndarray) – array with 1s (detected) and 0s (not-detected). The last dimension corresponds to the time dimension. E.g. bursts array.
Returns:: num_events (int or np.ndarray) – the number of detected events (per channel).

static compute_event_percentage(detected)[source]

Compute the time-percentage of detected events.

Ignores nan values.

Parameters:: detected (np.ndarray) – array with 1s (detected) and 0s (not-detected). The last dimension corresponds to the time dimension. E.g. bursts array.
Returns:: (float or np.ndarray) – percentage of detected events (per channel).

compute_features(bursts, ibis, channel_labels, postfix=None)[source]

Compute burst/IBI features for each channel.

Parameters:

bursts (np.ndarray) – array with dimensions (channels, time) containing 1s at locations of bursts and 0s at locations of non-bursts. May also contain np.nan for indicating missing values.
ibis (np.ndarray) – array with dimensions (channels, time) containing 1sat locations of inter-burst-intervals (IBIs) and 0s at locations of non-IBIs. May also contain np.nan for indicating missing values.
channel_labels (list) – list with the same length as bursts and ibis containing the labels of the channels (the first dimension of the arrays). May also be a string in case of only one channel.
postfix (string, optional) – optional postfix to add to the feature name in the output dictionary.

Returns:

features (dict) – dictionary of features values, hashed by feature name. Each channel is treated as a separate feature.

compute_global_features(**kwargs)[source]

Compute global features.

Parameters:: **kwargs (optional) – keyword arguments for pd.DataFrame.
Returns:: df (pd.DataFrame) – dataframe with one row, and feature values in columns.

compute_global_features_per_sleep_stage(sleep_stages_result, sleep_labels=None, line_length_result=None, **kwargs)[source]

Compute global features in specific sleep stages.

Parameters:

sleep_stages_result –
sleep_labels –
line_length_result (nnse.LineLengthResult, optional) – if given, the features in the 10 most suppressed period are computed additionally.
**kwargs (optional) – kwargs for self.compute_global_features().

Returns:

property duration

Return the total duration of the recorded samples.

Ignores nans.

Returns:: (float) – duration in seconds.

extract_epoch(begin=0, end=None, inplace=False)[source]

TODO :param begin: in seconds. :param end: in seconds. :param inplace:

Returns:

extract_global_features(aggregate_channels=True, sleep_stages=None, line_length=None)[source]

Extract features that characterize the entire recording.

Parameters:

aggregate_channels (bool, optional) – if True, returns features after aggragating the channels (AGG), if False, returns features for each channel. Defaults to True.
sleep_stages (nnsa.SleepStagesResult, optional) – object containing sleep stages result. Used to report global feature values per sleep stage. If None, all data is used (no distinction is made for sleep stages). Defaults to None.
line_length (nnsa.LineLengthResult, optional) – object containing line length result. If given, additional features are computed in the most suppressed period (10 minutes) according to the suppression curve, derived from the line length. Defaults to None.

Returns:

global_features (dict) – dictionary of features values, hashed by feature name.

property ibi_id

Return the class number for ibis.

Returns:: (int) – class number for ibis.

property ibi_label

Return the class label for ibis.

Returns:: (str) – class label for ibis.

property num_segments

Return the number of segments (number of samples).

Returns:: (int) – number of segments/samples.

plot()[source]

Plot the occurence of bursts/ibis as a function of time.

TODO Option to plot one channel only or to plot the aggregate.

shade_axis(*args, channel=None, **kwargs)[source]

Shade the current axis based on bursts and IBIs.

Wrapper that converts this class to an AnnotationSet and calls shade_axis() from AnnatationSet.

Parameters:

*args (optional) – see nnsa.AnnotationSet.shade_axis().
channel (str, optional) – see self.to_annotation_set().
**kwargs (optional) – see nnsa.AnnotationSet.shade_axis().

to_aggregate_result()[source]

Compute the aggregate result by combining the burst detection of all channels.

Returns:: (nnsa.BurstDetectionResult) – a new burst detection result object, with only one channel (AGG), which is an aggregate of all channels.

to_annotation_set(channel=None)[source]

Convert to AnnotationSet object.

Parameters:: channel (str) – the channel label for which to return an AnnotationSet. If None, an aggregate burst detection, combining all channels will be converted to an AnnotationSet. Defaults to None.
Returns:: (nnsa.AnnotationSet) – AnnotationSet containing self.burst_label and self.ibi_label annotations.

class nnsa.feature_extraction.discontinuity.IbiFeaturesResult(df, *args, **kwargs)[source]

Bases: ResultBase

High-level interface for processing IbiFeatures.

Parameters:: df (pd.DataFrame) – dataframe with IBI features (onset, duration, amplitude, …).

Methods:

`compute_eeg_grade`([window, overlap])	Compute EEG grade according to Dereymaeker et al. 2019.
`compute_ibi_percentage`([window, overlap])	Compute IBI time percentage in specific time windows.
`compute_median_in_window`([start, stop, ...])	Compute median feature value in specified time windows.

compute_eeg_grade(window=3600, overlap=0)[source]

Compute EEG grade according to Dereymaeker et al. 2019.

Returns the time as median of the onset times of the IBIs in the window.

Parameters:

window (float) – time window (in seconds).
overlap (float) – overlap between windows (in seconds).

Returns:

grade (pd.Series) – Series with the EEG grades and with onset as index.

compute_ibi_percentage(window=3600, overlap=0)[source]

Compute IBI time percentage in specific time windows.

Returns the time as median of the onset times of the IBIs in the window.

Parameters:

window (float) – time window (in seconds).
overlap (float) – overlap between windows (in seconds).

Returns:

percentage (pd.Series) – Series with the IBI percentage and with onset as index.

compute_median_in_window(start=None, stop=None, window=3600, overlap=0, features=None)[source]

Compute median feature value in specified time windows.

Returns the index as end time of the window.

Parameters:

start (float) – start time in seconds. If None, starts at the onset of first dIBI.
stop (float) – stop time in seconds.
window (float) – time window (in seconds).
overlap (float) – overlap between windows (in seconds).
features (list) – list of feature names for which to compute the running medians. If None, processes all features.

Returns:

df_median (pd.DataFrame) – DataFrame with onset as index and features as columns, which contain median values per window.

class nnsa.feature_extraction.discontinuity.SuppressionCurve(suppression, window_length, label='Suppresion curve', time_offset=0, **kwargs)[source]

Bases: TimeSeries

High-level object containing the suppression curve (Dereymaeker et al. 2015).

References

A. Dereymaeker, N. Koolen, K. Jansen, J. Vervisch, E. Ortibus, M. De Vos, S. Van Huffel, G. Naulaers, The suppression curve as a quantitative approach for measuring brain maturation in preterm infants, Clinical Neurophysiology, Volume 127, Issue 8, 2016, Pages 2760-2765,

Parameters:

suppression (np.ndarray) – 1D array containing the suppression values as function of time.
window_length (float) – the window length corresponding to one sample in suppression. I.e. the length of the window in which the suppression value was computed in seconds.

Methods:

get_most_suppressed_period([period_length])

Get the start and end time of the most suppressed period.

get_most_suppressed_period(period_length=600)[source]

Get the start and end time of the most suppressed period.

Parameters:

period_length (flaot) – length of the suppressed period to extract (in seconds). Choose a multiple of self.window_length.

Returns:

start_time (float) – time (in seconds) of the beginning of the suppressed period.
stop_time (float) – time (in seconds) of the end of the suppressed period.

nnsa.feature_extraction.dynamic_coupling module

Module for general dynamic coupling results (i.e. coupling as function of time).

Classes:

`DynamicCoupling`(**kwargs)	Class for computing the dynamic coupling between two signals.
`DynamicCouplingResult`(coupling, ...[, ...])	High-level interface for processing dynamic coupling as computed by nnsa.DynamicCoupling().

class nnsa.feature_extraction.dynamic_coupling.DynamicCoupling(**kwargs)[source]

Bases: ClassWithParameters

Class for computing the dynamic coupling between two signals.

Main mehtod: dynamic_coupling().

Parameters:: nnsa.ClassWithParameters. (see) –

Examples

>>> t = np.linspace(0, 10, 200)
>>> x = np.sin(t)
>>> y = np.sin(t)
>>> dc = DynamicCoupling(segmentation={'segment_length': 50, 'overlap': 40}, method='correlation')
>>> result = dc.dynamic_coupling(x, y, fs=1, verbose=0)
>>> print(type(result).__name__)
DynamicCouplingResult

>>> result.coupling.shape
(16,)

>>> np.mean(result.coupling)
1.0

Methods:

`coherence_dynamic_coupling`(x, y, fs[, ...])	Compute coherence between x and y in a windowed way.
`correlation_dynamic_coupling`(x, y, fs[, ...])	Compute correlation between x and y in a windowed way.
`default_parameters`()	Return the default parameters.
`dynamic_coupling`(args, *kwargs)	Alias for self.process().
`process`(x, y, fs[, label, verbose])	Compute dynamic coupling between x and y.
`tf_dynamic_coupling`(x, y, fs[, f_low, ...])	Compute transfer function gain between x and y in a windowed way.
`wbtf_dynamic_coupling`(x, y, fs[, verbose])	Compute coherence between x and y in a windowed way.

coherence_dynamic_coupling(x, y, fs, f_low=0, f_high=None, verbose=1, window='hann', nperseg=None, noverlap=None, nfft=None, detrend='constant', **kwargs)[source]

Compute coherence between x and y in a windowed way.

Parameters:

x (np.ndarray) – 1D signal array.
y (np.ndarray) – 1D signal array.
fs (float) – sample frequency of x and y.
f_low (float, optional) – frequency specifying the low edge frequency of the band in which to compute the average coherence. Defaults to 0.
f_high (float, optional) – frequency specifying the high edge frequency of the band in which to compute the average coherence. If None, this will be the Nyqvist frequency, i.e. fs/2. Defaults to None.
verbose (int, optional) – verbose level. Defaults to 1.
other (See documentation of scipy.signal.coherence function for) –
**kwargs – for scipy.signal.coherence().

Returns:

coupling (np.ndarray) – 1D array with coupling values.
coupling_surrogates (np.ndarray) – coupling values for each surrogate.

correlation_dynamic_coupling(x, y, fs, delays=None, abs_corr=True, verbose=1)[source]

Compute correlation between x and y in a windowed way.

Parameters:

x (np.ndarray) – 1D signal array.
y (np.ndarray) – 1D signal array.
fs (float) – sample frequency of x and y.
delays (np.ndarray, optional) – delays to try to get maximum correlation. If None, no delay is applied. Defaults to None.
abs_corr (bool, optional) – return the absolute value of the correlation (True) or not (False). Defaults to True.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

coupling (np.ndarray) – 1D array with coupling values.
coupling_surrogates (np.ndarray) – coupling values for each surrogate.

static default_parameters()[source]

Return the default parameters.

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

dynamic_coupling(*args, **kwargs)[source]: Alias for self.process().

process(x, y, fs, label=None, verbose=2)[source]

Compute dynamic coupling between x and y.

Parameters:

x (array-like) – 1D signal array.
y (array-like) – 1D signal array.
fs (float) – sample frequency of x and y (x and y must have equal fs).
label (str, optional) – label for the coupling output (e.g. ‘EEG-NIRS’). If None, the method parameter is used as label. Defaults to None.
verbose (int, optional) – verbose level. Set to 1 for a progress bar, 2 for also printing parameters.

Returns:

(nnsa.DynamicCouplingResult) – object containing the result.

tf_dynamic_coupling(x, y, fs, f_low=0, f_high=None, verbose=1, window='hann', nperseg=None, noverlap=None, nfft=None, detrend='constant', **kwargs)[source]

Compute transfer function gain between x and y in a windowed way.

Parameters:

x (np.ndarray) – 1D signal array.
y (np.ndarray) – 1D signal array.
fs (float) – sample frequency of x and y.
f_low (float, optional) – frequency specifying the low edge frequency of the band in which to compute the average coherence. Defaults to 0.
f_high (float, optional) – frequency specifying the high edge frequency of the band in which to compute the average coherence. If None, this will be the Nyqvist frequency, i.e. fs/2. Defaults to None.
verbose (int, optional) – verbose level. Defaults to 1.
other (See documentation of scipy.signal.csd function for) –
**kwargs – for compute_transfer_function().

Returns:

coupling (np.ndarray) – 1D array with coupling values.
coupling_surrogates (np.ndarray) – coupling values for each surrogate.

wbtf_dynamic_coupling(x, y, fs, verbose=1)[source]

Compute coherence between x and y in a windowed way.

Parameters:

x (np.ndarray) – 1D signal array.
y (np.ndarray) – 1D signal array.
fs (float) – sample frequency of x and y.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

coupling (np.ndarray) – 1D array with coupling values.
coupling_surrogates (np.ndarray) – coupling values for each surrogate.

class nnsa.feature_extraction.dynamic_coupling.DynamicCouplingResult(coupling, algorithm_parameters, coupling_surrogates=None, label='coupling', data_info=None, segment_start_times=None, segment_end_times=None, fs=None)[source]

Bases: ResultBase

High-level interface for processing dynamic coupling as computed by nnsa.DynamicCoupling().

Parameters:

coupling (np.ndarray) – 1D array with coupling values with size (n_segments,).
algorithm_parameters (nnsa.Parameters) – see ResultBase.
coupling_surrogates (np.ndarray, optional) – optional surrogate values for the coupling. Can be a 1D array, with shape (n_surrogates,) or a 2D array with shape (n_surrogates, n_segments). If not specified, some methods using surrogate data will raise errors. Defaults to None.
label (str, optional) – label for the coupling output (e.g. ‘EEG-NIRS’). Defaults to ‘coupling’.
data_info (str, optional) – see ResultBase.
segment_start_times (np.ndarray, optional) – see ResultBase.
segment_end_times (np.ndarray, optional) – see ResultBase.
fs (flaot, optional) – see ResultBase.

Methods:

`get_significance`(**kwargs)	Return a TimeSeries with the significance.
`plot`([time_scale, alpha, ax])	"
`plot_significance`(**kwargs)	Plot the significance (if coupling surrogates is available).
`to_time_series`(**kwargs)	Convert result to TimeSeries object.

Attributes:

num_segments

Return the number of segments.

get_significance(**kwargs)[source]

Return a TimeSeries with the significance.

Significance is defined as the fraction of surrogates that have lower coupling values as the real value. Therefore, if the significance is close to 1, the computed coupling can be deemed significant.

Parameters:: **kwargs (optional) – keyword arguments for TimeSeries.
Returns:: ts (TimeSeries) – TimeSeries object containing the significance.

property num_segments

Return the number of segments.

Returns:: (int) – number of segments.

plot(time_scale=None, alpha=0.05, ax=None, **kwargs)[source]

” Plot the coupling (and the surrogate coupling values if available) in the current axes.

Parameters:

time_scale (str) – see format_time_axis().
alpha (float) – significance value for surrogates.
ax (plt.Axes) – axes to plot in.
**kwargs (optional) – keyword arguments for plt.plot() for plotting the coupling values.

plot_significance(**kwargs)[source]

Plot the significance (if coupling surrogates is available).

Parameters:: **kwargs (optional) – keyword arguments for TimeSeries.plot().

to_time_series(**kwargs)[source]

Convert result to TimeSeries object.

Parameters:: **kwargs (optional) – keyword arguments for TimeSeries.
Returns:: ts (TimeSeries) – TimeSeries object containing the coupling.

nnsa.feature_extraction.entropy module

Module containing entropy-related functions and classes.

Classes:

`MultiScaleEntropy`(**kwargs)	Class for performing a multi-scale entropy analysis.
`MultiScaleEntropyResult`(mse, ...[, ...])	High-level interface for processing the results of multi-scale entropy analysis as created by nnsa.MultiScaleEntropy().

Functions:

sample_entropy(x, m, r)

Compute the sample entropy of signal x, given a sequence length m and match tolerance r.

class nnsa.feature_extraction.entropy.MultiScaleEntropy(**kwargs)[source]

Bases: ClassWithParameters

Class for performing a multi-scale entropy analysis.

Reference: this code was ported from Mario Lavanga and Ofelie de Wel’s MATLAB code.

Main method: multi_scale_entropy()

Parameters:: nnsa.ClassWithParameters. (see) –

Examples

>>> np.random.seed(0)
>>> x = np.random.rand(2, 2500)
>>> mse = MultiScaleEntropy()
>>> assert_equal(mse.parameters, MultiScaleEntropy.default_parameters())
>>> print(type(mse.parameters).__name__)
Parameters

>>> mse_result = mse.multi_scale_entropy(x, fs=25, verbose=0)
>>> print(type(mse_result).__name__)
MultiScaleEntropyResult

>>> mse_result.mse[10, 1, 0]
1.0185695809945732

Methods:

`default_parameters`()	Return the default parameters as a dictionary.
`multi_scale_entropy`(data_matrix, fs[, ...])	Perform the multi-scale entropy (MSE) analysis on multichannel data.

static default_parameters()[source]

Return the default parameters as a dictionary.

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

multi_scale_entropy(data_matrix, fs, channel_labels=None, verbose=1)[source]

Perform the multi-scale entropy (MSE) analysis on multichannel data.

Analysis pipeline ported from MATLAB code designed by Ofelie De Wel and Mario Lavanga.

Pipeline constsist of 4 steps: 1) Segmentation 2) Optional filtering 3) Artefact exclusion 4) MSE computation

Parameters:

data_matrix (np.ndarray) – see check_multichannel_data_matrix().
fs (float) – sample frequency of the EEG signals.
channel_labels (list of str, optional) – see check_multichannel_data_matrix().
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(nnsa.MultiScaleEntropyResult) – object containing the MSE result per segment and per channel.

class nnsa.feature_extraction.entropy.MultiScaleEntropyResult(mse, algorithm_parameters, channel_labels=None, data_info=None, segment_start_times=None, segment_end_times=None, fs=None)[source]

Bases: ResultBase

High-level interface for processing the results of multi-scale entropy analysis as created by nnsa.MultiScaleEntropy().

Parameters:

mse (np.ndarray) – array with multi-scale entropy values with dimensions (scales, channels, segments). mse[i] contains the result of scale i+1.
algorithm_parameters (nnsa.Parameters) – see ResultBase.
channel_labels (list of str, optional) – labels of the channels corresponding to the second axis in mse. If None, default labels will be created. Default is None.
data_info (str, optional) – see ResultBase.
segment_start_times (np.ndarray, optional) – see ResultBase.
segment_end_times (np.ndarray, optional) – see ResultBase.
fs (flaot, optional) – see ResultBase.

Attributes:

`average_mse`	Return the mse averaged over all segments.
`num_segments`	Return the number of segments.
`scales`	Return the scales of the mse analysis.

Methods:

`compute_average_slopes`([split])	Compute the average slope of the mse curve in the small and large scales per channel.
`compute_complexity_index`()	Compute the complexity index, i.e. the area under the mse curve, for each segment and each channel.
`extract_channels`(channels[, inplace])
`extract_global_features`(**kwargs)	Extract features that characterize the entire recording.
`maximum_mse`()	Return the maximum value of the multiscale entropy curve.
`plot`([channels, segments, plot_fit, ax])	Average the mse values for all segments and plot the entropy against scale for the specified channels.
`remove_channel`(channels[, inplace])	Remove one or more channels.

property average_mse

Return the mse averaged over all segments.

Returns:

self._average_mse (np.ndarray) – array with dimensions (scales, channels) containing the average sample
entropy values.

compute_average_slopes(split=5)[source]

Compute the average slope of the mse curve in the small and large scales per channel.

Parameters:

split (int, optional) – the scale that divides the scale into small scales (<=split) and large scales (>split). Defaults to 5.

Returns:

slope_small (np.ndarray) – array with dimensions (channels, segments) containing the average slope of the mse curve of scales 1 until split.
slope_large (np.ndarray) – array with dimensions (channels, segments) containing the average slope of the mse curve of scales split until the maximum available scale.

compute_complexity_index()[source]

Compute the complexity index, i.e. the area under the mse curve, for each segment and each channel.

Returns:: (np.ndarray) – array with dimensions (channels, segments) with the complexity indices.

extract_channels(channels, inplace=False)[source]

extract_global_features(**kwargs)[source]

Extract features that characterize the entire recording.

Parameters:: **kwargs (optional) – optional keyword arguments for local_to_global_features().
Returns:: global_features (dict) – see local_to_global_features().

maximum_mse()[source]

Return the maximum value of the multiscale entropy curve.

Returns:: (np.ndarray) – array with dimensions (channels, segments) with the maxima.

property num_segments

Return the number of segments.

Returns:: (int) – number of segments.

plot(channels=None, segments=None, plot_fit=False, ax=None)[source]

Average the mse values for all segments and plot the entropy against scale for the specified channels.

Parameters:

channels (list of str, optional) – a list of labels that specify which channels to plot. Each channel gets its own color in the plot. If None, all channels are plotted. Defaults to None.
segments (list, optional) – iterable with indices of the segments to plot. Each segment is plotted as a separate solid line of a color corresponding to the channel. If None, the average sample entropy values over all segments are plotted per scale. Defaults to None.
plot_fit (bool, optional) – if True, plot the polynomial approximation. Defaults to False.
ax (plt.Axes, optional) – axes to plot in. If None, plots in a new figure. Defaults to None.

remove_channel(channels, inplace=False)[source]

Remove one or more channels.

Parameters:

channels (str or list) – (list of) channel name(s) to remove.
inplace (bool, optional) – bool tos pecify whether it happens in place or not.

Returns:

new MultiScaleEntropyResult object if inplace is False.

property scales

Return the scales of the mse analysis.

Returns:: (np.ndarray) – array with scales corresponding to first axis of self.mse.

nnsa.feature_extraction.entropy.sample_entropy(x, m, r)[source]

Compute the sample entropy of signal x, given a sequence length m and match tolerance r.

Sample entropy is the negative natural logarithm of the probability that two sequences of length m that are similar, are still similar if the length of the sequences is increased by one sample.

Reference: https://www.physiology.org/doi/full/10.1152/ajpheart.2000.278.6.H2039?url_ver=Z39.88-2003&rfr_id=ori:rid:crossref.org&rfr_dat=cr_pub%3dpubmed Richman, J. S. & Moorman, J. R. Physiological time-series analysis using approximate entropy and sample entropy. American Journal of Physiology-Heart and Circulatory Physiology 278, H2039-H2049 (2000).

Parameters:

x (np.ndarray) – 1D array containing the signal to compute the sample entropy of.
m (int) – sequence length.
r (float) – matching tolerance. Seuquences are considered similar if their Chebyshev distance is below r. This is typically 0.1*std(x) or 0.2*std(x).

Returns:

(flaot) – sample entropy of x.

nnsa.feature_extraction.envelope module

Algorithms related to analysis of the envelope/magnitude of the EEG.

Classes:

`Envelope`(**kwargs)	Class for computing the envelope of a real valued signal.
`EnvelopeResult`(envelope, ...[, ...])	High-level interface for processing the results of envelope computation as created by nnsa.Envelope().

Functions:

`hilbert_envelope`(x[, nfft, axis])	Compute the envelope of the signals in x using the Hilbert transform.
`power_envelope`(x[, n_window, axis])	Compute the envelope of the signals in x derived from average signal power in small windows.

class nnsa.feature_extraction.envelope.Envelope(**kwargs)[source]

Bases: ClassWithParameters

Class for computing the envelope of a real valued signal.

Main method: envelope().

Parameters:: nnsa.ClassWithParameters (see) –

Examples

>>> fs = 256
>>> t = 1/fs*np.arange(8*100000).reshape(8, 100000)
>>> x = 4 * np.sin(t)
>>> env = Envelope(method='hilbert')
>>> print(type(env.parameters).__name__)
Parameters

>>> result = env.envelope(x, fs=fs, verbose=0)
>>> print(type(result).__name__)
EnvelopeResult

>>> print(result.envelope[2, 2222])
3.98601719157083

>>> print(result.envelope.mean())
3.997973665767074

Methods:

`default_parameters`()	Return the default parameters.
`envelope`(data_matrix, fs[, channel_labels, ...])	Perform the envelope computation on multichannel data.

static default_parameters()[source]

Return the default parameters.

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

envelope(data_matrix, fs, channel_labels=None, verbose=1)[source]

Perform the envelope computation on multichannel data.

Parameters:

data_matrix (np.ndarray) – see check_multichannel_data_matrix().
fs (float) – sample frequency of the signals in data_matrix.
channel_labels (list of str, optional) – see check_multichannel_data_matrix().
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(nnsa.EnvelopeResult) – object containing the signal envelopes per channel.

class nnsa.feature_extraction.envelope.EnvelopeResult(envelope, algorithm_parameters, fs, channel_labels=None, data_info=None, segment_start_times=None, segment_end_times=None)[source]

Bases: ResultBase

High-level interface for processing the results of envelope computation as created by nnsa.Envelope().

Parameters:

envelope (np.ndarray) – array with shape (channels, segments) containing signal envelopes.
algorithm_parameters (nnsa.Parameters) – see ResultBase.
fs (float) – sample frequency corresponding to the envelope array.
channel_labels (list of str, optional) – labels of the channels corresponding to the channel dimensions of envelope. If None, default labels will be created. Defaults to None.
data_info (str, optional) – see ResultBase.
segment_start_times (np.ndarray, optional) – see ResultBase.
segment_end_times (np.ndarray, optional) – see ResultBase.

Methods:

`baseline_correction_min`([window_length, inplace])	Perform baseline correction of the envelope by subtracting the minimum value in a window before each sample.
`compute_features`(envs[, postfix, ...])	Compute features of an array of envelope values.
`extract_global_features`([max_amplitude, ...])	Extract features that characterize the entire recording.
`plot`([channel])	Plot the envelope in the current axis.
`to_base_dataset`([unit])	Create an BaseDataset object from the envelope data.
`to_eeg_dataset`([unit])	Create an EegDataset object from the envelope data.
`to_time_series`([channel, unit])	Create a TimeSeries object from the envelope data of the specified channel.

Attributes:

num_segments

Return the number of segments (number of samples).

baseline_correction_min(window_length=None, inplace=False)[source]

Perform baseline correction of the envelope by subtracting the minimum value in a window before each sample.

See nnsa.baseline_correction_min().

Parameters:

window_length (int, optional) – the length of the window (in samples) to look for the baseline (minimum), see nnsa.baseline_correction_min(). If None, a window corresponding to 1 minute is used. Defaults to None.
inplace (bool, optional) – if True, the corrected values replace the envelope values in the current object. If False, a new EnvelopeResult object is returned with the baseline corrected envelope values. Defaults to False.

Returns:

envelope_corrected (nnsa.EnvelopeResult) – a new EnvelopeResult object with the baseline corrected envelope values (only if inplace is True).

compute_features(envs, postfix=None, concatenate_channels=True)[source]

Compute features of an array of envelope values.

Parameters:

envs (np.ndarray) – array with envelope values with dimensions (channels, time).
postfix (str, optional) – postfix for the keys in the output dictionary.
concatenate_channels (bool, optional) – if True, the channels are concatenated before computing the features. If False, the features are computed on each channel. Defaults to True.

Returns:

features (dict) – features describing the envelope distribution.

extract_global_features(max_amplitude=200, sleep_stages=None, concatenate_channels=True)[source]

Extract features that characterize the entire recording.

Parameters:

max_amplitude (float, optional) – the threshold for the envelope in uV. Values above this threshold are discarded in the analysis. Defaults to 200.
sleep_stages (nnsa.SleepStagesResult, optional) – object containing sleep stages result. Used to report global feature values per sleep stage. If None, no sleep stage dependent feature values are returned. Defaults to None.
concatenate_channels (bool, optional) – see self.compute_features.

Returns:

global_features (dict) – dictionary of features values, hashed by feature name.

property num_segments

Return the number of segments (number of samples).

Returns:: (int) – number of segments/samples.

plot(channel=None)[source]

Plot the envelope in the current axis.

Parameters:: channel (str or list, optional) – string or list of strings with label(s) of the channel(s) to plot. If None, all channels are plot in the same figure with a separate color. Defaults to None.

to_base_dataset(unit='uV', **kwargs)[source]

Create an BaseDataset object from the envelope data.

Parameters:

unit (str, optional) – unit of the envelope data. Defaults to ‘uV’.
**kwargs (optional) – optional keyword arguments for the TimeSeries object.

Returns:

ds (nnsa.BaseDataset) – BaseDataset containing the envelope data of the available channels.

to_eeg_dataset(unit='uV', **kwargs)[source]

Create an EegDataset object from the envelope data.

Parameters:

unit (str, optional) – unit of the envelope data. Defaults to ‘uV’.
**kwargs (optional) – optional keyword arguments for the TimeSeries object.

Returns:

ds (nnsa.EegDataset) – EegDataset containing the envelope data of the available channels.

to_time_series(channel=None, unit='uV', **kwargs)[source]

Create a TimeSeries object from the envelope data of the specified channel.

Parameters:

channel (str, optional) – the label of the channel which to convert to a TimeSeries. If None and the envelope contains only one channel, this channel is selected. Defaults to None.
unit (str, optional) – unit of the envelope data. Defaults to ‘uV’.
**kwargs (optional) – optional keyword arguments for the TimeSeries object.

Returns:

ts (nnsa.TimeSeries) – TimeSeries containing the envelope data of the specified channel.

nnsa.feature_extraction.envelope.hilbert_envelope(x, nfft=None, axis=-1)[source]

Compute the envelope of the signals in x using the Hilbert transform.

Notes

The envelope may suffer from boundary effects.

Parameters:

x (np.ndarray) – signal data.
nfft (int, optional) – number of Fourier components. If None, uses the next power of 2 from x.shape[axis] for optimal speed. Defaults to None.
axis (int, optional) – the axis along which to compute the envelope. Defaults to -1.

Returns:

envelope (np.ndarray) – array with same shape as x containing the envelopes of the signals in x.

nnsa.feature_extraction.envelope.power_envelope(x, n_window=100, axis=-1)[source]

Compute the envelope of the signals in x derived from average signal power in small windows.

Based on the envelope approximation used by Jennekens et al. 2011.

References

Jennekens W , Ruijs LS , Lommen CML , Niemarkt HJ , Pasman JW , van Kranen–Mastenbroek VM , et al. Automatic burst detection for the EEG of the preterm infant. Physiol Meas 2011;32(10):1623–37 .

Parameters:

x (np.ndarray) – signal data.
n_window (int, optional) – the number of samples in the averaging window. Defaults to 100.
axis (int, optional) – the axis along which to compute the envelope. Defaults to -1.

Returns:

envelope (np.ndarray) – array with same shape as x containing the envelopes of the signals in x.

nnsa.feature_extraction.feature_sets_old module

nnsa.feature_extraction.fractality module

Algorithms related to fractal analysis.

Classes:

`LineLength`(**kwargs)	Class for computing the Line Length (LL) feature.
`LineLengthResult`(line_length, ...[, ...])	High-level interface for processing the results of line length computation as created by nnsa.LineLength().
`MultifractalAnalysis`([eng])	Class for performing a multifractal analysis.
`MultifractalAnalysisResult`(cp, hmin, hmax, ...)	High-level interface for processing the results of multifractal analysis as created by nnsa.MultifractalAnalysis().

Functions:

`buid_q_log`([q_min, q_max, n])	Build a convenient array q for multifractal analysis.
`histogram_features_lll`(line_length[, ...])	Compute the histogram features from the log Line Length distribution.
`wfbmesti`(x[, method, axis, keepdims])	Compute Hurst exponent using the second order discrete derivative as in MATLAB's wfbmesti function.

class nnsa.feature_extraction.fractality.LineLength(**kwargs)[source]

Bases: ClassWithParameters

Class for computing the Line Length (LL) feature.

Reference: Line Length implemented as presented by Koolen et al.:

@Article{KOOLEN2014,: author = {Ninah Koolen and Katrien Jansen and Jan Vervisch and Vladimir Matic and Maarten De Vos and Gunnar Naulaers and Sabine Van Huffel}, title = {Line length as a robust method to detect high-activity events: Automated burst detection in premature {EEG} recordings}, journal = {Clinical Neurophysiology}, year = {2014}, volume = {125}, number = {10}, pages = {1985–1994}, month = {oct}, doi = {10.1016/j.clinph.2014.02.015}, publisher = {Elsevier {BV}},

}

Main method: line_length():

Parameters:: nnsa.ClassWithParameters. (see) –

Examples

>>> np.random.seed(0)
>>> x = np.random.rand(10, 10000)
>>> line_length = LineLength()
>>> print(type(line_length.parameters).__name__)
Parameters

>>> result = line_length.line_length(x, fs=25, verbose=0)
>>> print(type(result).__name__)
LineLengthResult

>>> result.line_length[2, 3]
0.005513363795332106

Methods:

`default_parameters`()	Return the default parameters.
`line_length`(data_matrix, fs[, ...])	Perform the computation of the Line Lenght feature on multichannel data.
`process`(args, *kwargs)	Alias of main method.

static default_parameters()[source]

Return the default parameters.

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

line_length(data_matrix, fs, channel_labels=None, verbose=1)[source]

Perform the computation of the Line Lenght feature on multichannel data.

Parameters:

data_matrix (np.ndarray) – see check_multichannel_data_matrix(). Koolen et al. originally used EEG signals bandpass filtered between 1 - 20 Hz.
fs (float) – sample frequency of the EEG signals. For the line length, the signals should typically be sampled at 250 Hz. If another frequency is used, a warning is raised.
channel_labels (list of str, optional) – see check_multichannel_data_matrix().
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(nnsa.LineLengthResult) – object containing the LL result per segment per channel.

process(*args, **kwargs)[source]: Alias of main method.

class nnsa.feature_extraction.fractality.LineLengthResult(line_length, algorithm_parameters, channel_labels=None, data_info=None, segment_start_times=None, segment_end_times=None, fs=None, **kwargs)[source]

Bases: ResultBase

High-level interface for processing the results of line length computation as created by nnsa.LineLength().

Parameters:

line_length (np.ndarray) – array with shape (channels, segments) containing the (normalized) line lengths.
channel_labels (list of str, optional) – labels of the channels corresponding to the channel dimensions of the arrays. If None, default labels will be created. Defaults to None.
data_info (str, optional) – see ResultBase.
segment_start_times (np.ndarray, optional) – see ResultBase.
segment_end_times (np.ndarray, optional) – see ResultBase.
fs (flaot, optional) – see ResultBase.
**kwargs – for ResultBase.

Methods:

`extract_channels`(channels[, inplace])
`extract_global_features`([...])	Extract features that characterize the entire recording.
`histogram_features`(**kwargs)	Compute the histogram features from the log LL distribution.
`plot`(*args[, channels, time_scale, ...])	Plot the line length as function of time (segments).
`to_suppression_curve`([window_length])	Compute the suppression curve, as derived from the line length (Dereymaeker et al. 2015).
`to_time_series`([channel])

Attributes:

`median_line_length`	Retrun the median of the line lenghts across channels.
`num_segments`	Return the number of segments.

extract_channels(channels, inplace=False)[source]

extract_global_features(aggregate_channels=<function aggregate_channel_features>, sleep_stages=None)[source]

Extract features that characterize the entire recording.

Parameters:

aggregate_channels (function or None, optional) – function that takes an array of channel features and returns one aggregate values. If None, the channels are not aggregated, i.e. the feature values each channel are returned per channel. Defaults to nnsa.aggregate_channel_features.
sleep_stages (nnsa.SleepStagesResult, optional) – object containing sleep stages result. Used to report global feature values per sleep stage. If None, no sleep stage dependent feature values are returned. Defaults to None.

Returns:

global_features (dict) – dictionary containing the feature name and value pairs.

histogram_features(**kwargs)[source]

Compute the histogram features from the log LL distribution.

Wrapper of histogram_features_lll() function.

Parameters:: **kwargs (optional) – keyword arguments for histogram_features_lll().
Returns:: see histogram_features_lll().

property median_line_length

Retrun the median of the line lenghts across channels.

Returns:: (np.ndarray) – median line length per segment..

property num_segments

Return the number of segments.

Returns:: (int) – number of segments.

plot(*args, channels='median', time_scale='seconds', log_transform=False, ax=None, **kwargs)[source]

Plot the line length as function of time (segments).

Parameters:

args (*) – positional arguments for plt.plot.
channels (list of str, optional) – a list of labels that specify which channels to plot. Each channel gets its own color in the plot. if ‘median’, the median line length across channels is plotted. If None, all channels are plotted. Defaults to ‘median’.
time_scale (str, optional) – the time scale to use. Choose from ‘seconds’, ‘minutes’, ‘hours’. Defaults to ‘seconds’.
log_transform (bool, optional) – if True, do a log10 transform on the LL. Defaults to False.
ax (plt.Axes, optional) – axes to plot in. If None, plots in current axes.
**kwargs (optional) – keyword arguments for plt.plot.

to_suppression_curve(window_length=150, **kwargs)[source]

Compute the suppression curve, as derived from the line length (Dereymaeker et al. 2015).

Parameters:

window_length (float) – the window length in seconds for the computation of the suppression curve.
**kwargs (optional) – optional keyword arguments for SuppressionCurve().

Returns:

suppression (np.array) – suppression values, with a sample frequency 1/window_length.

to_time_series(channel='median', **kwargs)[source]

class nnsa.feature_extraction.fractality.MultifractalAnalysis(eng=None, **kwargs)[source]

Bases: ClassWithParameters

Class for performing a multifractal analysis.

References

This code was partly ported from Mario Lavanga and Ofelie de Wel’s MATLAB code and calls some MATLAB functions from the Wavelet p-Leader and Bootstrap based MultiFractal analysis (WLBMF) MATLAB toolbox, described in: H. Wendt, P.Abry, and S.Jaffard, “Bootstrap for Multifractal Analysis” IEEE SignalProcessingMagazine, vol. 24, no. 4, pp. 38–48, 2007.

Main method: multifractal_analysis()

Notes

The following project claims to have implemented the MATLAB toolbox in Python (I did not check it out): https://github.com/omardrwch/mfanalysis/blob/master/mfanalysis/mfa.py

Parameters:

eng (matlab.engine.matlabengine.MatlabEngine, optional) – MATLAB engine to use for calling MATLAB functions. The required paths must already have been initialized (see self.eng()). If None, a new MATLAB engine will be started (which takes some time). Defaults to None.
**kwargs (optional) – see nnsa.ClassWithParameters.

Examples

>>> np.random.seed(0)
>>> x = np.random.rand(2, 2500)
>>> mfa = MultifractalAnalysis()
>>> print(type(mfa.parameters).__name__)
Parameters

>>> mfa_result = mfa.multifractal_analysis(x, fs=25, verbose=0)
Starting MATLAB engine...
Setting up the path...
>>> print(type(mfa_result).__name__)
MultifractalAnalysisResult

>>> mfa_result.cp[0, 0, 0]
0.5654653145233981

Methods:

`default_parameters`()	Return the default parameters.
`mfa_time_series`(time_series, fs, fs_rr, j1, ...)	Compute multifractality features of a time series.
`multifractal_analysis`(data_matrix, fs[, ...])	Perform the multifractal (MF) analysis on multichannel data.

Attributes:

eng

Return a MATLAB engine.

static default_parameters()[source]

Return the default parameters.

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

property eng

Return a MATLAB engine.

Returns:: (matlab.engine.matlabengine.MatlabEngine) – MATLAB engine.

mfa_time_series(time_series, fs, fs_rr, j1, j2, nq)[source]

Compute multifractality features of a time series.

Parameters:

time_series (np.ndarray) – 1D array with time series data to analyze.
fs (int) – sample frequency of the data in time_series.
fs_rr – (int): resampling frequency for the power in the delta frequency band.
j1 (int) – smallest scale analysis.
j2 (int) – largest scale analysis.
nq (int) – number of (positive) q values that will be used (see build_q_log()).

Returns:

zq (np.ndarray) – estimates of the partition function zeta(q).
hq (np.ndarray) – estimates of Hurst exponents h(q).
dq (np.ndarray) – estimates of singularity/multifractal spectrum D(q).
cp (np.ndarray) – estimates of the coefficients c_p from the Taylor expansion that estimate tau(q).
Element i-1 in the cp array corresponds to c_i.
hmin (float) – Hurst exponent at the left of the spectrum (at q=-5).
hmax (float) – Hurst exponent at the right of the spectrum (at q=5).

multifractal_analysis(data_matrix, fs, channel_labels=None, verbose=1)[source]

Perform the multifractal (MF) analysis on multichannel data.

Analysis pipeline ported from MATLAB code designed by Ofelie De Wel and Mario Lavanga.

Pipeline constsist of 4 steps: 1) Segmentation 2) Optional filtering 3) Artefact exclusion 4) MF feature computation

Reference:: Lavanga M., De Wel O., Caicedo A., Heremans E., Jansen K., Dereymaeker A., Naulaers G., Van Huffel S. (2017), Automatic quiet sleep detection based on multifractality in preterm neonates: effects of maturation. Proc. of the 39th Annual International Conference of the IEEE Engineering in Medicine and Biology Society of the IEEE (EMBC 2017) Jeju Island, South Korea, Jul. 2017, pp. 2010-2013

Parameters:

data_matrix (np.ndarray) – see check_multichannel_data_matrix().
fs (float) – sample frequency of the EEG signals.
channel_labels (list of str, optional) – see check_multichannel_data_matrix().
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(nnsa.MultifractalAnalysisResult) – object containing the MF result per segment and per channel.

class nnsa.feature_extraction.fractality.MultifractalAnalysisResult(cp, hmin, hmax, algorithm_parameters, q_functions=None, channel_labels=None, data_info=None, segment_start_times=None, segment_end_times=None, fs=None)[source]

Bases: ResultBase

High-level interface for processing the results of multifractal analysis as created by nnsa.MultifractalAnalysis().

Parameters:

cp (np.ndarray) – estimates of the coefficients c_p from the Taylor expansion that estimate tau(q) with dimensions (p, channels, segments). Element i-1 in the cp array corresponds to c_i.
hmin (np.ndarray) – Hurst exponent at the left of the spectrum (at q=-5) with dimensions (channels, segments).
hmax (np.ndarray) – Hurst exponent at the right of the spectrum (at q=5) with dimensions (channels, segments).
algorithm_parameters (nnsa.Parameters) – see ResultBase.
q_functions (dict, optional) – dict with functions of q (e.g. ‘zq’, ‘hq’, ‘Dq’). Each value in the dict is an array with dimensions (q, channels, segments). Each array in the dict must have this same shape.
channel_labels (list of str, optional) – labels of the channels corresponding to the channel dimensions of the arrays. If None, default labels will be created. Default is None.
data_info (str, optional) – see ResultBase.
segment_start_times (np.ndarray, optional) – see ResultBase.
segment_end_times (np.ndarray, optional) – see ResultBase.
fs (flaot, optional) – see ResultBase.

Methods:

`extract_features`()	Return standard set of features extracted from the result of the MFA.
`extract_global_features`(**kwargs)	Extract features that characterize the entire recording.
`plot`([ax])	Plot the result.

Attributes:

`num_segments`	Return the number of segments.
`q`	Return array with q values.

extract_features()[source]

Return standard set of features extracted from the result of the MFA.

Returns:: (dict) – dictionary with features. Features are arrays with dimension (channels, segments).

extract_global_features(**kwargs)[source]

Extract features that characterize the entire recording.

Parameters:: **kwargs (optional) – optional keyword arguments for local_to_global_features().
Returns:: global_features (dict) – see local_to_global_features().

property num_segments

Return the number of segments.

Returns:: (int) – number of segments.

plot(ax=None)[source]

Plot the result.

Parameters:: ax –

Returns:

property q

Return array with q values.

Returns:: (np.ndarray) – array with q values.

nnsa.feature_extraction.fractality.buid_q_log(q_min=0.01, q_max=5, n=50)[source]

Build a convenient array q for multifractal analysis.

The created array consist of the following values: pm log-spaced values between q_min and q_max, 0, pm 1 and pm 2.

Parameters:

q_min (float, optional) – minimum values for positive q.
q_max (flaot, optional) – maxmimum value for positive q.
n (int, optional) – number of log-spaced values for positive q.

Returns:

(np.ndarray) – array with q values in sorted order.

nnsa.feature_extraction.fractality.histogram_features_lll(line_length, channel_labels=None, ignore_nan=True)[source]

Compute the histogram features from the log Line Length distribution.

N. Koolen et al., “Data-driven metric representing the maturation of preterm EEG,” 2015 37th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC), Milan, 2015, pp. 1492-1495.

Parameters:

line_length (np.ndarray) – array with the normalized line length with dimensions (channels, segments).
channel_labels (list, optional) – list of the channel labels corresponding to the rows of line_length.
ignore_nan (bool, optional) – if True, ignore nan values in line_length. Defaults to True.

Returns:

(pd.DataFrame) – dataframe with the channel labels as row index and the features as columns.

nnsa.feature_extraction.fractality.wfbmesti(x, method='derivative_wavelet', axis=-1, keepdims=False)[source]

Compute Hurst exponent using the second order discrete derivative as in MATLAB’s wfbmesti function.

This function only implements the two second order discrete derivative methods from MATLAB’s function, the third method (variance versus level) is not implemented here (since it is the slowest method).

Parameters:

x (np.ndarray) – input signal(s).
method (str) – which method to use. Chose from: ‘derivative’: the first estimate returned by MATLAB. ‘derivative_wavelet’: the second estimate returned by MATLAB.
axis (int) – the time axis in x.
keepdims (bool) – if True, the time axis is reduced to 1, if False, the time axis is removed.

Returns:

H (np.ndarray) – array with Hurst exponent(s). E.g., if x has shape (p, q, r), axis is -1 and keepdims is False, then H has shape (p, q).

nnsa.feature_extraction.frequency_analysis module

Algorithms for extraction of frequency features.

Classes:

`PowerAnalysis`(**kwargs)	Class for performing a power analysis of EEG signal.
`PowerAnalysisResult`(power, algorithm_parameters)	High-level interface for processing the results of a power analysis as created by nnsa.PowerAnalysis().
`Psd`(**kwargs)	Class for estimating the power spectral density of a signal using Welch's method.
`PsdResult`(power_density, df, ...[, ...])	High-level interface for power spectral density results as created by nnsa.Psd().psd().

class nnsa.feature_extraction.frequency_analysis.PowerAnalysis(**kwargs)[source]

Bases: ClassWithParameters

Class for performing a power analysis of EEG signal.

References: this code was ported from Mario Lavanga and Ofelie de Wel’s MATLAB code.

Main method: power_analysis()

Parameters:: nnsa.ClassWithParameters. (see) –

Examples

>>> np.random.seed(0)
>>> x = np.random.rand(10, 10000)
>>> power_analysis = PowerAnalysis()
>>> assert_equal(power_analysis.parameters, PowerAnalysis.default_parameters())
>>> print(type(power_analysis.parameters).__name__)
Parameters

>>> power_analysis_result = power_analysis.power_analysis(x, fs=25, verbose=0)
>>> print(type(power_analysis_result).__name__)
PowerAnalysisResult

>>> power_analysis_result.power['delta_1'][2, 3]
0.01603280237682399

Methods:

`default_parameters`()	Return the default parameters.
`power_analysis`(data_matrix, fs[, ...])	Perform the power analysis on multichannel data as designed by Mario Lavanga and Ofelie De Wel.

static default_parameters()[source]

Return the default parameters.

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

power_analysis(data_matrix, fs, channel_labels=None, unit=None, verbose=1)[source]

Perform the power analysis on multichannel data as designed by Mario Lavanga and Ofelie De Wel.

Code was ported from MATLAB and constsist of 5 steps: 1) Segmentation 2) Optional filtering 3) Artefact exclusion 4) PSD estimation 5) Computation of frequency power in specified frequency bands per segment

Parameters:

data_matrix (np.ndarray) – see check_multichannel_data_matrix().
fs (float) – sample frequency of the EEG signals.
channel_labels (list of str, optional) – see check_multichannel_data_matrix().
unit (str, optional) – the physical unit of the signals in data_matrix (e.g. ‘uV’). If None no unit is passed to the returned object (PowerAnalysisResult). Defaults to None.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(nnsa.PowerAnalysisResult) – object containing the powers of the frequency bands per segment and per channel.

class nnsa.feature_extraction.frequency_analysis.PowerAnalysisResult(power, algorithm_parameters, channel_labels=None, data_info=None, unit=None, segment_start_times=None, segment_end_times=None, fs=None)[source]

Bases: ResultBase

High-level interface for processing the results of a power analysis as created by nnsa.PowerAnalysis().

Parameters:

power (dict) – dictionary with frequency band labels as keys and (channels, segments) arrays with power as values, e.g. as returned by nnsa.PowerAnalysis.power_analysis()
algorithm_parameters (nnsa.Parameters) – see ResultBase.
channel_labels (list of str, optional) – labels of the channels corresponding to the rows of the values in power. If None, default labels will be created. Default is None.
data_info (str, optional) – see ResultBase.
unit (str, optional) – unit of the values in power.
segment_start_times (np.ndarray, optional) – see ResultBase.
segment_end_times (np.ndarray, optional) – see ResultBase.
fs (flaot, optional) – see ResultBase.

Methods:

`compute_relative_power`()	Compute the relative power per channel per segment for each band.
`extract_channels`(channels[, inplace])
`extract_global_features`(**kwargs)	Extract features that characterize the entire recording.
`extract_histogram_features`([ignore_nan])	Compute the histogram features of each feature attribute.
`plot`([channels, frequency_bands, legend, ax])	Plot the power analysis.
`summary`([cell_width, n_decimals, ...])	Print a summary of the power analysis.

Attributes:

num_segments

Return the number of segments.

compute_relative_power()[source]

Compute the relative power per channel per segment for each band.

Returns:: rel_power (dict) – relative power per band.

extract_channels(channels, inplace=False)[source]

extract_global_features(**kwargs)[source]

Extract features that characterize the entire recording.

Parameters:: **kwargs (optional) – optional keyword arguments for local_to_global_features().
Returns:: global_features (dict) – see local_to_global_features().

extract_histogram_features(ignore_nan=True)[source]

Compute the histogram features of each feature attribute.

Parameters:: ignore_nan (bool, optional) – if True, ignore nan values. Defaults to True.
Returns:: out (dict) – dict with feature names as keys and feature values as values.

property num_segments

Return the number of segments.

Returns:: (int) – number of segments.

plot(channels=None, frequency_bands=None, legend=True, ax=None)[source]

Plot the power analysis.

Creates a subplot for each frequency band and plots the corresponding power of all (specified) channels.

Parameters:

channels (list of str, optional) – a list of labels that specify which channels to plot. If None, all channels are plotted. Defaults to None.
frequency_bands (list of str, optional) – a list of labels that specify which frequency bands to plot. If None, all bands are plotted. Defaults to None.
legend (bool, optional) – whether to plot the legend or not. Defaults to True.

Returns:

fig – Figure handle.
ax (list) – list with axes handles for each subplot.

summary(cell_width=10, n_decimals=2, frequency_bands=None)[source]

Print a summary of the power analysis.

Parameters:

cell_width (int, optional) – width of a cell in the table that is printed.
n_decimals (int, optional) – number of decimals to print.
frequency_bands (list, optional) – a list with labels for the frequency bands to print the summary of.

class nnsa.feature_extraction.frequency_analysis.Psd(**kwargs)[source]

Bases: ClassWithParameters

Class for estimating the power spectral density of a signal using Welch’s method.

Main method: psd()

Parameters:: nnsa.ClassWithParameters. (see) –

Examples

>>> np.random.seed(0)
>>> x = np.random.rand(10000)
>>> psd = Psd()
>>> assert_equal(psd.parameters, Psd.default_parameters())
>>> print(type(psd.parameters).__name__)
Parameters

>>> psd_result = psd.psd(x, fs=250)
>>> print(type(psd_result).__name__)
PsdResult

>>> print(psd_result.power_density)
[7.20648796e-01 1.43280205e+00 1.40759024e+00 ... 2.83669937e-04
 2.81437262e-04 1.40343941e-04]

Methods:

`default_parameters`()	Return the default parameters as a dictionary.
`process`(args, *kwargs)	Alias for self.psd().
`psd`(x, fs[, unit, axis, verbose])	Estimate the power spectral density using Welch's method.

static default_parameters()[source]

Return the default parameters as a dictionary.

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

process(*args, **kwargs)[source]: Alias for self.psd().

psd(x, fs, unit='a.u.', axis=-1, verbose=0, **kwargs)[source]

Estimate the power spectral density using Welch’s method.

Parameters:

x (np.ndarray) – signal data array.
fs (float) – sample frequency of the signal in Hz.
unit (str, optional) – the unit of the signal values. Defaults to ‘a.u.’
axis (int, optional) – axis along which the periodogram is computed. Defaults to -1.
verbose (int, optional) – verbose level. Defaults to 0.
**kwargs (optional) – for scipy.signal.welch().

Returns:

(nnsa.feature_extraction.PsdResult) – object containing the power spectral density estimate.

class nnsa.feature_extraction.frequency_analysis.PsdResult(power_density, df, algorithm_parameters, data_info=None, unit=None)[source]

Bases: ResultBase

High-level interface for power spectral density results as created by nnsa.Psd().psd().

Parameters:

power_density (np.ndarray) – power spectral density for frequencies 0, df, df*2, …, df*(len(power_density)-1).
df (float) – frequency resolution of the power spectral density.
algorithm_parameters (nnsa.Parameters) – see ResultBase.
data_info (str, optional) – see ResultBase.
unit (str, optional) – the unit corresponding to power.

Methods:

`compute_power`(f_low, f_high)	Compute power of frequency band spanned by f_low and f_high by numerically integrating the psd over this domain.
`normalize`([how, inplace])	Normalize the PSD result.
`plot`(*args[, in_db, cumulative, ...])	Plot the power spectrum density.

Attributes:

`frequencies`	Return the frequencies corresponding to the powers in power_density.
`num_segments`	Return the number of segments/samples.

compute_power(f_low, f_high)[source]

Compute power of frequency band spanned by f_low and f_high by numerically integrating the psd over this domain.

Parameters:

f_low (float) – lower limit of the frequency band.
f_high (float) – upper limit of the frequency band.

Returns:

power (float) – the frequency power spanned by f_low and f_high.

property frequencies

Return the frequencies corresponding to the powers in power_density.

Returns:: (np.ndarray) – array of same length as self.power_denisty containing the corresponding frequencies.

normalize(how='max', inplace=False)[source]

Normalize the PSD result.

Parameters:

how (str) – how to normalize. Choose from: - “max”: noramlize such that maximum power is 1.
inplace (bool) – whether to apply inplace or not.

Returns:

psd (PsdResult) – normalized Psd (only returend if inplace is False).

property num_segments

Return the number of segments/samples.

Returns:: (int) – number of segments/samples.

plot(*args, in_db=True, cumulative=False, title_postfix=None, ax=None, **kwargs)[source]

Plot the power spectrum density.

Parameters:

*args (optional) – optional positional arguments for plt.semilogy function.
in_db (bool) – whether to plot the PSD in decibels (True) or just power (False).
title_postfix (str, optional) – if not None, this will be added to the plot title. Defaults to None.
cumulative (bool) – if True plots the cumulative power by integrating over frequency.
ax (plt.Axes, optional) – axes object to plot in. If None, plots in a new figure. Defaults to None.
**kwargs (optional) – optional keyword arguments for plt.semilogy function.

nnsa.feature_extraction.kernels module

Functions:

compute_rbf_1d(x, y, gamma)

nnsa.feature_extraction.kernels.compute_rbf_1d(x, y, gamma)[source]

nnsa.feature_extraction.result module

Module with Result classes that provide high-level interface for the results of feature extraction algortihms.

Classes:

ResultBase([algorithm_parameters, ...])

Base class for high-level interface for the results of feature extraction algortihms.

Functions:

read_result_from_file(filepath[, verbose])

Read result from file as created by the save_to_file() method of the ResultBase class.

class nnsa.feature_extraction.result.ResultBase(algorithm_parameters=None, data_info=None, segment_start_times=None, segment_end_times=None, fs=None, time_offset=0)[source]

Bases: object

Base class for high-level interface for the results of feature extraction algortihms.

For each class in feature_extraction, a corresponding Result class is made to manipulate/visualize the results.

Parameters:

algorithm_parameters (nnsa.Parameters) – Parameters object of the corresponding feature_extraction class.
data_info (str, optional) – optional string with information about the data (e.g. source file, preprocessing).
segment_start_times (np.array, optional) – start times (in seconds) for the segments. If None, it is assumed that the segments form a continuous series and start at 0 s. The segment times are then derived from the segmentation parameters (if present in algorithm parameters, see self._get_segment_start_times()). Defaults to None.
segment_end_times (np.array, optional) – end times (in seconds) for the segments. If None, the segment times are derived from segment_start_times and the segment length parameter in the segmentation parameters (if present in algorithm parameters, see self._get_segment_end_times()). Defaults to None.
fs (float, optional) – sample frequency corresponding to the segments axis, i.e. 1/segment length. In some cases, the feature extracted is on the same time scale as the original data. In that case, it makes sense to pass a sample frequency instead of segment start and end times. If fs is given while segment_start_times is not and no segmentation parameters are found, the time array corresponding to the segments axis will be derived from fs, assuming the samples are continuous and starting at 0 s. Defaults to None.
time_offset (float, optional) – optional time offset in seconds for the time arrays. Useful to set the define the time array together with fs. This offset will also be added to the segment start times, even if the segment times are defined explicitly. Defaults to 0.

Notes

For the time array corresponding to the segments (if applicable), either specify

fs and time_offset (if the datapoints are equidstant, continuous and starting at time_offset); or
segment_start_times and fs (if the datapoints are not equidistant, but do correspond to the same length, (fs=1/segment_length); or
segment_start_times and segment_end_times (in all other cases. NOTE: do not set segment_start_times == segment_end_times, since this will be interpreted as a discontinuous signal, see self.is_discontinuous()).

Attributes:

`algorithm_parameters`	Return the parameters of the corresponding feature extraction algortihm.
`fs`	Return the sample freqeuncy of the segments.
`num_segments`	Return the number of segments/samples.
`segment_end_times`	Return the end times of the segments in seconds (starting at 0 s).
`segment_length`	Return the segment length in seconds (if the segment lengths is consistent/fixed).
`segment_start_times`	Return the start times of the segments in seconds (starting at 0 s).
`segment_times`	Compute the segments time array corresponding to the segment dimensions of the feature array.
`time`	Time array starting containing start times of the segments.
`time_offset`	Return the time offset in seconds for the time array.

Methods:

`compute_global_features`(**kwargs)	Compute global features.
`extract_epoch`([begin, end, inplace])	Extract part of the data that falls within begin - end.
`is_discontinuous`()	Check if the result is continuous in time.
`merge`(other[, inplace])	Merge other Result objects into one object.
`read_file`(filepath[, verbose])
`save_to_file`(filepath[, overwrite, verbose])	Save ResultBase-derived object to a file.
`to_file`(args, *kwargs)	Shortcut to save_to_file().

property algorithm_parameters

Return the parameters of the corresponding feature extraction algortihm.

Returns:: (nnsa.Parameters) – Parameters object of the corresponding feature_extraction class.

compute_global_features(**kwargs)[source]

Compute global features.

Parameters:: **kwargs (optional) – keyword arguments for pd.DataFrame.
Returns:: df (pd.DataFrame) – dataframe with one row, and feature values in columns.

extract_epoch(begin=None, end=None, inplace=False)[source]

Extract part of the data that falls within begin - end.

Parameters:

begin (float, optional) – begin time of epoch to extract in seconds. Defaults to 0.
end (float, optional) – end time of epoch to extract in seconds. If None, the extracted epoch contains all availabel data from begin on. Defaults to None.
inplace (bool, optional) – if True, extract the epoch inplace by removing data that falls outside the epoch in the current object. If False, a new object is returned, leaving the original one unchanged. Defaults to False.

Returns:

(ResultBase-derived) – new Result object containing only the extracted epoch (if inplace is False).

property fs

Return the sample freqeuncy of the segments.

Returns:: (float) – sample frequency (Hz).

is_discontinuous()[source]

Check if the result is continuous in time. I.e., the time/segment array does not include jumps in time.

Returns:: (bool) – True is the result is discontinuous. False if not.

merge(other, inplace=False)[source]

Merge other Result objects into one object.

A warning is given if the algorithm parameters of the to be merged results are not the same. The algorithm parameters and data info of the current object are taken.

Parameters:

other (list) – list with Result objects (all of the same type).
inplace (bool, optional) – if True, merges the data inplace by adding it to the current object. If False, a new object is returned, leaving the original ones unchanged. Defaults to False.

Returns:

(ResultBase-derived) – new Result object containing the merged result (if inplace is False).

property num_segments

Return the number of segments/samples.

Returns:: (int) – number of segments/samples.

static read_file(filepath, verbose=1)[source]

save_to_file(filepath, overwrite=False, verbose=1)[source]

Save ResultBase-derived object to a file.

Automatically selects the corresponding writer function for the detected file type. The created file can later be read with the function read_result_from_file().

Parameters:

filepath (str) – path to the file to which to save the ResultBase-derived object to. If no file extension is included in the filepath, the .hdf5 will be added by default and the result will be saved to an hdf5 file. To save as a different file, specify a compatible file extension (see SUPPORTED_RESULT_FILE_TYPES).
overwrite (bool) – if True, overwrites exisiting file if filepath exists. If False, raises an error if filepath already exists. Defaults to False.
verbose (int, optional) – verbose level.

property segment_end_times

Return the end times of the segments in seconds (starting at 0 s).

Returns:: (np.array) – end times (in seconds) for the segments.

property segment_length

Return the segment length in seconds (if the segment lengths is consistent/fixed).

Raises a ValueError if the segment length is not constant.

Returns:: segment_length (float) – segment length (in seconds).

property segment_start_times

Return the start times of the segments in seconds (starting at 0 s).

Returns:: (np.array) – start times (in seconds) for the segments.

property segment_times

Compute the segments time array corresponding to the segment dimensions of the feature array.

Returns:: segment_times (np.ndarray) – time (in seconds) array for the axis corresponding to segments.

property time

Time array starting containing start times of the segments.

Shortcut when result is sampled with self.fs.

Returns:: self.segment_start_times

property time_offset

Return the time offset in seconds for the time array.

Returns:: (float) – time offset in seconds.

to_file(*args, **kwargs)[source]: Shortcut to save_to_file().

nnsa.feature_extraction.result.read_result_from_file(filepath, verbose=1)[source]

Read result from file as created by the save_to_file() method of the ResultBase class.

Automatically calls the corresponding read function for the detected file type.

Parameters:

filepath (str) – path to the file containing the result as created by the save_to_file() method of the ResultBase class. The object returned by this function will be equal to the object that created the file. The file extension must be included in filepath.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

result (nnsa.ResultBase) – instance of a ResultBase-derived class containing the result.

nnsa.feature_extraction.sleep_stages module

Code for sleep stage-related feature extraction (after classification/annotation wct)

Classes:

`SleepStages`(**kwargs)	Sleep stage classification from text annotations.
`SleepStagesCnn`([num_classes, detect_novelties])	Sleep stage classification using a Convolutional Neural Network.
`SleepStagesCnnResult`(probabilities, ...[, ...])	High-level interface for manipulating sleep stage probabilities as predicted by nnsa.SleepStagesCnn().sleep_stages_cnn().
`SleepStagesResult`(annotation_set[, ...])	High-level interface for manipulating sleep stage annotations as created by nnsa.SleepStages().sleep_stages().

Functions:

`add_sleep_features_2`(sleep_stages_result, ...)	Helper function to add features in a 2-class SleepStagesResult to a dictionary.
`get_cnn_sleep_result`(filepath[, ...])	Helper function to read an EDF+ file and do the sleep stage classification using the CNN.

class nnsa.feature_extraction.sleep_stages.SleepStages(**kwargs)[source]

Bases: ClassWithParameters

Sleep stage classification from text annotations.

main method: sleep_stages()

Parameters:: nnsa.ClassWithParameters. (see) –

Examples

>>> ss = SleepStages()
>>> assert_equal(ss.parameters, SleepStages.default_parameters())
>>> print(type(ss.parameters).__name__)
Parameters

>>> annotation_set = AnnotationSet([Annotation(0, 100, 'QS TA'), Annotation(139.2, 60.8, 'AS1')])
>>> ss_result = ss.sleep_stages(annotation_set)
>>> print(type(ss_result).__name__)
SleepStagesResult

>>> print(ss_result.proportion('QS'))
0.5

Methods:

`annotation_conversions`(annotation_set)	Convert each unique annotation in the annotation set to a standard annotation text and a sleep label.
`default_parameters`()	Return the default parameters as a dictionary.
`sleep_stages`(annotation_set[, verbose])	Infer the course of the sleep stages from the annotations.

annotation_conversions(annotation_set)[source]

Convert each unique annotation in the annotation set to a standard annotation text and a sleep label.

Can be used to see how individual annotations are converted to sleep labels.

Parameters:: annotation_set (nnsa.AnnotationSet) – text annotations that need to be converted to sleep stages.
Returns:: (pd.DataFrame) – DataFrame with columns ‘original_text’, ‘standard_text’ and ‘sleep_label’.

static default_parameters()[source]

Return the default parameters as a dictionary.

Returns:: (nnsa.Parameters) – a default set of parameters for the sleep stages.

sleep_stages(annotation_set, verbose=1)[source]

Infer the course of the sleep stages from the annotations.

Sort the annotations based on onset.
Standardize the annotations, i.e., find a standard annotation text for each annotation.

3) Convert the standard texts to sleep stage labels (controlled by class_mapping and include_labels_with_artefacts parameters). 4) Fill unlabeled periods using no_label annotations. 5) Merge successive annotations if their label is the same. 6) Interpolate/replace artefact segments (controlled by interpolate_no_label_kwargs parameter). 7) Remove short sleep stages (controlled by remove_short_stages_kwargs parameter).

Parameters:

annotation_set (nnsa.AnnotationSet) – text annotations that need to be converted to sleep stages.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(nnsa.SleepStagesResult) – SleepStagesResult object containing the annotations related to sleep stages.

class nnsa.feature_extraction.sleep_stages.SleepStagesCnn(num_classes=2, detect_novelties=True, **kwargs)[source]

Bases: ClassWithParameters

Sleep stage classification using a Convolutional Neural Network.

References: A. H. Ansari et al., “A convolutional neural network outperforming state-of-the-art sleep staging algorithms for both preterm and term infants” Journal of Neural Engineering, vol. 17, no. 1, p. 16028, Jan. 2020, doi: 10.1088/1741-2552/ab5469.

main method: sleep_stages_cnn()

Note

Tested with keras version 2.2.4 and tensorflow version 1.13.1 and with python version 3.6.

Parameters:

num_classes (int) – number of classes in sleep stage classification (2-class (2), or 4-class (4)).
**kwargs (optional) – optional keyword arguments for nnsa.ClassWithParameters.

Examples

>>> np.random.seed(0)
>>> x = np.random.rand(20, 900, 8)*400 - 200
>>> cnn = SleepStagesCnn()
>>> assert_equal(cnn.parameters, SleepStagesCnn.default_parameters())
>>> print(type(cnn.parameters).__name__)
Parameters

>>> cnn_result = cnn.sleep_stages_cnn(x, verbose=0)
>>> print(type(cnn_result).__name__)
SleepStagesCnnResult

>>> print(cnn_result.probabilities[:, 0])
[0.04391909 0.95608091]

Attributes:

`data_requirements`	Return a dictionary with requirements for the input of the CNN.
`keras_model`	Return the model.
`keras_model_activations`	Return the model for intermediate activations.
`keras_model_latent`	Return the model for latent features.
`model_dir`	Return the directory containing model files.
`model_path`	Return the filpath of the model.
`norm_param_path`	Return the filpath with the normalization parameters.
`normalization_parameters`	Return the normalization parameters.

Methods:

`default_parameters`()	Return the default parameters as a dictionary.
`predict_activations`(x[, verbose])
`preprocess_recording`(raw_eeg, raw_fs[, verbose])	Run the preprocessing routine (filtering, resampling) on an entire recording.
`process`(eeg, fs[, verbose])	Process raw EEG data (channel order should match self.data_requirements['channel_order']).
`sleep_stages_cnn`(x[, segment_start_times, ...])	Apply the sleep stage classification algortihm to the preprocessed (filtered/resampled/segmented) input x: 1) normalize input x, 2) predict the CNN output, 3) postprocess the output.

property data_requirements

Return a dictionary with requirements for the input of the CNN.

Returns:: data_requirements (dict) – a dictionary with requirements for the input of the CNN (e.g., channel order, fs, segment length).

static default_parameters()[source]

Return the default parameters as a dictionary.

Returns:: (nnsa.Parameters) – a default set of parameters for the model.

property keras_model

Return the model.

Returns:: (nnsa.model or keras.model) – model object.

property keras_model_activations

Return the model for intermediate activations.

Returns:: (nnsa.model or keras.model) – model object.

property keras_model_latent

Return the model for latent features.

Returns:: (nnsa.model or keras.model) – model object.

property model_dir

Return the directory containing model files.

Returns:: model_dir (str) – path to directory with model files.

property model_path

Return the filpath of the model.

Returns:: model_path (str) – filepath of the model.

property norm_param_path

Return the filpath with the normalization parameters.

Returns:: norm_param_path (str) – filepath of the pickle file with the normalization parameters. The file contains 2 arrays. The first array contains the means per channel and the second the stds per channel for normalization (see self._load_normalization_parameters).

property normalization_parameters

Return the normalization parameters.

Returns:: (tuple) – normalization parameters.

predict_activations(x, verbose=1)[source]

preprocess_recording(raw_eeg, raw_fs, verbose=1)[source]

Run the preprocessing routine (filtering, resampling) on an entire recording.

Parameters:

raw_eeg (np.ndarray) – raw EEG data to wct with shape (time, channels).
raw_fs (float) – sample frequency of raw EEG data.
verbose – (int): verbosity level.

Returns:

eeg (np.ndarray) – preprocessed EEG data.
fs (float) – sample frequency of preprocessed EEG data.

process(eeg, fs, verbose=1, **kwargs)[source]

Process raw EEG data (channel order should match self.data_requirements[‘channel_order’]).

Parameters:

eeg (np.ndarray) – 2D array with shape (time, channels) with raw (unfiltered) EEG data. The data should be referenced as required and in the channels should have the order as required in self.data_requirements.
fs (float) – sampling frequency of eeg (Hz).
verbose (int) – verbosity level.

sleep_stages_cnn(x, segment_start_times=None, segment_end_times=None, verbose=1)[source]

Apply the sleep stage classification algortihm to the preprocessed (filtered/resampled/segmented) input x: 1) normalize input x, 2) predict the CNN output, 3) postprocess the output.

Parameters:

x (np.ndarray) – (unnormalized) input array with shape corresponding to (segments, time, channels) with preprocessed (filtered and resampled) EEG data. Note that the time and channels dimension depend on the shape of the input layer in the CNN model. E.g. for the default model, shape of x must be (num_segments, 900, 8), corresponding to 30 second segments sampled at 30 Hz and 8 mono-polar EEG channels with reference Cz in the following order: Fp1, Fp2, C3, C4, T3, T4, O1, O2. The array may also be 4 dimensional with shape (segments, time, channels, 1), which is the shape for the CNN model. If x does not have this fourth dimension, it will be added by this preprocessing.
verbose (int, optional) – verbose level (0 or 1). Default to 1.

Returns:

(SleepStagesCnnResult) – nnsa object containing the results of the CNN sleep stage classification.

class nnsa.feature_extraction.sleep_stages.SleepStagesCnnResult(probabilities, class_labels, fs, algorithm_parameters, is_novelty=None, novelty_score=None, latent_features=None, data_info=None, segment_start_times=None, segment_end_times=None, time_offset=0)[source]

Bases: ResultBase

High-level interface for manipulating sleep stage probabilities as predicted by nnsa.SleepStagesCnn().sleep_stages_cnn().

Also note the method .to_sleep_stages_result(), which returns a more general object SleepStagesResult that provides a high level interface for manipulating sleep stages/labels in general. SleepStagesCnnResult class differs from SleepStagesResult, in that this class contains the result of a classifier, and provides methods to analyze the outcome of the classifier (e.g. compute score metrics, investigate probabilities etc.), whereas the SleepStagesResult class focusses on the analysis of the sleep stages (which may either be defined automatically or manually by a clinician).

Parameters:

probabilities (np.ndarray) – probabilties for a number of segments per class with shape (num_classes, num_segments).
class_labels (list of str) – class labels corresponding to the rows of self.probabilities.
fs (float) – 1/segment length in Hz.
algorithm_parameters (nnsa.Parameters) – see ResultBase.
is_novelty (np.ndarray, None) – optional boolean array with shape (n_segments,) indicating which segmentes were classified as novelties (out-of-data).
is_novelty – optional array with shape (n_segments,) containing novelty scores for each segment.
data_info (str, optional) – see ResultBase.
segment_start_times (np.ndarray, optional) – see ResultBase.
segment_end_times (np.ndarray, optional) – see ResultBase.

Attributes:

`class_mapping`	Return class mapping (=dictionary that maps a class label to a class number).
`df`
`num_segments`	Return the number of segments.
`y_pred`	Return the class predictions.

Methods:

`compute_global_features`(**kwargs)	Compute global features.
`confusion_matrix`(y_true)	Return a ConfusionMatrix object conatining the confusion matrix.
`convert_classes`(target_class_labels)	Convert to different, derivative classes.
`get_classes`([threshold, return_probs])	Convert the probabilities to class numbers.
`get_naive_labels`([threshold])	Return the sleep label for each class.
`get_probabilities`(class_label)	Return the classification probabilities per segment for a given class_label.
`get_segment_indices`(class_label)	Return the indices of the segments classified as class_label.
`plot`(args, *kwargs)
`plot_probabilities`([class_label, ...])	Plot the probility of the segments belonging to the secified class.
`plot_probability`(args, *kwargs)
`remove_artefacts`(af_mask[, fs_mask, t_mask, ...])	Remove artefacts by setting the probabilities of segment during which too many samples were artefacts to nan.
`robust_sleep_labels`(aci_per_chan, amp[, ...])	Robust sleep prediction by introducing more classes, like artefacts, movement, novelty, uncertain, transitional.
`to_annotation_set`([threshold])	Convert the CNN output to an AnnotationSet with the sleep labels.
`to_annotation_set_per_segment`([threshold])	Convert the CNN output to an AnnotationSet with the sleep labels creating one Annotation per segment.
`to_dataframe`(args, *kwargs)	Collect relevant results in a pandas dataframe where each row is a segment.
`to_df`(args, *kwargs)
`to_frame`(args, *kwargs)
`to_sleep_stages_result`([threshold, verbose])	Convert the probabilities to sleep stages and return the sleep stages as a SleepStagesResult object.

property class_mapping

Return class mapping (=dictionary that maps a class label to a class number).

Returns:: (dict) – dictionary that maps a class label to a class number.

compute_global_features(**kwargs)[source]

Compute global features.

Parameters:: **kwargs (optional) – keyword arguments for SleepStagesResult.compute_global_features().
Returns:: df (pd.DataFrame) – dataframe with one row, and feature values in columns.

confusion_matrix(y_true)[source]

Return a ConfusionMatrix object conatining the confusion matrix.

Parameters:: y_true (np.ndarray) – 1D array with true class numbers.
Returns:: confusion_matrix (nnsa.ConfusionMatrix) – object containing the confusion matrix.

convert_classes(target_class_labels)[source]

Convert to different, derivative classes.

Parameters:: target_class_labels (list) – list with new class labels.
Returns:: ss_out (SleepStagesCnn) – new object with probabilities corresponding to the target classes.

property df

get_classes(threshold=None, return_probs=False)[source]

Convert the probabilities to class numbers.

Parameters:

threshold (float, optional) – threshold of probability. If probability for the maximum class is lower than the threshold, the class number of that segment will be np.nan. If None, the clas with the maximum probability will be taken. Defaults to None.
return_probs (bool) – return probabilities as well (True).

Returns:

classes (np.ndarray) – 1D array with same length as self.probabilities with integers representing the classes as defined in self.class_labels, i.e. class i corresponds to self.class_labels[i].
return_probs (np.ndarray) – arrray with same length as classes with the maximum probabilities per segment.

get_naive_labels(threshold=None)[source]

Return the sleep label for each class.

Parameters:: threshold (float, optional) – threshold of probability. If probability for the maximum class is lower than the threshold, the class number of that segment will be np.nan. If None, the clas with the maximum probability will be taken. Defaults to None.
Returns:: labels (list) – list with same length as self.probabilities with the sleep labels (str).

get_probabilities(class_label)[source]

Return the classification probabilities per segment for a given class_label.

Parameters:: class_label (str) – the label of the class to get the probabilities from.
Returns:: (np.ndarray) – probabilities of each segment for the class_label class.

get_segment_indices(class_label)[source]

Return the indices of the segments classified as class_label.

Parameters:: class_label (str) – the label of the class to get the segment indices from.
Returns:: (np.ndarray) – indices of segments classified as class_label.

property num_segments

Return the number of segments.

Returns:: (int) – number of segments.

plot(*args, **kwargs)[source]

plot_probabilities(class_label=None, class_number=None, time_scale='hours', ax=None, novelty_color='C3', *args, **kwargs)[source]

Plot the probility of the segments belonging to the secified class.

Parameters:

class_label (str) – the label of the class to plot the probabilities of.
novelty_color – color for highlighting novelties (if available). If None, novelties are not highlighted.

plot_probability(*args, **kwargs)[source]

remove_artefacts(af_mask, fs_mask=None, t_mask=None, max_af_samples_frac=0.5, max_af_channels_frac=0.125, inplace=False)[source]

Remove artefacts by setting the probabilities of segment during which too many samples were artefacts to nan.

Parameters:

af_mask (np.ndarray) – array with shape (n_channels, n_samples).
fs_mask (float) – optional sampling frequency of af_mask. If you do not specify this, specify t_mask.
t_mask (np.ndarray) – array with shape (n_samples) containing the time vector for af_mask.
max_af_samples_frac (float) – if the fraction of artefacts in a channel segment is larger than this, the channel is considered artefact for that segment.
max_af_channels_frac (float) – if the fraction of artefacted channels is larger than this. the segment is considered artefact and the corresponding values in self.probabilities will be set to nan.
inplace (bool) – whether to remove artefacts inplcae (True) or not (False). If not inplace, returns the new object, otherwise does not return anything.

Returns:

ss_out (SleepStagesCnnResult) – copy of the object, but with artefacts set to nan (only if inplace is False).

robust_sleep_labels(aci_per_chan, amp, add_naive=False)[source]

Robust sleep prediction by introducing more classes, like artefacts, movement, novelty, uncertain, transitional.

Parameters:

aci_per_chan (np.ndarray) – 2D array with shape (n_segments, n_channels) containing the artefact contamination index (%) for each segment.
amp (np.ndarray) – 2D array with shape (n_segments, n_channels) containing amplitudes of each segment and channel.
add_naive (bool) – if True or ‘all’ adds the naive/raw sleep label to the robust label in brackets. If ‘missing’: adds the naive/raw sleep label to the robust label only for missing sleep stages. If None or False, does not include the naive label.

Returns:

robust_sleep_labels (list) – list with length n_segments containing robust labels.

to_annotation_set(threshold=None)[source]

Convert the CNN output to an AnnotationSet with the sleep labels.

Parameters:: threshold (float, optional) – theshold for probability, see self.get_classes(). Defaults to None.
Returns:: annotation_set (nnsa.AnnotationSet) – object containing the sleep stages as annotations.

to_annotation_set_per_segment(threshold=None)[source]

Convert the CNN output to an AnnotationSet with the sleep labels creating one Annotation per segment.

Parameters:: threshold (float, optional) – theshold for probability, see self.get_classes(). If None, takes class with maximum probability.
Returns:: annotation_set (nnsa.AnnotationSet) – object containing the sleep stages as annotations.

to_dataframe(*args, **kwargs)[source]

Collect relevant results in a pandas dataframe where each row is a segment.

Parameters:

*args –
**kwargs –

Returns:

df (pd.DataFrame) – pandas DataFrame with segment-wise results.

to_df(*args, **kwargs)[source]

to_frame(*args, **kwargs)[source]

to_sleep_stages_result(threshold=None, verbose=1, **kwargs)[source]

Convert the probabilities to sleep stages and return the sleep stages as a SleepStagesResult object.

This is a wrapper that prepares the input for SleepStages.sleep_stages() and returns the result.

Parameters:

threshold (float, optional) – theshold for probability, see self.get_classes(). Defaults to None.
verbose (int, optional) – verbosity level for creation of sleep stages.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the SleepStages class.

Returns:

result (nnsa.SleepStagesResult) – SleepStagesResult object containing annotations related to sleep stages.

property y_pred

Return the class predictions.

Returns:: (np.ndarray) – array with integer values representing classes.

class nnsa.feature_extraction.sleep_stages.SleepStagesResult(annotation_set, algorithm_parameters=None, class_mapping=None, data_info=None)[source]

Bases: ResultBase

High-level interface for manipulating sleep stage annotations as created by nnsa.SleepStages().sleep_stages().

Parameters:

annotation_set (nnsa.AnnotationSet) – AnnotationSet consisting of sleep labels. All labels must have a duration. Each unique label is considered a class.
algorithm_parameters (nnsa.Parameters, optional) – see ResultBase.
class_mapping (dict, optional) – dictionary that maps a class label (annotation) to a class number. If None, a default mapping is applied with class numbers ranging from 0 to N-1, with N the number of unique class labels. Defaults to None.
data_info (str, optional) – see ResultBase.

Attributes:

`annotation_set`
`class_labels`
`class_mapping`
`class_mapping_invert`	Invert class mapping.
`num_segments`	Return the number of segments/samples.
`total_duration`	Return the total duration of the annotated period in seconds.

Methods:

`class_numbers_to_labels`(class_numbers)	Convert class numbers to class labels.
`compute_global_features`(**kwargs)	Compute global features.
`count_annotations_per_class`([default_value])	Count the number of annotations per class.
`create_mask`(class_label, query_times[, ...])	Return a boolean mask for (any of the) class_label on the query time points.
`cycle_count`(class_label[, ignore_labels])	Count the number of times a sleep stage transitioned into a different one and back.
`extract_cleanest_epoch`(epoch_length[, dt, ...])	Extract the cleanest epoch (a window of epoch_length with least 'NL' coverage).
`extract_epoch`([begin, end, inplace])	Extract epoch specified by begin and end.
`extract_features`(class_label)	Extract some features from the sleep stage annotations.
`extract_global_features`([postfix])	Extract features that characterize the entire recording.
`get_classes`()	Convert the annotation labels to class numbers and return them as an array.
`inter_class_intervals`(class_label[, ...])	Compute the intervals between a specific sleep stages, specified by class_label.
`interpolate_artefacts`([artefact_texts, ...])	Interpolate artefact labels if they are short enough and surrounded by the same non-artefact label.
`interpolate_classes`(query_times[, kind])	Interpolate class numbers to the time points specified by query_times.
`mean_std_duration_per_class`([default_value])	Compute mean and standard deviation of the duration of each sleep stage class.
`median_duration`(class_label)	Return the median duration of the class_label annotations.
`median_iqr_duration_per_class`([default_value])	Compute median and inter quartile range of the duration of each sleep stage class.
`pieplot`(**kwargs)
`plot`(*args[, offset, time_scale, fill, ax])	Quick plot of the sleep stages as function of time.
`plot_hypnogram`([time_scale, order, ...])	Plot the hypnogram (sleep stages as function of time).
`proportion`(class_label[, ignore_labels, ...])	Return the proportion of segments classified as class_label.
`remove_corrupted_stages`([corrupt_labels, ...])	Remove the sleep stages that are considered corrupted or incomplete.
`remove_short_stages`([min_duration, inplace])	Remove sleep stages that last too short by replacing the labels by no_label (NL).
`segment_labels`(segment_start_times, ...[, ...])	Return an array of labels corresponding to segments with specified start and end times.
`to_dataframe`()	Return a dataframe of self.annotation_set.
`total_duration_per_class`([default_value])	Compute the total duration of each sleep stage class.

property annotation_set

property class_labels

property class_mapping

property class_mapping_invert

Invert class mapping.

Returns:: mapping (dict) – inverted class mapping.

class_numbers_to_labels(class_numbers)[source]

Convert class numbers to class labels.

Nans are convert to no_label labels.

Parameters:: class_numbers (list, np.ndarray) – class numbers to convert.
Returns:: labels (list) – class labels.

compute_global_features(**kwargs)[source]

Compute global features.

Parameters:: **kwargs (optional) – keyword arguments for pd.DataFrame.
Returns:: df (pd.DataFrame) – dataframe with one row, and feature values in columns.

count_annotations_per_class(default_value=0)[source]

Count the number of annotations per class.

Parameters:: default_value (float, optional) – default value if no annotations of a class are present. Set this e.g. to np.nan or zero. Defaults to 0.
Returns:: count_dict (dict) – dictionary with the counts per class.

create_mask(class_label, query_times, check_class_label=True, no_label_to_nan=False)[source]

Return a boolean mask for (any of the) class_label on the query time points.

Parameters:

class_label (str or list) – the label(s) of the class to get the mask from. If a list, True is returned if the label at the query point is in class_label.
query_times (np.ndarray) – query time points for the mask in seconds.
check_class_label (bool, optional) – check if the class labels that are passed exist in self. If check_class_label is True and a label does not occur in self, an error is raised. Defaults to True.
no_label_to_nan (bool, optional) – returns a mask with nans where the label is ‘no_label’. If False, returns False at locations where the sleep label is nan. Defaults to False.

Returns:

mask (np.ndarray) – boolean array with same shape as time specifying whether the sleep stage equals the class_label at the corresponding time point.

cycle_count(class_label, ignore_labels=None)[source]

Count the number of times a sleep stage transitioned into a different one and back.

Ignores no_label.

Assumes the annotations are sorted by onset.

Parameters:

class_label (str) – the label of the sleep stage for which to compute the cycle_count.
ignore_labels (str or list, optional) – specify a class label or list of class labels to ignore. These labels won’t be considered as valid transitions (e.g. artefacts, no_label). no_label segments will automatically be ignored. If None, a default list of labels to ignore will be used. Defaults to None.

Returns:

(int) – number of interruptions.

extract_cleanest_epoch(epoch_length, dt=1, inplace=False)[source]

Extract the cleanest epoch (a window of epoch_length with least ‘NL’ coverage).

Parameters:

epoch_length (float) – length of the epoch to extract (in seconds).
dt (float) – stepsize when searching for the cleanest epoch. Decrease for more accuracy, at the cost of computational time.
inplace (bool) – whether to extract inplace or not.

Returns:

(SleepStagesResult) – extracted epoch, if inplace is False.

extract_epoch(begin=None, end=None, inplace=False)[source]

Extract epoch specified by begin and end.

Parameters:

begin (float) – begin time of epoch (seconds).
end (float) – end time of epoch (seconds).
inplace (bool) – whether to apply the operation inplace (True) or not (False).

Returns:

sleep_stages_result (SleepStagesResult) – new object with extracted epoch (if inplace if False).

extract_features(class_label)[source]

Extract some features from the sleep stage annotations.

Sorts the annotations (inplace).

Parameters:: class_label (str) – the class label to extract features from.
Returns:: (dict) – dictionary with features.

extract_global_features(postfix=None)[source]

Extract features that characterize the entire recording.

Parameters:: postfix (str, optional) – postfix for the keys in the output dictionary. If None, no postfix is added. Defaults to None.
Returns:: (dict) – dictionary containing the feature name and value pairs.

get_classes()[source]

Convert the annotation labels to class numbers and return them as an array.

Returns:: (np.ndarray) – array with the class numbers corrsponding to the sleep stage annotations.

inter_class_intervals(class_label, ignore_labels=None)[source]

Compute the intervals between a specific sleep stages, specified by class_label.

Assumes the annotations are sorted by onset.

Parameters:

class_label (str) – the label of the sleep stage for which to compute the intervals.
ignore_labels (str or list, optional) – specify a class label or list of class labels to ignore. These labels won’t be considered as valid intervals (e.g. artefacts, no_label). If None, ignore nothing. Defaults to None.

Returns:

(np.ndarray) – array with all the intervals that were found.

interpolate_artefacts(artefact_texts=None, max_duration=180, inplace=False, **kwargs)[source]

Interpolate artefact labels if they are short enough and surrounded by the same non-artefact label.

nnsa.feature_extraction.statistics module

Module containing statistics-related functions and classes.

Classes:

`SignalStats`(**kwargs)	Class for computing a set of statistical parameters of a signal.
`SignalStatsResult`(stats, algorithm_parameters)	High-level interface for processing signal statistics as computed by nnsa.SignalStats().

class nnsa.feature_extraction.statistics.SignalStats(**kwargs)[source]

Bases: ClassWithParameters

Class for computing a set of statistical parameters of a signal.

Main method: signal_stats().

Parameters:: nnsa.ClassWithParameters (see) –

Examples

>>> fs = 256
>>> np.random.seed(43)
>>> x = np.random.normal(loc=5, scale=10, size=(8, fs*300))
>>> ss = SignalStats(artefact_criteria=None)
>>> print(type(ss.parameters).__name__)
Parameters

>>> result = ss.signal_stats(x, fs=fs, verbose=0)
>>> print(type(result).__name__)
SignalStatsResult

# Some stats of 3nd channel (index 2), 5th segment (index 4). >>> print(result.stats[‘std’][2, 4]) 9.96795466696633 >>> print(result.stats[‘skewness’][2, 4]) 0.02042382947932932 >>> print(result.stats[‘kurtosis’][2, 4]) 0.028582535331379777

# Average std across all segments and all channels. >>> print(result.stats[‘std’].mean()) 10.00292371308106

Methods:

`default_parameters`()	Return the default parameters as a dictionary.
`signal_stats`(data_matrix, fs[, ...])	Compute signal stats on multichannel data.

static default_parameters()[source]

Return the default parameters as a dictionary.

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

signal_stats(data_matrix, fs, channel_labels=None, verbose=1)[source]

Compute signal stats on multichannel data.

Analysis pipeline ported from MATLAB code designed by Ofelie De Wel and Mario Lavanga.

Pipeline constsist of 4 steps: 1) Segmentation 2) Optional filtering 3) Artefact exclusion 4) Stats computation

Parameters:

data_matrix (np.ndarray) – see check_multichannel_data_matrix().
fs (float) – sample frequency of the signals.
channel_labels (list of str, optional) – see check_multichannel_data_matrix().
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(nnsa.SignalStatsResult) – object containing statistics per segment per channel.

class nnsa.feature_extraction.statistics.SignalStatsResult(stats, algorithm_parameters, channel_labels=None, data_info=None, segment_start_times=None, segment_end_times=None, fs=None)[source]

Bases: ResultBase

High-level interface for processing signal statistics as computed by nnsa.SignalStats().

Parameters:

stats (dict) – dict where each entry is some statistic computed per channel per segment. The entries are matrices with size (n_channels, n_segments).
algorithm_parameters (nnsa.Parameters) – see ResultBase.
channel_labels (list of str, optional) – labels of the channels corresponding to the rows of the values in mse. If None, default labels will be created. Default is None.
data_info (str, optional) – see ResultBase.
segment_start_times (np.ndarray, optional) – see ResultBase.
segment_end_times (np.ndarray, optional) – see ResultBase.
fs (flaot, optional) – see ResultBase.

Attributes:

num_segments

Return the number of segments.

property num_segments

Return the number of segments.

Returns:: (int) – number of segments.

nnsa.feature_extraction.time_domain module

Functions for time-domain feature computation.

Functions:

`auc`(y[, x, dx, zero_level, normalize, axis, ...])	Compute the area under the curve (AUC).
`compute_flatness`(x[, q])	Compute the flatness of x, which is defined as the minimal range in which q% of the values in x lie.

nnsa.feature_extraction.time_domain.auc(y, x=None, dx=1.0, zero_level=0, normalize=False, axis=-1, method='trapz', **kwargs)[source]

Compute the area under the curve (AUC). Excludes nans.

Parameters:

y (np.ndarray) – input array to integrate.
x (np.ndarray, optional) – the sample points corresponding to the y values. If x is None, the sample points are assumed to be evenly spaced dx apart. The default is None.
dx (float, optional) – the spacing between sample points when x is None. The default is 1.
zero_level (float, optional) – y translation. y will be translated by y = y-zero_level before AUC computation. Defaults to 0.
normalize (bool, optional) – if True, normalizes the auc by the number of points.
axis (int, optional) – the axis along which to integrate. Defaults to -1.
method (str, optional) – the method to use for integration. Choose from ‘trapz’, ‘simps’ to use the trapezoidal or Simpson’s rule, respectively.
**kwargs (optional) – optional keyword arguments for the function that is called, depedning on method.

Returns:

auc (float) – area between y and zero_level. y values above zero_level have a positive contribution, while values below zero_level have a negative contribution.

nnsa.feature_extraction.time_domain.compute_flatness(x, q=95)[source]

Compute the flatness of x, which is defined as the minimal range in which q% of the values in x lie.

Parameters:

x (np.ndarray) – 1D array.
q (float, optional) – percentage of data that must lie in the flatness range. Defaults to 95.

Returns:

flatness (float) – minimal range in which q% of the values in x lie.

nnsa.feature_extraction.wavelets module

Wavlet-based feature extraction.

Classes:

`CWT`(**kwargs)	Class for computing continuous wavelet transorm.
`CWTResult`(W, scales, wavelet, insidecoi, ...)	High-level interface for processing continuous wavelet transform as computed by nnsa.CWT().
`WaveletCoherence`(**kwargs)	Class for computing wavelet coherence.
`WaveletCoherenceResult`(P, A, freqs, fs, wavelet)	High-level interface for processing wavelet coherence as computed by nnsa.WaveletCoherence().
`WaveletResult`(P, A, freqs, fs, wavelet[, ...])	High-level interface for processing wavelet maps.

Functions:

`convert_freq_scale`(freqs, freq_scale[, current])	Convert frequencies in the current scale to some other frequency or time scale.
`revert_freq_scale`(freqs, freq_scale)	Convert frequencies in some other frequency or time scale to Hz.

class nnsa.feature_extraction.wavelets.CWT(**kwargs)[source]

Bases: ClassWithParameters

Class for computing continuous wavelet transorm.

Main method: compute_wavelet_coherence() or process().

Parameters:: nnsa.ClassWithParameters. (see) –

Examples

>>> np.random.seed(43)
>>> N = 1024
>>> fs = 1
>>> t = np.arange(0, N, 1/fs)
>>> f_cos = 0.1
>>> x = np.cos(2*np.pi*t*f_cos) + np.random.rand(N)
>>> cwt = CWT()
>>> result = cwt.wct(x, fs=1, verbose=0)
>>> print(type(result).__name__)
CWTResult

>>> result.W.shape
(76, 1024)

# Print most prominent frequency (should be close to f_cos). >>> result.freqs[np.argmax(result.wps())].round(1) 0.1

Methods:

`cwt`(x, fs[, time_offset, label, verbose])	Compute continuous wavelet transform of x.
`default_parameters`()	Return the default parameters.
`process`(args, *kwargs)

cwt(x, fs, time_offset=0, label=None, verbose=1)[source]

Compute continuous wavelet transform of x.

Args: x (array-like): 1D signal array. fs (float): sample frequency of x and y in Hz. time_offset (float, optional): time offset in seconds (i.e. time of the first sample).

Defaults to 0.

label (tuple, optional): label for the output. verbose (int, optional): verbose level.

Defaults to 1.

Returns:: (nnsa.CWTResult) – object containing the result.

static default_parameters()[source]

Return the default parameters.

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

process(*args, **kwargs)[source]

class nnsa.feature_extraction.wavelets.CWTResult(W, scales, wavelet, insidecoi, freqs, *args, signal=None, nan_mask=None, label='CWT', **kwargs)[source]

Bases: ResultBase

High-level interface for processing continuous wavelet transform as computed by nnsa.CWT().

Parameters:

W (np.ndarray) – 2D array with wavelet coefficients (n_freqs, n_time).
scales (np.ndarray) – scales corresponding to the first axis of W.
wavelet (str) – string indicating whihc wavelet was used. E.g. ‘Morlet(6)’.
insidecoi (np.ndarray) – boolean array with same shape as W that is True at locations in the cone of influence (COI).
freqs (np.ndarray) – frequencies in Hz corresponding to the first axis of W.
algorithm_parameters (nnsa.Parameters) – see ResultBase.
signal (np.ndarray, optional) – array of shape (n_time) containing the time signal on which the CWT was computed. Defaults to None.
nan_mask (np.ndarray, optional) – boolean array of shape (n_time) containing True values where the signal originally contained nans which where interpolated prior to wavelet transform. If given, the nan mask can be used to exclude values at time points that where nan originally. Defaults to None.
label (tuple, optional) – label for the signal. Defaults to ‘CWT’.
data_info (str, optional) – see ResultBase.
segment_start_times (np.ndarray, optional) – see ResultBase.
segment_end_times (np.ndarray, optional) – see ResultBase.
fs (flaot, optional) – see ResultBase.

Attributes:

`Wp`	Return the wavelet power.
`dj`
`dt`
`num_segments`	Return the number of segments.
`wavelet`

Methods:

`plot`([signal_kwargs])	General plot of the results.
`plot_scalogram`([ax])	Plot time-frequency scalogram.
`to_wavelet_power`()	Converts to scale-normalized power and phase.
`wps`()	Compute wavelet power spectrum: the wavelet power averaged across time.

property Wp

Return the wavelet power.

The power is scaled by the inverse of the scale, as proposed by Liu et al. 2007.

Returns:: Wp (np.ndarray) – wavelet power (same size as self.W).

property dj

property dt

property num_segments

Return the number of segments.

Returns:: (int) – number of segments/samples.

plot(signal_kwargs=None, **kwargs)[source]: General plot of the results.

plot_scalogram(ax=None, **kwargs)[source]: Plot time-frequency scalogram.

to_wavelet_power()[source]

Converts to scale-normalized power and phase.

Returns:: result (WaveletResult) – WaveetResult instance conatining normailized wavelet power.

property wavelet

wps()[source]

Compute wavelet power spectrum: the wavelet power averaged across time.

Returns:

wps (np.ndarray) – 1D array with powers.
freqs (np.ndarray) – 1D arrays with frequencies corresponding to wps.

class nnsa.feature_extraction.wavelets.WaveletCoherence(**kwargs)[source]

Bases: ClassWithParameters

Class for computing wavelet coherence.

Main method: compute_wavelet_coherence() or process().

Parameters:: nnsa.ClassWithParameters. (see) –

Examples

>>> np.random.seed(43)
>>> N = 1024
>>> fs = 1
>>> t = np.arange(0, N, 1/fs)
>>> f_mutual = 0.1
>>> x = np.cos(2*np.pi*t*f_mutual) + np.random.rand(N)
>>> y = np.sin(2*np.pi*t*f_mutual) + np.random.rand(N)
>>> wc = WaveletCoherence(surrogates={'n_surrogates': 0})
>>> result = wc.wct(x, y, fs=1, verbose=0)
>>> print(type(result).__name__)
WaveletCoherenceResult

>>> result.P.shape
(76, 1024)

# Print most prominent coupled frequency (should be close to the mutual frequency). >>> result.freqs[np.argmax(np.nanmean(result.P, axis=1))].round(1) 0.1

Methods:

`default_parameters`()	Return the default parameters.
`pct`(x, y, z, fs[, time_offset, labels, verbose])	Compute partial wavelet coherence: coherence between x and y, while ignoring common correlation with z.
`wavelet_coherence`(x, y, fs[, time_offset, ...])	Compute wavelet-based coherence between x and y.
`wct`(args, *kwargs)	Alias for self.wavelet_coherence().

static default_parameters()[source]

Return the default parameters.

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

pct(x, y, z, fs, time_offset=0, labels=None, verbose=1)[source]

Compute partial wavelet coherence: coherence between x and y, while ignoring common correlation with z.

Args: x (array-like): 1D signal array. y (array_like): 1D signal array. Must have the same length and sample frequency as x. z (array_like or list): 1D signal array. Must have the same length and sample frequency as x.

Can also be a list of 1D signal arrays, in which case the confounding relation from each of these signals will be removed.

fs (float): sample frequency of x and y in Hz. time_offset (float, optional): time offset in seconds (i.e. time of the first sample).

Defaults to 0.

labels (tuple, optional): labels for the output, see WaveletCoherence.wct().: If labels is not given and TimeSeries are passed, infers the labels from these objects. Otherwise, if labels is None, uses default labels. Defaults to None.
verbose (int, optional): verbose level.: Defaults to 1.

Returns:: (nnsa.WaveletResult) – object containing the result.

wavelet_coherence(x, y, fs, time_offset=0, labels=None, verbose=1)[source]

Compute wavelet-based coherence between x and y.

Args: x (array-like): 1D signal array. y (array_like): 1D signal array. Must have the same length and sample frequency as x. fs (float): sample frequency of x and y in Hz. time_offset (float, optional): time offset in seconds (i.e. time of the first sample).

Defaults to 0.

labels (tuple, optional): labels for the output.: If labels is not given and TimeSeries are passed, infers the labels from these objects. Otherwise, if labels is None, uses default labels (‘x’, ‘y’). Defaults to None.
verbose (int, optional): verbose level.: Defaults to 1.

Returns:: (nnsa.WaveletResult) – object containing the result.

wct(*args, **kwargs)[source]: Alias for self.wavelet_coherence().

class nnsa.feature_extraction.wavelets.WaveletCoherenceResult(P, A, freqs, fs, wavelet, insidecoi=None, name=None, algorithm_parameters=None, significance=None, P_surrogates=None, signals=None, labels=None, extra=None, data_info=None, segment_start_times=None, segment_end_times=None, time_offset=0)[source]

Bases: WaveletResult

High-level interface for processing wavelet coherence as computed by nnsa.WaveletCoherence().

Alias for WaveletResult().

Parameters:: WaveletResult. (see) –

class nnsa.feature_extraction.wavelets.WaveletResult(P, A, freqs, fs, wavelet, insidecoi=None, name=None, algorithm_parameters=None, significance=None, P_surrogates=None, signals=None, labels=None, extra=None, data_info=None, segment_start_times=None, segment_end_times=None, time_offset=0)[source]

Bases: ResultBase

High-level interface for processing wavelet maps. Can handle CWT, WCT, PCT.

Parameters:

P (np.ndarray) – 2D array with wavelet power or squared coherence values with size (n_freqs, n_time). E.g. for a CWT: P = 1/scales.reshape(-1, 1) * np.abs(W)**2
A (np.ndarray) – 2D array with wavelet phase angles with size (n_freqs, n_time). E.g. for a CWT: A = np.angle(W)
freqs (np.ndarray) – frequencies in Hz corresponding to the first axis of P and A.
fs (float) – sampling frequency (Hz).
wavelet (Mother, str) – Mother object or string specifying which wavelet was used (e.g. ‘Morlet(6)’).
insidecoi (np.ndarray, optional) – boolean array of shape (n_freqs, n_time) containing True values at the cone/mask of influence. True pixels correspond to regions affected by adge/artefact effects. Defaults to None.
name (str, optional) – name for the result, e.g. ‘WCT EEG-NIRS’.
algorithm_parameters (nnsa.Parameters, optional) – see ResultBase.
significance (np.ndarray, optional) – array with same shape as P containing significance values for P between 0 - 1 (0 not significant, 1 significant). If not specified, methods that require significance values will raise errors. Defaults to None.
P_surrogates (np.ndarray, optional) – array with same size as P, with mean surrogate values. Defaults to None.
signals (np.ndarray, optional) – array of shape (n_signals, n_time) containing an arbitrary number of signals that were used in the computation (for visualization purposes). Defaults to None.
extra (dict, optional) – dict with optional extra arrays. E.g. to save some other surrogate values.
labels (tuple, optional) – tuple of length n_signals, with a label for each element in signals, e.g. (‘EEG’, ‘NIRS’). Defaults to None.
data_info (str, optional) – see ResultBase.
segment_start_times (np.ndarray, optional) – see ResultBase.
segment_end_times (np.ndarray, optional) – see ResultBase.
time_offset (float, optional) – see ResultBase.

Attributes:

`W`	Return the complex valued wavelet coefficients.
`dj`	Return 2log-space scale spacing.
`dt`	Return sampling period.
`num_segments`	Return the number of segments/samples.
`scales`	Return the wavelet scales equivalent to self.freqs.
`wavelet`	Return wavelet Mother object.

Methods:

`compute_coi`()	Return mask for the cone of influence at edges.
`downsample`([ratio, how, which, inplace])	Downsample the spectra along the frequency (axis=0) or time (axis=1) axis.
`get_cum_freq_profile`([freq_low, freq_high, ...])	Return the frequency profile.
`get_downsampled`([which, phase_center, ...])
`get_freq_profile`([freq_low, freq_high, ...])	Return the frequency profile.
`get_phase_mask`([A, phase_center, phase_tol])	Return a boolean mask based on the phase.
`get_profile`(which[, freq_low, freq_high, ...])	Return the time or frequency profile.
`get_significance_mask`([significance, alpha])	Return mask where the data is significant.
`get_smoothed`(window, stepsize[, time_scale, ...])	Return smoothed values.
`get_time_profile`([freq_low, freq_high, ...])	Return the frequency profile.
`match_shapes`()	Match shapes of signals (truncate longest one) (inplace).
`plot`([freq_low, freq_high, freq_scale, ...])	Plot the results.
`plot_complex_freq_profile`([freq_low, ...])
`plot_cum_freq_profile`([freq_low, freq_high, ...])	Plot the cumulative frequency profile (is a 2d image).
`plot_freq_profile`([freq_low, freq_high, ...])	Plot the frequency profile.
`plot_phase`([freq_low, freq_high, ...])	Plot the phase.
`plot_phase_discrete`([freq_low, freq_high, ...])	Plot the phase.
`plot_scalogram`([freq_low, freq_high, ...])	Plot the scalogram (contour plot of the wavelet coherence as a function of frequency and time).
`plot_signals`([time_start, time_stop, ...])	Plot the original signals as function of time.
`plot_time_profile`([freq_low, freq_high, ...])	Plot the time profile (i.e.
`shade`(mask[, freq_low, freq_high, ...])	Plot filled contour mask to shade a part of the scalogram.
`to_complex`()	Return complex values C.
`update_coi`(nan_mask, **kwargs)	Update cone of influence by combining it with a MOI based on nan_mask (inplace).

property W: Return the complex valued wavelet coefficients.

compute_coi()[source]: Return mask for the cone of influence at edges.

property dj: Return 2log-space scale spacing.

downsample(ratio=2, how='decimate', which='time', inplace=False)[source]

Downsample the spectra along the frequency (axis=0) or time (axis=1) axis. Does also downsample the signals.

Parameters:

ratio (int) – downsampling ratio.
how (str, optional) – method for downsampling. Options: - ‘decimate’: take every ratio`th sample. - ‘mean’: collapse `ratio consecutive samples into the mean of those samples. - ‘median’: collapse ratio consecutive samples into the median of those samples. Defaults to ‘decimate’.
which (str, optional) – dimension which to downsample. Choose from: - ‘time’ or ‘t’: downsample time dimension. - ‘freq’ or ‘f’: downsample frequency dimension. - ‘both’: downsample both time and frequency dimensions. Defaults to ‘time.
inplace (bool, optional) – if True, operates inplace, else a new object is returned. Defaults to False.

Returns:

wcr (WaveletCoherenceResult) – new WaveletCoherenceResult object containing the filtered signal (if inplace is False).

property dt: Return sampling period.

get_cum_freq_profile(freq_low=None, freq_high=None, freq_scale='Hz', time_start=None, time_stop=None, time_scale='seconds', which='mean', phase_center=None, phase_tol=0.7853981633974483, mask_coi=True)[source]

Return the frequency profile.

Parameters:

freq_low (float, optional) – low frequency to include (in the unit of freq_scale). If None, the minimum available frequency is used. Defaults to None.
freq_high (float, optional) – high frequency to include (in the unit of freq_scale). If None, the maximum available frequency is used. Defaults to None.
freq_scale (str, optional) – frequency scale. Use ‘Hz’, ‘mHz’, ‘seconds’, ‘minutes’. Defaults to ‘Hz’.
time_start (float, optional) – start time to include (in the unit of time_scale). If None, the first available timestamp is used. Defaults to None.
time_stop (float, optional) – end time to include (in the unit of time_scale). If None, the last available timestamp is used. Defaults to None.
time_scale (str, optional) – time scale, see nnsa.data.plotting.convert_time_scale(). Defaults to ‘seconds’.
which (str, optional) – what to plot as a function of frequency. Choose from: - ‘mean’: mean of P. - ‘mean_sig’: mean significance. - ‘frac_sig’: fraction of significant P. - ‘frac_phase’: occurence fraction of the specified phase.
phase_tol (phase_center and) – select phase. See self.get_phase_mask. If None, include all phases.
mask_coi (bool, optional) – ignore samples that are in the COI. Defaults to True.

Returns:

freqs (np.ndarray) – frequencies.
freq_profile (np.ndarray) – time averaged value per frequency.

get_downsampled(which='mean', phase_center=None, phase_tol=0.7853981633974483, time_start=None, time_stop=None, time_win=21600, time_step=None, freq_low=None, freq_high=None, freq_scale='Hz', freq_win=None, freq_step=None, mask_coi=True, max_nan_frac=0.5)[source]

get_freq_profile(freq_low=None, freq_high=None, freq_scale='Hz', time_start=None, time_stop=None, time_scale='seconds', how='mean', phase_center=None, phase_tol=0.7853981633974483, mask_coi=True, max_nan=None, **kwargs)[source]

Return the frequency profile.

Parameters:

self.get_profile(). (See) –

Returns:

freqs (np.ndarray) – frequencies in the specified scale.
freq_profile (np.ndarray) – time averaged value per frequency.

get_phase_mask(A=None, phase_center=None, phase_tol=0.7853981633974483)[source]

Return a boolean mask based on the phase.

Parameters:

A (np.ndarray, optional) – array with phases. If None, takes self.A.
phase_center (float, optional) – center phase.
phase_tol (float, optional) – tolerance around center phase. Phase will be included if larger than (phase_center - phase_tol) and smaller than (phase_center + phase_tol).

Returns:

phase_mask (np.ndarray) – boolean mask for A.

get_profile(which, freq_low=None, freq_high=None, freq_scale='Hz', time_start=None, time_stop=None, time_scale='seconds', how='mean', phase_center=None, phase_tol=0.7853981633974483, mask_coi=True, max_nan=None)[source]

Return the time or frequency profile.

Parameters:

which (str) – ‘time’ or (‘freq’, ‘frequency’, ‘scale’). Determines which profile is returned.
freq_low (float, optional) – low frequency to include (in the unit of freq_scale). If None, the minimum available frequency is used. Defaults to None.
freq_high (float, optional) – high frequency to include (in the unit of freq_scale). If None, the maximum available frequency is used. Defaults to None.
freq_scale (str, optional) – frequency scale. Use ‘Hz’, ‘mHz’, ‘seconds’, ‘minutes’. Defaults to ‘Hz’.
time_start (float, optional) – start time to include (in the unit of time_scale). If None, the first available timestamp is used. Defaults to None.
time_stop (float, optional) – end time to include (in the unit of time_scale). If None, the last available timestamp is used. Defaults to None.
time_scale (str, optional) – time scale, see nnsa.data.plotting.convert_time_scale(). Defaults to ‘seconds’.
how (str, optional) – what to plot as a function of frequency. Choose from: - ‘mean’: mean of P. - ‘median’: median of P. - ‘mean_sig’: mean significance. - ‘median_sig’: median significance. - ‘frac_sig’: fraction of significant P. - ‘frac_phase’: occurence fraction of the specified phase.
phase_tol (phase_center and) – select phase. See self.get_phase_mask. If None, include all phases.
mask_coi (bool, optional) – ignore samples that are in the COI. Defaults to True.

Returns:

x (np.ndarray) – time or frequencies in the specified scale.
profile (np.ndarray) – time or frequency profile.

get_significance_mask(significance=None, alpha=0.05)[source]: Return mask where the data is significant.

get_smoothed(window, stepsize, time_scale='seconds', which='abs_sq', mask_coi=True, max_nan=1, phase_center=None, phase_tol=0.7853981633974483)[source]: Return smoothed values. Choose from abs_sq, abs, real, imag, frac_sig.

get_time_profile(freq_low=None, freq_high=None, freq_scale='Hz', time_start=None, time_stop=None, time_scale='seconds', how='mean', phase_center=None, phase_tol=0.7853981633974483, mask_coi=True, max_nan=None, **kwargs)[source]

Return the frequency profile.

Parameters:

self.get_profile(). (See) –

Returns:

time (np.ndarray) – time in the specified scale.
time_profile (np.ndarray) – frequency averaged value per time.

match_shapes()[source]: Match shapes of signals (truncate longest one) (inplace).

property num_segments

Return the number of segments/samples.

Returns:: (int) – number of segments/samples.

plot(freq_low=None, freq_high=None, freq_scale='Hz', time_start=None, time_stop=None, time_scale='seconds', scalogram_kwargs=None, time_profile_kwargs=None, freq_profile_kwargs=None, signals_kwargs=None, mask_coi=True, fig_kwargs=None)[source]

Plot the results.

Parameters:

freq_low (float, optional) – low frequency to include (in the unit of freq_scale). If None, the minimum available frequency is used. Defaults to None.
freq_high (float, optional) – high frequency to include (in the unit of freq_scale). If None, the maximum available frequency is used. Defaults to None.
freq_scale (str, optional) – frequency scale. Use ‘Hz’, ‘mHz’, ‘seconds’, ‘minutes’. Defaults to ‘Hz’.
time_start (float, optional) – start time to include (in the unit of time_scale). If None, the first available timestamp is used. Defaults to None.
time_stop (float, optional) – end time to include (in the unit of time_scale). If None, the last available timestamp is used. Defaults to None.
time_scale (str, optional) – time scale, see nnsa.data.plotting.convert_time_scale(). Defaults to ‘seconds’.
scalogram_kwargs (dict, optional) – keyword arguments for self.plot_scalogram(). Defaults to None.
time_profile_kwargs (dict, optional) – keyword arguments for self.plot_time_profile(). Defaults to None.
freq_profile_kwargs (dict, optional) – keyword arguments for self.plot_freq_profile(). Defaults to None.
signals_kwargs (dict, optional) – keyword arguments for self.plot_signals(). Defaults to None.
mask_coi (bool, optional) – mask samples that were are inside the cone of influence (COI). Defaults to True.

Returns:

axes handles foe each subplot.

plot_complex_freq_profile(freq_low=None, freq_high=None, freq_scale='Hz', time_start=None, time_stop=None, time_scale='seconds', which='amp_phase', significant_only=False, ax=None, mask_coi=True, **kwargs)[source]

plot_cum_freq_profile(freq_low=None, freq_high=None, freq_scale='Hz', time_start=None, time_stop=None, time_scale='seconds', which='mean', phase_center=None, phase_tol=0.7853981633974483, ax=None, mask_coi=True, **kwargs)[source]

Plot the cumulative frequency profile (is a 2d image).

Parameters:

freq_low (float, optional) – low frequency to include (in the unit of freq_scale). If None, the minimum available frequency is used. Defaults to None.
freq_high (float, optional) – high frequency to include (in the unit of freq_scale). If None, the maximum available frequency is used. Defaults to None.
freq_scale (str, optional) – frequency scale. Use ‘Hz’, ‘mHz’, ‘seconds’, ‘minutes’. Defaults to ‘Hz’.
time_start (float, optional) – start time to include (in the unit of time_scale). If None, the first available timestamp is used. Defaults to None.
time_stop (float, optional) – end time to include (in the unit of time_scale). If None, the last available timestamp is used. Defaults to None.
time_scale (str, optional) – time scale, see nnsa.data.plotting.convert_time_scale(). Defaults to ‘seconds’.
which (str, optional) – what to plot as a function of frequency. Choose from: - ‘mean’: mean of P. - ‘mean_sig’: mean of significance. - ‘frac_sig’: fraction of significant P. - ‘frac_phase’: occurence fraction of the specified phase.
phase_tol (phase_center and) – select phase. See self.get_phase_mask. If None, include all phases.
ax (plt.Axes, optional) – axes object to plot in. If None, plots in the current axes. Defaults to None.
mask_coi (bool, optional) – ignore samples that are in the COI. Defaults to True.
**kwargs (optional) – optional keyword arguments for the plt.contourf function.

plot_freq_profile(freq_low=None, freq_high=None, freq_scale='Hz', time_start=None, time_stop=None, time_scale='seconds', how='mean', phase_center=None, phase_tol=0.7853981633974483, ax=None, orientation='horizontal', mask_coi=True, **kwargs)[source]

Plot the frequency profile.

Parameters:

freq_low (float, optional) – low frequency to include (in the unit of freq_scale). If None, the minimum available frequency is used. Defaults to None.
freq_high (float, optional) – high frequency to include (in the unit of freq_scale). If None, the maximum available frequency is used. Defaults to None.
freq_scale (str, optional) – frequency scale. Use ‘Hz’, ‘mHz’, ‘seconds’, ‘minutes’. Defaults to ‘Hz’.
time_start (float, optional) – start time to include (in the unit of time_scale). If None, the first available timestamp is used. Defaults to None.
time_stop (float, optional) – end time to include (in the unit of time_scale). If None, the last available timestamp is used. Defaults to None.
time_scale (str, optional) – time scale, see nnsa.data.plotting.convert_time_scale(). Defaults to ‘seconds’.
how (str, optional) – what to plot as a function of frequency. Choose from: - ‘mean’: mean of P. - ‘median’: median of P. - ‘frac_sig’: fraction of significant P. - ‘frac_phase’: occurence fraction of the specified phase.
phase_tol (phase_center and) – select phase. See self.get_phase_mask. If None, include all phases.
ax (plt.Axes, optional) – axes object to plot in. If None, plots in the current axes. Defaults to None.
orientation (str, optional) – whether to plot ‘horitontal’ (i.e. frequency on the x-axis), or ‘vertical’ (i.e. frequency on the y-axis). Defaults to ‘horizontal’.
mask_coi (bool, optional) – ignore samples that are in the COI. Defaults to True.
**kwargs (optional) – optional keyword arguments for the plt.contourf function.

plot_phase(freq_low=None, freq_high=None, freq_scale='Hz', time_start=None, time_stop=None, time_scale='seconds', mask_non_significant=True, alpha=0.05, add_colorbar=True, ax=None, cmap=None, **kwargs)[source]

Plot the phase.

Parameters:

freq_low (float, optional) – low frequency to include (in the unit of freq_scale). If None, the minimum available frequency is used. Defaults to None.
freq_high (float, optional) – high frequency to include (in the unit of freq_scale). If None, the maximum available frequency is used. Defaults to None.
freq_scale (str, optional) – frequency scale. Use ‘Hz’, ‘mHz’, ‘seconds’, ‘minutes’. Defaults to ‘Hz’.
time_start (float, optional) – start time to include (in the unit of time_scale). If None, the first available timestamp is used. Defaults to None.
time_stop (float, optional) – end time to include (in the unit of time_scale). If None, the last available timestamp is used. Defaults to None.
time_scale (str, optional) – time scale, see nnsa.data.plotting.convert_time_scale(). Defaults to ‘seconds’.
ax (plt.Axes, optional) – axes object to plot in. If None, plots in the current axes. Defaults to None.
cmap (list, optional) – colopmap.
**kwargs (optional) – optional keyword arguments for the plt.pcolormesh function.

plot_phase_discrete(freq_low=None, freq_high=None, freq_scale='Hz', time_start=None, time_stop=None, time_scale='seconds', plot_significance=True, significance_mode='contour', alpha=0.05, ax=None, mask_coi=True, mask_mode='shade', phases=None, colors=None, **kwargs)[source]

Plot the phase.

Parameters:

freq_low (float, optional) – low frequency to include (in the unit of freq_scale). If None, the minimum available frequency is used. Defaults to None.
freq_high (float, optional) – high frequency to include (in the unit of freq_scale). If None, the maximum available frequency is used. Defaults to None.
freq_scale (str, optional) – frequency scale. Use ‘Hz’, ‘mHz’, ‘seconds’, ‘minutes’. Defaults to ‘Hz’.
time_start (float, optional) – start time to include (in the unit of time_scale). If None, the first available timestamp is used. Defaults to None.
time_stop (float, optional) – end time to include (in the unit of time_scale). If None, the last available timestamp is used. Defaults to None.
time_scale (str, optional) – time scale, see nnsa.data.plotting.convert_time_scale(). Defaults to ‘seconds’.
plot_surrogates (bool, optional) – plot mean profile of the surrogates (if surrogates available). Defaults to False.
ax (plt.Axes, optional) – axes object to plot in. If None, plots in the current axes. Defaults to None.
orientation (str, optional) – whether to plot ‘horitontal’ (i.e. frequency on the x-axis), or ‘vertical’ (i.e. frequency on the y-axis). Defaults to ‘horizontal’.
mask_coi (bool, optional) – ignore samples that are in the COI. Defaults to True.
phases (list, optional) – list with phases classes.
colors (list, optional) – list with colors corresponding to phases.
colors –
**kwargs (optional) – optional keyword arguments for the plt.pcolormesh function.

plot_scalogram(freq_low=None, freq_high=None, freq_scale='Hz', time_start=None, time_stop=None, time_scale='seconds', plot_significance=True, significance_mode='contour', alpha=0.05, ax=None, mask_coi=True, mask_mode='shade', add_colorbar=False, **kwargs)[source]

Plot the scalogram (contour plot of the wavelet coherence as a function of frequency and time).

If surrogate data is available, a significance threshold is computed using the significance level alpha and regions where the coherence exceeds the threshold are encircled with black contours.

Parameters:

freq_low (float, optional) – low frequency to include (in the unit of freq_scale). If None, the minimum available frequency is used. Defaults to None.
freq_high (float, optional) – high frequency to include (in the unit of freq_scale). If None, the maximum available frequency is used. Defaults to None.
freq_scale (str, optional) – frequency scale. Use ‘Hz’, ‘mHz’, ‘seconds’, ‘minutes’. Defaults to ‘Hz’.
time_start (float, optional) – start time to include (in the unit of time_scale). If None, the first available timestamp is used. Defaults to None.
time_stop (float, optional) – end time to include (in the unit of time_scale). If None, the last available timestamp is used. Defaults to None.
time_scale (str, optional) – time scale, see nnsa.data.plotting.convert_time_scale(). Defaults to ‘seconds’.
plot_significance (bool, optional) – plot contour lines alng the significant regions (True) or not (False). Defaults to True.
significance_mode (str, optional) – how to display significance. Choose from: - ‘contour’: draws contour lines at the significance level. - ‘hide’: hides non-significant pixels (shades them darkgrey). Defaults to ‘contour’.
alpha (float, optional) – float between 0 and 1, defining the significance level when computing the significance threshold if surrogate data is available. Defaults to 0.05.
ax (plt.Axes, optional) – axes object to plot in. If None, plots in the current axes. Defaults to None.
mask_coi (bool, optional) – mask samples in the COI. Defaults to True.
mask_mode (str, optional) – choose to ‘remove’ or ‘shade’ nans. Defaults to ‘shade’.
add_colorbar (bool) – whether to add a colorbar to the plot (True) or not (False).
**kwargs (optional) – optional keyword arguments for the plt.contourf function.

plot_signals(time_start=None, time_stop=None, time_scale='seconds', normalize=True, smooth_window=None, ax=None, colors=None, **kwargs)[source]

Plot the original signals as function of time.

Parameters:

time_start (float, optional) – start time to include (in the unit of time_scale). If None, the first available timestamp is used. Defaults to None.
time_stop (float, optional) – end time to include (in the unit of time_scale). If None, the last available timestamp is used. Defaults to None.
time_scale (str, optional) – time scale, see nnsa.data.plotting.convert_time_scale(). Defaults to ‘seconds’.
normalize (bool, optional) – normalize signals (zero mean, unit SD) prior to plotting. Defaults to True.
smooth_window (float) – optional window for moving mean to smooth time signals (in seconds).
ax (plt.Axes, optional) – axes object to plot in. If None, plots in the current axes. Defaults to None.
colors (optional) – Specify one color for all signals (str, array), or one color for each signals (list, tuple, dict).
**kwargs (optional) – optional keyword arguments for the plt.plot function.

plot_time_profile(freq_low=None, freq_high=None, freq_scale='Hz', time_start=None, time_stop=None, time_scale='seconds', plot_surrogates=False, ax=None, mask_coi=True, **kwargs)[source]

Plot the time profile (i.e. coherence averaged over a range of frequencies).

Parameters:

freq_low (float, optional) – low frequency to include (in the unit of freq_scale). If None, the minimum available frequency is used. Defaults to None.
freq_high (float, optional) – high frequency to include (in the unit of freq_scale). If None, the maximum available frequency is used. Defaults to None.
freq_scale (str, optional) – frequency scale. Use ‘Hz’, ‘mHz’, ‘seconds’, ‘minutes’. Defaults to ‘Hz’.
time_start (float, optional) – start time to include (in the unit of time_scale). If None, the first available timestamp is used. Defaults to None.
time_stop (float, optional) – end time to include (in the unit of time_scale). If None, the last available timestamp is used. Defaults to None.
time_scale (str, optional) – time scale, see nnsa.data.plotting.convert_time_scale(). Defaults to ‘seconds’.
plot_surrogates (bool, optional) – plot mean profile of the surrogates (if surrogates available). Defaults to False.
ax (plt.Axes, optional) – axes object to plot in. If None, plots in the current axes. Defaults to None.
mask_coi (bool, optional) – ignore samples that are in the COI. Defaults to True.
**kwargs (optional) – optional keyword arguments for the plt.plot function.

property scales: Return the wavelet scales equivalent to self.freqs.

shade(mask, freq_low=None, freq_high=None, freq_scale='Hz', time_start=None, time_stop=None, time_scale='seconds', color='k', alpha=0.5, ax=None)[source]

Plot filled contour mask to shade a part of the scalogram.

Parameters:: mask (np.ndarray) – binary mask, where True values will be shaded.

to_complex()[source]

Return complex values C.

C = sqrt(P) * exp(Aj)

Returns:: C (np.ndarray) – complex values, came shape as self.P and self.A.

update_coi(nan_mask, **kwargs)[source]

Update cone of influence by combining it with a MOI based on nan_mask (inplace).

Parameters:

nan_mask – see compute_moi.
**kwargs – for compute_moi().

property wavelet: Return wavelet Mother object.

nnsa.feature_extraction.wavelets.convert_freq_scale(freqs, freq_scale, current='Hz')[source]: Convert frequencies in the current scale to some other frequency or time scale.

nnsa.feature_extraction.wavelets.revert_freq_scale(freqs, freq_scale)[source]: Convert frequencies in some other frequency or time scale to Hz.

nnsa.feature_extraction package

Subpackages

Submodules

nnsa.feature_extraction.aeeg module

nnsa.feature_extraction.brain_age module

nnsa.feature_extraction.brain_age_cnn module

nnsa.feature_extraction.common module

nnsa.feature_extraction.connectivity module

nnsa.feature_extraction.correlation module

nnsa.feature_extraction.discontinuity module

nnsa.feature_extraction.dynamic_coupling module

nnsa.feature_extraction.entropy module

nnsa.feature_extraction.envelope module

nnsa.feature_extraction.feature_sets_old module

nnsa.feature_extraction.fractality module

nnsa.feature_extraction.frequency_analysis module

nnsa.feature_extraction.kernels module

nnsa.feature_extraction.result module

nnsa.feature_extraction.sleep_stages module

nnsa.feature_extraction.statistics module

nnsa.feature_extraction.time_domain module

nnsa.feature_extraction.wavelets module

Module contents