nnsa.containers package

Submodules

nnsa.containers.datasets module

Module for creating an object that holds the data of multiple time series, annotations and features.

Classes:

`BaseDataset`(*args[, label])	Base class with common functionalities for Datasets.
`EegDataset`(*args[, label])	High-level interface for processing (multichannel) EEG for neonatal signal analysis.
`OxygenDataset`(*args[, label])	High-level interface for processing oxygen data for neonatal signal analysis.

class nnsa.containers.datasets.BaseDataset(*args, label=None)[source]

Bases: object

Base class with common functionalities for Datasets.

Parameters:

*args (optional) – optional positional arguments may be TimeSeries objects containing signals. Those will be added to the Dataset upon initialization. When a list is given, this list is expected to be a list of TimeSeries objects.
label (str) – optional label for dataset.

Methods:

`append`(data_object)	Append a data object to the Dataset (in place).
`asarray`([channels, return_channel_labels, ...])	Return an array containing (a copy of) multi-channel data with shape (num_channels, num_samples) if channels_last is False.
`astype`(*args[, inplace])
`average_signals`([channels])	Average the signals and return as a new TimeSeries.
`clear`()	Empty the dataset (inplace).
`combine_channels`([channels, label])	Combine the channels into one signal by cutting into segments and pasting the best channels together.
`compute_power_cwt`([freq_low, freq_high, ...])	Compute power in specified band for each signal in the dataset.
`demean`([channels, verbose, inplace])	Demean each time series in the dataset.
`envelope`([verbose])	Compute the envelope of the signals.
`extract_channels`([channels, make_copy])	Extract the specified channels and return them in a new dataset
`extract_default_channels`(**kwargs)	Extract the 9 default channels ([]).
`extract_epoch`([begin, end, channels])	Extract a piece of data in the specified interval.
`fill_nan`([value, inplace])	Fill NaN values in the signals.
`filter`(filter_obj[, channels, inplace, verbose])	Filter each of the signals in the Dataset by calling the filter() method on each TimeSeries objects.
`filter_saved_filter`(filter_name[, channels, ...])	Filter each of the signals in the dataset by calling the filter_saved_filter() method on each TimeSeries object.
`filtfilt`(filter_obj[, channels, inplace, ...])	Filter each of the signals in the Dataset by calling the filtfilt() method on each TimeSeries objects.
`from_data_dict`(data_dict, **kwargs)	Create a dataset based on data in a dict.
`get_non_artefact_masks`(segment_length[, ...])	For each signal get a mask indicating non artefact segments.
`interp`(t[, channels])	Linearly interpolate values.
`interp_nan`(args, *kwargs)
`interpolate_nan`([inplace, max_nan_length])	Linearly interpolate nan values.
`is_synchronized`([channels])	Check if all the TimeSeries in the Dataset are synchronized.
`isempty`()	Check if dataset is empty.
`line_length`([preprocess, verbose])	Compute line length feature.
`logical_and`(other)
`logical_or`(other)
`merge`(other[, inplace])	Merge other BaseDataset object(s) into one object.
`multi_scale_entropy`([preprocess, verbose])	Perform a multi-scale entropy (mse) analysis.
`multifractal_analysis`([verbose])	Perform a multifractal analysis (mfa).
`nan_to_num`([channels, inplace])	Apply numpy's nan_to_num function to each timeseries (e.g.
`normalize`([how, channels, inplace, verbose])	Normalize the data.
`notch_filt`([f0, channels, inplace, verbose])
`plot`(*args[, begin, end, channels, scale, ...])	Plot the data of specified channels for a specifiec time frame.
`power_analysis`([verbose])	Perform a Fourier based power analysis.
`read_hdf5`(filepath[, ds, begin, end])	Read the Dataset object to a .hdf5 file.
`remove`(channel[, inplace, verbose])	Remove a signal from the dataset.
`remove_artefact_channels`([inplace])	Remove channels that do not meet the quality criteria.
`remove_artefacts`([inplace])	Replace samples that are artefacts by np.nan
`remove_flatlines`([inplace, verbose])	Replace flatline samples by np.nan
`remove_neighborhood_artefacts`(*args[, ...])	Replace values by np.nan if samples in their neighborhood are nan.
`remove_outliers`(*args[, inplace, verbose])	Replace outlier samples by np.nan
`remove_values`(*args[, inplace, verbose])	Replace values by np.nan
`resample`(fs_new[, method, channels, ...])	Resample the signals in this Dataset to new sampling frequency fs_new.
`save_hdf5`(filepath[, overwrite])	Save the Dataset object to a .hdf5 file.
`segment`(segment_length[, overlap])	Return a segment generator that segments the signals in the dataset (into smaller time segments).
`set_time_offset`(time_offset[, inplace])	Set the same time offset to all time series.
`signal_stats`([verbose])	Compute signal statistics.
`squeeze`()	Returns the TimeSeries if only one TimeSeries in the Dataset.
`stepwise_moving_average`(*args[, avg_fun])
`stepwise_reduce`(*args[, channels, inplace])	Compute stepwise values for the signals in this Dataset.
`to_time_series`([make_copy])	If the Dataset contains only one TimeSeries, return this.
`transform`(fun[, channels, inplace])	Apply a custom function to each signal in the dataset.

Attributes:

`channel_labels`	Return a list of channel labels (labels of the time series objects).
`dtype`	Return the dtype if all TimeSeries have the same dtype.
`fs`	Return the sample frequency if all TimeSeries have the same sample frequency.
`info`	Return the info dict of first signal in dataset.
`shape`	Return the shape (n_channels, n_samples).
`time`	Return the time array if all TimeSeries have the same length, sample frequency and time_offset.
`time_offset`	Return the time offset if all TimeSeries have the same time offset.
`time_series`	Return the TimeSeries objects of the Dataset object.
`unit`	Return the unit if all TimeSeries have the same unit.

append(data_object)[source]

Append a data object to the Dataset (in place).

Valid data objects:: TimeSeries

Parameters:: data_object (various) – an nnsa data object. If data_object is a list, this function will recursively be called on each item in the list such that data_object may also be a list of nnsa data objects.

asarray(channels=None, return_channel_labels=False, channels_last=False)[source]

Return an array containing (a copy of) multi-channel data with shape (num_channels, num_samples) if channels_last is False.

Parameters:

channels (list, optional) – list with labels of the signals that are put into the output array. The order of the labels determines the order of the signals in the output array. I.e. the signal with label labels[i] is put in array(i, :). If None, all signals in the EegDataset are put in the output array. Defaults to None.
return_channel_labels (bool, optional) – if True, additionally outputs the labels that correspond with the rows of the created array. If False, only outputs the array. Default is False.
channels_last (bool) – if False, output shape is (num_channels, num_samples), if True, output shape is (num_samples, num_channels).

Returns:

array (np.ndarray) – array with shape (num_channels, num_samples) if channels_last == False, containing (copies of) the multi-channel data.
channels (list, optional) – the labels corresponding to the rows in the output array (only if output_channel_labels is True).

astype(*args, inplace=False, **kwargs)[source]

average_signals(channels=None, **kwargs)[source]

Average the signals and return as a new TimeSeries.

Raises an error if the signals are not synchronized.

Parameters:

channels (list, optional) – list with labels of the signals to be average. If None, all signals in the Dataset are averaged. Defaults to None.
**kwargs (optional) – keyword arguments for the creation of a the new TimeSeries object.

Returns:

(nnsa.TimeSeries) – new TimeSeries object containing the average signal.

property channel_labels

Return a list of channel labels (labels of the time series objects).

Returns:: (list) – list with channel labels.

clear()[source]: Empty the dataset (inplace).

combine_channels(channels=None, label=None, **kwargs)[source]

Combine the channels into one signal by cutting into segments and pasting the best channels together.

See nnsa.combine_channels().

Parameters:

channels (list, optional) – list with labels of the signals to be combined. If None, all signals in the Dataset are combined. Defaults to None.
label (str, optional) – a label for the combined time series.
**kwargs (optional) – keyword arguments for nnsa.combine_channels().

Returns:

ts (nnsa.TimeSeries) – TimeSeries object containing the combined signal.

compute_power_cwt(freq_low=None, freq_high=None, channels=None, inplace=False, **kwargs)[source]

Compute power in specified band for each signal in the dataset.

Parameters:

freq_low (float, optional) – lower frequency cutoff for bandpower. If None, takes lowest possible.
freq_high (float, optional) – upper frequency cutoff for bandpower. If None, takes highest possible.
channels (list, optional) – list with labels of the signals to apply to. If None, all signals in the Dataset are processed. Defaults to None.
inplace (bool, optional) – if True, replaces the signals in place by their power. If False, returns a new object.
**kwargs (optional) – optional keyword arguments for compute_power_cwt().

Returns:

ds (BaseDataset) – dataset with power of the signals (if inplace is False).

demean(channels=None, verbose=1, inplace=False, **kwargs)[source]: Demean each time series in the dataset.

property dtype

Return the dtype if all TimeSeries have the same dtype. Raises an error otherwise.

Returns:: dtype – dtype common to all signals.

envelope(verbose=1, **kwargs)[source]

Compute the envelope of the signals.

This is a wrapper that prepares the input for Envelope.envelope() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the Envelope class.

Returns:

result (nnsa.EnvelopeResult) – the result of the envelope computation.

Examples

To get the envelope data as a EegDataset: >>> signal = 4 * np.sin(np.arange(10000)) >>> ts = TimeSeries(signal=signal, fs=100, label=’EEG Cz’, unit=’uV’, info={‘source’: ‘random’}) >>> ds = BaseDataset([ts]) >>> envelope_result = ds.envelope(verbose=0) >>> ds_envelope = envelope_result.to_eeg_dataset() >>> print(type(ds_envelope).__name__) EegDataset

>>> print(ds_envelope.time_series['EEG Cz'].signal.mean())
3.9998155220627787

extract_channels(channels=None, make_copy=True)[source]

Extract the specified channels and return them in a new dataset

Parameters:

channels (list) – labels of channels to return.
make_copy (bool) – whether to make a copy of the TimeSeries objects or not. If False and a TimeSeries object in the output dataset is mutated, that TimeSeries in the input dataset is alse mutated.

Returns:

ds_out (Dataset) – new dataset with the requested channels.

Raises:

ValueError if channels do not exist. –

extract_default_channels(**kwargs)[source]

Extract the 9 default channels ([]).

Parameters:: **kwargs – for self.extract_channels().
Returns:: ds_out (Dataset) – new dataset with the requested channels.

extract_epoch(begin=None, end=None, channels=None, **kwargs)[source]

Extract a piece of data in the specified interval.

Parameters:

begin (float, optional) – start time in seconds (including time_offset) of the epoch to extract. If negative, begin is duration + begin (python-like indexing). If None, the beginning of the signals is taken. Defaults to None.
end (float, optional) – end time in seconds (including time_offset) of the epoch to extract. If negative, the end is duration + end (python-like indexing). If None, the end of the signal is taken. Must point to a time greater than begin. Defaults to None.
channels (list, optional) – list signal labels to extract an epoch from. If None, all channels are taken. Defaults to None.
**kwargs (dict, optional) – for self.__init__().

Returns:

ds_epoch (nnsa.BaseDataset) – a new Dataset with only the data of the specified epoch.

fill_nan(value=0, inplace=False, **kwargs)[source]

Fill NaN values in the signals.

Parameters:

value (float) – value to fill nans with.
inplace (bool) – whether to fill nans in place or create a new object.
**kwargs – for TimeSeries.fill_nan().

Returns:

ds (BaseDataset) – new Dataset object containing the new signals (only if inplace is False).

filter(filter_obj, channels=None, inplace=False, verbose=1, **kwargs)[source]

Filter each of the signals in the Dataset by calling the filter() method on each TimeSeries objects.

Parameters:

filter_obj (FilterBase-derived) – a child class from the nnsa.FilterBase class. The fs property does not need to be set, will be done automatically.
channels (list, optional) – list with labels of the signals that should be filtered. If None, all signals in the Dataset are filtered. Defaults to None.
inplace (bool, optional) – if True, the filtered signals will replace the original signals in this Dataset. If False (default), the function returns a new Dataset object containing the filtered signals, leaving the data in the current Dataset unchanged. Note that if only certain channels are filtered, the newly created Dataset object will only contain those filtered channels.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – keyword arguments for TimeSeries.filter().

Returns:

(BaseDataset) – new Dataset object containing the filtered signals (only if inplace is False).

filter_saved_filter(filter_name, channels=None, inplace=False, verbose=1, **kwargs)[source]

Filter each of the signals in the dataset by calling the filter_saved_filter() method on each TimeSeries object.

Parameters:

filter_name (str) – see nnsa.preprocessing.filter_saved_filter().
channels (list, optional) – list with labels of the signals that should be filtered. If None, all signals in the Dataset are filtered. Defaults to None.
inplace (bool, optional) – if True, the filtered signals will replace the original signals in this Dataset. If False (default), the function returns a new Dataset object containing the filtered signals, leaving the data in the current Dataset unchanged. Note that if only certain channels are filtered, the newly created Dataset object will only contain those filtered channels.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – keyword arguments for TimeSeries.filter_saved_filter().

Returns:

(BaseDataset) – new Dataset object containing the filtered signals (only if inplace is False).

filtfilt(filter_obj, channels=None, inplace=False, verbose=1, **kwargs)[source]

Filter each of the signals in the Dataset by calling the filtfilt() method on each TimeSeries objects.

Parameters:

filter_obj (FilterBase-derived) – a child class from the nnsa.FilterBase class. The fs property does not need to be set, will be done automatically.
channels (list, optional) – list with labels of the signals that should be filtered. If None, all signals in the Dataset are filtered. Defaults to None.
inplace (bool, optional) – if True, the filtered signals will replace the original signals in this Dataset. If False (default), the function returns a new Dataset object containing the filtered signals, leaving the data in the current Dataset unchanged. Note that if only certain channels are filtered, the newly created Dataset object will only contain those filtered channels.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – keyword arguments for TimeSeries.filtfilt().

Returns:

(BaseDataset) – new Dataset object containing the filtered signals (only if inplace is False).

from_data_dict(data_dict, **kwargs)[source]

Create a dataset based on data in a dict.

Parameters:

dict( (data_dict =) – data=data, # 2D array with shape (n_channels, n_samples) fs=fs, # sampling frequency (Hz) label=label, # Optional list of labels for each channel in data filepath=filepath, # Optional filepath where the data comes from t0=t0, # Optional time offset (time at t0) in seconds.
**kwargs – for self.__init__().
) –

property fs

Return the sample frequency if all TimeSeries have the same sample frequency. Raises an error otherwise.

Returns:: fs (flaot) – sample frequency common to all signals.

get_non_artefact_masks(segment_length, overlap=0, artefact_criteria=None)[source]

For each signal get a mask indicating non artefact segments.

Parameters:

segment_length (float) – segment length.
overlap (float, optional) – overlap between segments. Defaults to 0.
artefact_criteria (dict) – dict with artefact criteria for determining whether each segment is an artefact.

Returns:

ds_out (BaseDataset) – new dataset with non artefact masks for each signal.

property info

Return the info dict of first signal in dataset.

Returns:: info (dict) – info dict of first signal in dataset.

interp(t, channels=None, **kwargs)[source]

Linearly interpolate values.

Parameters:

t (np.ndarray) – time instances at which to evaluate the signals.
channels (list) – determines which and the order of the channels that are interpolated. If None, uses all available channels.
**kwargs – for TimeSeries.interp().

Returns:

data (np.ndarray) – 2D array with shape (n_channels, len(t)) containing the interpolated data.

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

interpolate_nan(inplace=False, max_nan_length=None)[source]

Linearly interpolate nan values.

Parameters:

inplace (bool, optional) – interpolate inplace (True) or return a copy (False). Defaults to False.
max_nan_length (int or str, optional) – number of maximum allowable consecutive nan samples that we interpolate (in seconds). If ‘auto’, the average duration of a constant value in the signal is taken. If None, no limit is applied, i.e. all nans are interpolated. Defaults to None.

Returns:

ds (BaseDataset) – dataset with nans interpolated (if inplace is False).

is_synchronized(channels=None)[source]

Check if all the TimeSeries in the Dataset are synchronized.

Parameters:: channels (list, optional) – list with labels of signals to check. If None, all signals are checked. Defaults to None.
Returns:: (bool) – True if all TimeSeries are in sync, False if not.

isempty()[source]

Check if dataset is empty.

Returns:: (bool) – True if the Dataset is empty, False if not.

line_length(preprocess=False, verbose=1, **kwargs)[source]

Compute line length feature.

This is a wrapper that prepares the input for LineLength.line_length() and returns the result.

Parameters:

preprocess (bool, optional) – apply a default preprocessing routine on the data before feature computation (True) or not (False). Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the LineLength class.

Returns:

result (nnsa.LineLengthResult) – the result of the line length computation.

logical_and(other)[source]

logical_or(other)[source]

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

Merge other BaseDataset object(s) into one object.

Parameters:

other (BaseDataset or list) – list with (compatible) BaseDataset objects. Must contain the same TimeSeries (with same labels and fs) as self.
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:

out (BaseDataset) – new BaseDataset object containing the merged data (if inplace is False).

multi_scale_entropy(preprocess=False, verbose=1, **kwargs)[source]

Perform a multi-scale entropy (mse) analysis.

This is a wrapper that prepares the input for MultiScaleEntropy.multi_scale_entropy() and returns the result.

Parameters:

preprocess (bool, optional) – apply a default preprocessing routine on the data before feature computation (True) or not (False). Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the MultiScaleEntropy class.

Returns:

result (nnsa.MultiScaleEntropyResult) – the result of the mse analysis.

multifractal_analysis(verbose=1, **kwargs)[source]

Perform a multifractal analysis (mfa).

This is a wrapper that prepares the input for MultifractalAnalysis.multifractal_analysis() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the MultifractalAnalysis class.

Returns:

result (nnsa.MultifractalAnalysisResult) – the result of the mfa analysis.

nan_to_num(channels=None, inplace=False, **kwargs)[source]

Apply numpy’s nan_to_num function to each timeseries (e.g. to replace nans by zeros).

Parameters:

channels (list) – see self.transform.
inplace (bool) – see self.transform.
**kwargs (optional) – kwargs for self.transform.

normalize(how='zscore', channels=None, inplace=False, verbose=0, **kwargs)[source]

Normalize the data.

Parameters:

how (str) – how to normalize. Choose from: - “zscore”
channels (list, optional) – which channels to normalize. If None, all channels are normalized.
inplace (bool, optional) – whether to normalize inplace (True) or not.
verbose (int, optional) – verbosity level.
**kwargs (dict) – for TimeSeries.normalize().

Returns:

(BaseDataset) – new Dataset object (only returned if inplace is False).

notch_filt(f0=50, channels=None, inplace=False, verbose=1, **kwargs)[source]

plot(*args, begin=None, end=None, channels=None, scale=None, relative_time=False, time_scale='seconds', add_offsets=False, ticklabels=True, subplots=False, color=None, legend=True, ax=None, **kwargs)[source]

Plot the data of specified channels for a specifiec time frame.

Plots in the current axis.

Parameters:

*args (optional) – optional arguments for the plt.plot() function.
begin (float, optional) – begin time in seconds (incl. offset). If None, plots from the first sample. Defaults to None.
end (float, optional) – end time in seconds or None to specify the end of the entire signal. Relative to the beginning of the loaded signal ignores any offset. Defaults to None.
channels (list, optional) – list of labels specifying the signals to plot. If None, all signals in the Dataset are plotted. Defaults to None.
relative_time (bool, optional) – if True, the time axis is relative to the start of the segment to plot. If False, the time axis will correspond to the time in the recording.
time_scale (str, optional) – the time scale to use. Choose from ‘seconds’, ‘minutes’, ‘hours’. Defaults to ‘seconds’.
add_offsets (bool, optional) – if True, adds y offsets, based on signal SD, to each of the channels for easier visualization. If False, does not apply any offsets. If a float, adds this offset to each channel.
ticklabels (bool, optional) – if add_offsets is True, set ticklabels to True to put the signal labels as yticks. Set to False to keep numeric y-labels.
subplots (bool, optional) – if True, plots each signal in a separate subplot. If False, plots all signals in ax`. Defaults to False.
color (list or dict, optional) – list or dictionary woth colors for each TimeSeries in the Dataset.
legend (bool, optional) – include legend (True) or not (False) if subplots is False. Defaults to True.
ax (plt.Axes, optional) – axes object to plot in. If None, plots in the current axes. If subplots is True, always plots in a new figure. Defaults to None.
**kwargs (optional) – optional keyword arguments for the plt.plot() function.

Returns:

ax (plt.axes) – axes instance.

power_analysis(verbose=1, **kwargs)[source]

Perform a Fourier based power analysis.

This is a wrapper that prepares the input for PowerAnalysis.power_analysis() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the PowerAnalysis class.

Returns:

result (nnsa.PowerAnalysisResult) – the result of the power analysis.

static read_hdf5(filepath, ds=None, begin=None, end=None, **kwargs)[source]

Read the Dataset object to a .hdf5 file.

Parameters:

filepath (str) – filepath to read.
begin (float, optional) – start second (wrt time offset).
end (float, optional) – end second (wrt time offset).
ds (optional) – Dataset object to append the data to. If None, creates a BaseDataset object.
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ds (nnsa.BaseDataset) – Dataset object with data read from the file.

Examples

>>> signal = np.random.rand(8, 1000)
>>> ds = BaseDataset()
>>> ts_all = [TimeSeries(signal=signal[i], fs=10, label=i) for i in range(len(signal))]
>>> ds.append(ts_all)
>>> ds.save_hdf5('testfile.hdf5')
>>> ds_read = BaseDataset.read_hdf5('testfile.hdf5')
>>> ds_read_epoch = BaseDataset.read_hdf5('testfile.hdf5', begin=10, end=20)
>>> os.remove('testfile.hdf5')
>>> _ = [assert_equal(ts.signal, ts_read.signal) for ts, ts_read in zip (ds, ds_read)]
>>> _ = [assert_equal(ts.signal, ts_read.signal) for ts, ts_read in zip (ds.extract_epoch(begin=10, end=20), ds_read_epoch)]

remove(channel, inplace=False, verbose=1)[source]

Remove a signal from the dataset.

Parameters:

channel (str) – label of the channel to remove.
inplace (bool, optional) – If True, the channel is removed directly from the EegDataset object itself. If False, the function returns a copy of the original EegDataset object in which the specified channel is removed, leaving the data in the current EegDataset unchanged. Default is False.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(BaseDataset) – new Dataset object containing the same signals, except for the removed channel (only if inplace is False).

remove_artefact_channels(inplace=False, **kwargs)[source]

Remove channels that do not meet the quality criteria.

Parameters:

inplace (bool, optional) – If True, the channel is removed directly from the Dataset object itself. If False, the function returns a copy of the original Dataset object in which the artefacted channels are removed, leaving the data in the current Dataset unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for overruling default signal quality criteria (see nnsa.artefacts.artefact_detection.detect_artefact_signals()).

Returns:

(EegDataset) – new Dataset object containing the same signals, except for the removed channels (only if inplace is False).

remove_artefacts(inplace=False, **kwargs)[source]

Replace samples that are artefacts by np.nan

Parameters:

inplace (bool, optional) – If True, the samples are replaced directly from the Dataset object itself. If False, the function returns a copy of the original Dataset object in which the artefacted samples are replaced, leaving the data in the current Dataset unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for overruling default sample quality criteria (see nnsa.artefacts.artefact_detection.detect_artefact_samples()).

Returns:

(BaseDataset) – new Dataset object containing the same signals, but with artefacted samples changed to np.nan (only returned if inplace is False).

remove_flatlines(inplace=False, verbose=1, **kwargs)[source]

Replace flatline samples by np.nan

Parameters:

inplace (bool, optional) – If True, the samples are replaced directly from the Dataset object itself. If False, the function returns a copy of the original Dataset object in which the flatline samples are replaced, leaving the data in the current Dataset unchanged. Default is False.
verbose (int) – verbosity level.
**kwargs (optional) – optional keyword arguments for TimeSeries.remove_flatlines().

Returns:

(BaseDataset) – new Dataset object containing the same signals, but with flatline samples changed to np.nan (only returned if inplace is False).

remove_neighborhood_artefacts(*args, inplace=False, verbose=1, **kwargs)[source]

Replace values by np.nan if samples in their neighborhood are nan.

Parameters:

*args – arguments for TimeSeries.remove_neighborhood_artefacts().
inplace (bool, optional) – If True, the samples are replaced directly from the Dataset object itself. If False, the function returns a copy of the original Dataset object in which the samples are replaced, leaving the data in the current Dataset unchanged. Default is False.
verbose (int) – verbosity level.
**kwargs (optional) – optional keyword arguments for TimeSeries.remove_neighborhood_artefacts().

Returns:

(BaseDataset) – new Dataset object containing the same signals, but with specific samples changed to np.nan (only returned if inplace is False).

remove_outliers(*args, inplace=False, verbose=1, **kwargs)[source]

Replace outlier samples by np.nan

Parameters:

*args – arguments for TimeSeries.remove_outliers().
inplace (bool, optional) – If True, the samples are replaced directly from the Dataset object itself. If False, the function returns a copy of the original Dataset object in which the samples are replaced, leaving the data in the current Dataset unchanged. Default is False.
verbose (int) – verbosity level.
**kwargs (optional) – optional keyword arguments for TimeSeries.remove_outliers().

Returns:

(BaseDataset) – new Dataset object containing the same signals, but with anomaly samples changed to np.nan (only returned if inplace is False).

remove_values(*args, inplace=False, verbose=1, **kwargs)[source]

Replace values by np.nan

Parameters:

*args – arguments for TimeSeries.remove_values().
inplace (bool, optional) – If True, the samples are replaced directly from the Dataset object itself. If False, the function returns a copy of the original Dataset object in which the samples are replaced, leaving the data in the current Dataset unchanged. Default is False.
verbose (int) – verbosity level.
**kwargs (optional) – optional keyword arguments for TimeSeries.remove_values().

Returns:

(BaseDataset) – new Dataset object containing the same signals, but with specific samples changed to np.nan (only returned if inplace is False).

resample(fs_new, method='polyphase_filtering', channels=None, inplace=False, verbose=1, **kwargs)[source]

Resample the signals in this Dataset to new sampling frequency fs_new.

Parameters:

fs_new (float) – new sampling frequency to resample to.
method (str, optional) – see nnsa.TimeSeries.resample()
channels (list, optional) – list with labels of the signals to be resampled. If None, all signals in the Dataset are resampled. Defaults to None.
inplace (bool, optional) – if True, the resampled signals will replace the original signals in this Dataset. If False (default), the function returns a new Dataset object containing the resampled signals, leaving the data in the current Dataset unchanged. Note that if only certain channels are resampled, the newly created Dataset object will only contain those resampled channels.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – see nnsa.TimeSeries.resample()

Returns:

(BaseDataset) – new Dataset object containing the resampled signals (only if inplace is False).

save_hdf5(filepath, overwrite=False)[source]

Save the Dataset object to a .hdf5 file.

Parameters:

filepath (str) – filepath to save to.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists and mode is ‘w’. Defaults to False.

segment(segment_length, overlap=0)[source]

Return a segment generator that segments the signals in the dataset (into smaller time segments).

Only works is all signals have the same sample frequency.

Parameters:

segment_length (float) – length of a segment in seconds.
overlap (float, optional) – overlap between succesive segments in seconds. Defaults to 0.

Yields:

(BaseDataset) – Dataset object holding the signals of the next segment.

set_time_offset(time_offset, inplace=False)[source]

Set the same time offset to all time series.

Parameters:

time_offset (float) – time offset to set.
inplace (bool, optional) – whether to set in place (True) or create a new object (False). Defaults to False.

Returns:

ds_out (BaseDataset) – new dataset with time offset set to all time series (if inplace is True).

property shape

Return the shape (n_channels, n_samples).

Raises an error if not all signals have the same lengths.

signal_stats(verbose=1, **kwargs)[source]

Compute signal statistics.

This is a wrapper that prepares the input for SignalStats.signal_stats() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the SignalStats class.

Returns:

result (nnsa.SignalStatsResult) – object containing the signal stats.

squeeze()[source]: Returns the TimeSeries if only one TimeSeries in the Dataset. Otherwise returns the Dataset itself.

stepwise_moving_average(*args, avg_fun=<function nanmean>, **kwargs)[source]

stepwise_reduce(*args, channels=None, inplace=False, **kwargs)[source]

Compute stepwise values for the signals in this Dataset.

Parameters:

*args – inputs for nnsa.TimeSeries.stepwise_reduce()
channels (list, optional) – list with labels of the signals to apply to. If None, all signals in the Dataset are processed. Defaults to None.
inplace (bool, optional) – if True, the new signals will replace the original signals in this Dataset. If False (default), the function returns a new Dataset object containing the new signals, leaving the data in the current Dataset unchanged. Note that if only certain channels are processed, the newly created Dataset object will only contain those processed channels.
**kwargs (optional) – keyword arguments for nnsa.TimeSeries.stepwise_reduce()

Returns:

(BaseDataset) – new Dataset object containing the new signals (only if inplace is False).

property time

Return the time array if all TimeSeries have the same length, sample frequency and time_offset. Raises an error otherwise.

Returns:: time (np.ndaaray) – time array common to all signals.

property time_offset

Return the time offset if all TimeSeries have the same time offset. Raises an error otherwise.

Returns:: time_offset (flaot) – time offset in seconds common to all signals.

property time_series

Return the TimeSeries objects of the Dataset object.

Returns:: (dict) – the TimeSeries objects in the Dataset object, where the keys are the TimeSeries labels and the values the corresponding TimeSeries objects.

to_time_series(make_copy=False)[source]

If the Dataset contains only one TimeSeries, return this. Otherwise raise a ValueError.

Parameters:: make_copy (bool, optional) – if True, the returned TimeSeries is a copy of the TimeSeries in self. If False, no copy is made.
Returns:: ts (TimeSeries) – nnsa TimeSeries object.

transform(fun, channels=None, inplace=False)[source]

Apply a custom function to each signal in the dataset.

Parameters:

fun (function) – function that transform the data. Takes in a 1D array and returns a 1D array.
channels (list, optional) – list with labels of the signals to transform. If None, all signals in the Dataset are transformed. Defaults to None.
inplace (bool) – transform the data inplace (True) or return a new dataset instance (False).

Returns:

ds (BaseDataset) – dataset with the transformed data (if inplace is False).

property unit

Return the unit if all TimeSeries have the same unit. Raises an error otherwise.

Returns:: unit (str) – unit common to all signals.

class nnsa.containers.datasets.EegDataset(*args, label=None)[source]

Bases: BaseDataset

High-level interface for processing (multichannel) EEG for neonatal signal analysis.

Methods:

`amplitude_eeg`([channel_1, channel_2, verbose])	Compute amplitude-integrated EEG (aEEG) from single bipolar channel continuous EEG.
`as_brain_rt`([bp_filter])	Preprocess the data to make it similar to the view as in BrainRT.
`brain_age_rf`([verbose])	Compute the brain age from the EEG using the random forest approach.
`brain_age_sinc`([verbose])	Compute the brain age from the EEG using the deep Sinc network.
`burst_detection`([create_bipolar_channels, ...])	Perform burst detection on all channels in the dataset.
`clamp`([threshold, channels, inplace, verbose])	Clamp EEG values by applying a clamping function to reduce dynamic range.
`coherence_graph`([preprocess, verbose])	Compute a connectivity graph, where the weights of the edges are based on the coherence between channels.
`compute_features`([verbose, chunk_size])	Compute EEG feature set.
`create_bipolar_channel`(channel_1, channel_2)	Create a bipolar channel by subtracting channel_2 from channel_1, i.e. bipolar channel = channel_1 - channel_2.
`create_bipolar_channels`(channels_1, channels_2)	Create a set of bipolar channels by subtracting channels_2 from channels_1.
`detect_anomalous_channels`([window, ...])	Simple method to detect anomalous high-frequency/amplitude channels by setting a threshold on the line length.
`detect_artefacts`([multi_channel_cnn, verbose])	Helper function to quickly detect artefacts using a combination of methods (see code).
`detect_artefacts_amplitude`(threshold_high[, ...])	Detect locations of artefacts by settings thresholds on the running mean/maximum of the absolute amplitude.
`detect_artefacts_amplitude_kaupilla`([...])	Detect locations of artefacts by settings thresholds on the amplitude as proposed by Kaupilla et al. 2018.
`detect_artefacts_cnn`([preprocess, ...])	Detect locations of artefacts based on clean EEG detection with CNN.
`detect_artefacts_kota`([notch_filter, bp_filter])	Simple method to detect small and large amplitude artefacts.
`detect_artefacts_method`(how, **kwargs)	Shortcut to any of the artefact removal functions.
`detect_artefacts_rfc`([pma, preprocess, verbose])	Detect locations of artefacts based on a sample supervised random forest classifier from the artefact_detection package.
`filter`(*args[, remove_mean])	Calls the parent function, but with remove_mean set to True by default.
`filter_saved_filter`(*args[, remove_mean])	Calls the parent function, but with remove_mean set to True by default.
`filtfilt`(*args[, remove_mean])	Calls the parent function, but with remove_mean set to True by default.
`from_array`(eeg, fs[, channel_labels])	Create an EegDataset from a 2D array (channels x time).
`get_channel`(channel[, make_copy])	Return a channel as TimeSeries.
`get_segments`(segment_length[, overlap, ...])	Segment the EEG data and return the segmented data as a 3D array.
`kirubin_features`([reference_channel, ...])	Compute Kirubin's feature set.
`mean`([channels, label])	Return the nanmean of the specified channels as a TimeSeries.
`median`([channels, label])	Return the nanmedian of the specified channels as a TimeSeries.
`notch_filt`(*args[, remove_mean])	Calls the parent function, but with remove_mean set to True by default.
`plot`([begin, end, channels, color, scale, ...])	Plot the EEG data of specified channels for a specifiec time frame.
`plot_mask`(mask[, time_scale, color, ...])	Plot a shaded mask over an EEG plot.
`power_analysis`([verbose])	Calls the paretn method, but sets some common frequency bands for EEG.
`read_begin_end_time`(filepath)	Read the start and end time (wrt time offset) of the EEG data in a HDF5 file.
`read_edf`(filepath[, begin, end])	Read an EegDataset object from an .edf file.
`read_hdf5`(filepath[, begin, end])	Read an EegDataset object from an .hdf5 file.
`read_mat`(filepath[, begin, end, loadmat_kwargs])	Read an EegDataset object from a .mat file.
`read_pickle`(filepath[, begin, end])	Read an EegDataset object from a .pkl file.
`read_set`(filepath[, begin, end, loadmat_kwargs])	Read an EegDataset object from a .set file (from Matlab EEGLAB).
`reference`([reference_channel, ...])	Reference all EEG signals to reference_channel, i.e. subtract the signal of the reference_channel from all other EEG channels.
`remove_artefact_channels`([inplace])	Remove channels that do not meet the quality criteria.
`remove_artefacts_amplitude`([notch_filter, ...])	Remove artefacts as detected by self.detect_artefacts_amplitude().
`remove_artefacts_derivative`([threshold, inplace])	Remove artefacts based on a threshold on the derivative of the filtered signal.
`remove_artefacts_kota`([notch_filter, ...])	Remove artefacts as detected by self.detect_artefacts_kota().
`remove_artefacts_mask`(mask_ds[, inplace])	Insert nans where boolean mask is True.
`remove_artefacts_method`(how, **kwargs)	Shortcut to any of the artefact removal functions.
`remove_artefacts_rfc`(pma[, preprocess, inplace])	Remove artefacts based on a sample supervised random forest classifier from the artefact_detection package.
`save_csv`(filepath[, overwrite])	Save the EegDataset data to a .csv (comma-separated value) file.
`save_hdf5`(filepath[, mode, overwrite])	Save the EegDataset data to a .hdf5 file.
`save_mat`(filepath[, overwrite])	Save the EegDataset data to a .mat file.
`save_pickle`(filepath[, overwrite])	Save the EegDataset data to a .pkl (pickle) file.
`sleep_stages_cnn`([preprocess, remove_flats, ...])	Automatic sleep stage classification using a Convolutional Neural Network.
`sleep_stages_robust`([verbose])	Automatic robust sleep stage classification.
`substitute_bad_channels`(af_mask[, inplace])	Find segments with bad channels in the EEG and substitute by the mean of the good channels.

Attributes:

signal

Return the EEG data as a numpy array (channels, time).

amplitude_eeg(channel_1='EEG C3', channel_2='EEG C4', verbose=1, **kwargs)[source]

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

Use on raw EEG data.

Parameters:

channel_1 (str, optional) – the label of the first channel. Defaults to ‘EEG C3’.
channel_2 (str, optional) – the label of the second channel (will be subtracted from the first channel). Defaults to ‘EEG C4’.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the AmplitudeEeg class.

Returns:

result (nnsa.AmplitudeEegResult) – object containing the aEEG.

as_brain_rt(bp_filter=True)[source]

Preprocess the data to make it similar to the view as in BrainRT.

Creates bipolar channels and filter.

Parameters:: bp_filter (bool) – if True, filter the data as in Brain RT (with a first order bandpass Butterworth).
Returns:: eeg_ds (nnsa.EegDataset) – preprocessed dataset (new object).

brain_age_rf(verbose=1, **kwargs)[source]

Compute the brain age from the EEG using the random forest approach.

Use on raw EEG data.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the BrainAge class.

Returns:

result (BrainAgeResult) – object containing the brain age.

brain_age_sinc(verbose=1, **kwargs)[source]

Compute the brain age from the EEG using the deep Sinc network.

Use on raw EEG data.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the BrainAgeSinc class.

Returns:

result (BrainAgeResult) – object containing the brain age.

burst_detection(create_bipolar_channels=True, verbose=1, **kwargs)[source]

Perform burst detection on all channels in the dataset.

This is a wrapper that prepares the input for BurstDetection.burst_detection() and returns the result.

Parameters:

create_bipolar_channels (bool, optional) – if True, automatically create bipolar channels according to the method used. If False, run the algorithm on the channels as currently in the object. Defaults to True.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the BurstDetection class.

Returns:

result (nnsa.BurstDetectionResult) – the result of the burst detection.

clamp(threshold=250, channels=None, inplace=False, verbose=1)[source]

Clamp EEG values by applying a clamping function to reduce dynamic range.

Parameters:

threshold (float) – threshold for the clamping function.
inplace (bool, optional) – whether to apply inplace (True) or not.
verbose (int, optional) – verbosity level.

Returns:

ds_out (EegDataset) – new Dataset object (only returned if inplace is False).

coherence_graph(preprocess=False, verbose=1, **kwargs)[source]

Compute a connectivity graph, where the weights of the edges are based on the coherence between channels.

This is a wrapper that prepares the input for CoherenceGraph.coherence_graph() and returns the result.

Parameters:

preprocess (bool, optional) – apply a default preprocessing routine on the data before feature computation (True) or not (False). Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the CoherenceGraph class.

Returns:

result (nnsa.CoherenceGraphResult) – an object containing the resulting adjacency matrices of the graphs.

compute_features(verbose=1, chunk_size=None, **kwargs)[source]

Compute EEG feature set.

Parameters:

kwargs – for EegFeatures().
verbose (int) – verbosity level.
chunk_size (int) – number of time samples to process at once. If None, a suitable chunk_size is chosen automatically.

Returns:

result (FeatureSetResult) – feature set result.

create_bipolar_channel(channel_1, channel_2, label=None)[source]

Create a bipolar channel by subtracting channel_2 from channel_1, i.e. bipolar channel = channel_1 - channel_2.

Parameters:

channel_1 (str) – the label of the first channel.
channel_2 (str) – the label of the second channel (will be subtracted from the first channel).
label (str, optional) – label for the new bipolar channel. If None, a label will automatically be created from channel_1 and channel_2. Defaults to None.

Returns:

ts_bipolar (nnsa.TimeSeries) – TimeSeries object holding the bipolar channel data.

create_bipolar_channels(channels_1, channels_2, labels=None, missing_mode='error')[source]

Create a set of bipolar channels by subtracting channels_2 from channels_1.

channels_new[i] = channels_1[i] - channels_2[i]

Parameters:

channels_1 (list) – the labels of the first channels.
channels_2 (list) – the labels of the second channels (will be subtracted from the first channel). Must have the same length as channels_1.
labels (str, optional) – label for the new bipolar channels. Must have the same length as channels_1. If None, labels will automatically be created from channels_1 and channels_2. Defaults to None.
missing_mode (str, optional) – what to do if a specified channel is missing from the dataset. Choose from: - ‘error’: raise a ValueError if a channel is specified that is not in the EEG dataset. - ‘ignore’: ignore the requested bipolar channels that could not be created. - ‘warn’: ignore, but display a warning.

Returns:

ds_bipolar (nnsa.EegDataset) – EegDataset object holding the bipolar channels data.

detect_anomalous_channels(window=3, std_factor=8, p_trim=0.25, verbose=0)[source]

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

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

Parameters:

window (float) – the window length (seconds) in which to compute line length.
std_factor (float) – the factor for std determining the threshold (mean+`std_factor*std).
p_trim (float) – the relative amount of channels to strip before computing the mean and std. The channels with the highest line lengths are stripped/excluded.
verbose (int) – verbosity level.

detect_artefacts(multi_channel_cnn=True, verbose=1)[source]

Helper function to quickly detect artefacts using a combination of methods (see code).

Apply to raw EEG.

Parameters:

multi_channel_cnn (bool) – whether to use the multi-channel CNN (True) or not (False).
verbose (int) – verbosity level.

Returns:

af_ds (EegDataset) – EegDataset with artefact masks consisting of boolean values: True at locations of artefacts, False otherwise.

detect_artefacts_amplitude(threshold_high, threshold_low=0, window=1, how='max')[source]

Detect locations of artefacts by settings thresholds on the running mean/maximum of the absolute amplitude.

Returns a boolean mask where True values indicate locations where x < threshold_low or x > threshold_high, where x is the moving average/maximum of the absolute signal values in a window of window seconds.

Parameters:

threshold_high (float) – threshold in uV.
threshold_low (float) – threshold in uV.
window (float) – window for the moving average in seconds.
how (str) – whether to take the moving ‘mean’ or ‘max’.

Returns:

af_ds (EegDataset) – EegDataset with artefact masks consisting of boolean values: True at locations of artefacts, False otherwise.

detect_artefacts_amplitude_kaupilla(notch_filter=True, bp_filter=True)[source]

Detect locations of artefacts by settings thresholds on the amplitude as proposed by Kaupilla et al. 2018.

To apply to raw EEG data: set notch_filter and bp_filter to True.

Parameters:

notch_filter (bool) – specify whether the EEG needs to be filtered. Set to True if eeg is raw data.
bp_filter (bool) – specify whether the EEG needs to be filtered. Set to True if eeg is raw data.

Returns:

af_ds (EegDataset) – EegDataset with artefact masks consisting of boolean values: True at locations of artefacts, False otherwise.

detect_artefacts_cnn(preprocess=None, detect_flats=True, detect_peaks=True, verbose=1, **kwargs)[source]

Detect locations of artefacts based on clean EEG detection with CNN.

EEG data must be referenced to Cz. If Cz is in self, referencing will be done automatically. If Cz is not present, referencing will be ignored (assuming the EEG data is already referenced).

Apply to raw EEG data and set preprocess_eeg to True.

Parameters:

preprocess (bool) – specify whether the EEG needs to be preprocessed (filtered, resampled). Set to True if eeg is raw data. If not specified, preprocessing will be done if fs is not as required by the model, otherwise not.
detect_flats (bool) – if True, computes moving std in short windows and if its below a threshold, the sample is marked as artefact (since the CNN might not catch this).
detect_peaks (bool) – if True, computes moving max abs amplitude in short windows and if its above a threshold, the sample is marked as artefact (since the CNN might not catch this).
verbose (int) – verbosity level.
**kwargs (dict) – for CleanDetectorCnn().

Returns:

af_ds (EegDataset) – EegDataset with artefact masks consisting of boolean values: True at locations of artefacts, False otherwise.

detect_artefacts_kota(notch_filter=True, bp_filter=True)[source]

Simple method to detect small and large amplitude artefacts.

Apply to raw data referenced to Cz with notch_filter and bp_filter set to True.

https://doi.org/10.1016/j.pediatrneurol.2021.06.001

detect_artefacts_method(how, **kwargs)[source]: Shortcut to any of the artefact removal functions.

detect_artefacts_rfc(pma=None, preprocess=None, verbose=1, **kwargs)[source]

Detect locations of artefacts based on a sample supervised random forest classifier from the artefact_detection package.

EEG data must be referenced to Cz. If Cz is in self, referencing will be done automatically. If Cz is not present, referencing will be ignored (assuming the EEG data is already referenced).

To apply to raw EEG data: set preprocess_eeg to True.

See also

RfcArtefactDetector

Parameters:

pma (float) – PMA of the neonate at time of recording. Optional dependeing on model, see RfcArtefactDetector.predict().
preprocess (bool) – specify whether the EEG needs to be preprocessed (filtered, resampled). Set to True if eeg is raw data (but it should still be referenced to Cz). If not specified, preprocessing will be done if fs is not 128, otherwise not.
verbose (int) – verbosity level.
**kwargs (dict) – for RfcArtefactDetector().

Returns:

af_ds (EegDataset) – EegDataset with artefact masks consisting of boolean values: True at locations of artefacts, False otherwise.

filter(*args, remove_mean=True, **kwargs)[source]: Calls the parent function, but with remove_mean set to True by default.

filter_saved_filter(*args, remove_mean=True, **kwargs)[source]: Calls the parent function, but with remove_mean set to True by default.

filtfilt(*args, remove_mean=True, **kwargs)[source]: Calls the parent function, but with remove_mean set to True by default.

static from_array(eeg, fs, channel_labels=None, **kwargs)[source]

Create an EegDataset from a 2D array (channels x time).

Parameters:

eeg (np.ndarray) – 2d array with dimensions (channels, time).
fs (float) – sample frequency in Hz.
channel_labels (list) – list with length len(eeg) containing labels for the channels. If None, will create default numbered names, like Ch1, Ch2, Ch3, …
**kwargs – optional keyword arguments for nnsa.TimeSeries.

Returns:

ds (nnsa.EegDataset) – EegDataset with the data from the array.

Examples

>>> eeg = np.random.rand(8, 10000)
>>> eeg_ds = EegDataset.from_array(eeg, fs=250, channel_labels=list(range(8)))

get_channel(channel, make_copy=True)[source]

Return a channel as TimeSeries. Can also be a bipolar channel.

Parameters:

channel (str) – channel label, or a bipolar channel.
make_copy (bool) – if True, the returned TimeSeries is always a copy. If False, the returned TimeSeries may be the same object as in self, if channel is in self.

Returns:

ts (TimeSeries) – time series containing the channel signal.

get_segments(segment_length, overlap=0, channels_last=True)[source]

Segment the EEG data and return the segmented data as a 3D array.

Parameters:

segment_length (float) – segment length in seconds.
overlap (float) – segment overlap in seconds.
channels_last (bool) – if True, the returned array has shape (n_segments, n_time, n_channels). If False, the shape is (n_segments, n_channels, n_time).

Returns:

eeg_seg (np.ndarray) – 3D array with length equal to the number of segments. The other two dimensions are time and channels, their order depends on channels_last.

kirubin_features(reference_channel=None, preprocess=False, inplace=False, verbose=1, **kwargs)[source]

Compute Kirubin’s feature set.

This is a wrapper that prepares the input for KirubinFeatures.wct() and returns the result.

Parameters:

reference_channel (str, optional) – specify how to reference the data. If no referencing is desired, specify None.
preprocess (bool, optional) – apply a default preprocessing routine on the data before feature computation (True) or not (False). Defaults to False.
inplace (bool, optional) – if preprocess_eeg is True, specify if the preprocessing should be inplace or not. Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the KirubinFeatures class.

Returns:

result (nnsa.KirubinFeaturesResult) – the result with the features.

mean(channels=None, label=None, **kwargs)[source]

Return the nanmean of the specified channels as a TimeSeries.

Parameters:

channels (list, optional) – list with labels of the signals to be average. If None, all signals in the Dataset are averaged. Defaults to None.
label (str, optional) – label for returned TimeSeries.
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ts (nnsa.TimeSeries) – TimeSeries containing the median of the channels.

median(channels=None, label=None, **kwargs)[source]

Return the nanmedian of the specified channels as a TimeSeries.

Parameters:

channels (list, optional) – list with labels of the signals to be average. If None, all signals in the Dataset are averaged. Defaults to None.
label (str, optional) – label for returned TimeSeries.
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ts (nnsa.TimeSeries) – TimeSeries containing the median of the channels.

notch_filt(*args, remove_mean=True, **kwargs)[source]: Calls the parent function, but with remove_mean set to True by default.

plot(begin=None, end=None, channels=None, color=None, scale=None, relative_time=False, time_scale=None, ax=None, legend=True, **kwargs)[source]

Plot the EEG data of specified channels for a specifiec time frame.

Assumes that all channels have same sampling frequency and unit. Raises a NotImplementedError if this is not the case.

Parameters:

begin (float, optional) – begin time in seconds, relative to the beginning of the loaded signal (ignores any offset). Defaults to 0.
end (float, optional) – end time in seconds or None to specify the end of the entire signal. Relative to the beginning of the loaded signal ignores any offset. Defaults to None.
channels (list, optional) – list of labels specifying the channels to plot, in order bottom to up. If None, all EEG channels in the EegDataset are plotted. Defaults to None.
color (str or array or None) – if str or array, use this as the color for all channels. If None, the default colors will be used to plot each channel in a different color.
scale (int, optional) – value (in the same unit as the data) by which to scale the data (data is divided by scale). This factor must aim to squeeze most data between -0.5 and 0.5. If None, this scale is determined automatically. Default is None.
relative_time (bool, optional) – if True, the time axis is relative to the start of the segment to plot. If False, the time axis will correspond to the time in the recording.
time_scale (str, optional) – the time scale to use. Choose from ‘seconds’, ‘minutes’, ‘hours’, None. If None or ‘timedelta’, plots with a datetime.timedelta format (hh:mm:ss).
ax (plt.Axes, optional) – axes to plot in. If None, plots in a new figure. Defaults to None.
legend (bool, optional) – add a legend (True) indicating the scale or not (False). Defaults to True.
**kwargs (optional) – optional keyword arguments for the plt.plot() function.

Returns:

ax (plt.axes) – axes instance.

plot_mask(mask, time_scale='seconds', color=None, skip_value=0, ax=None, **kwargs)[source]

Plot a shaded mask over an EEG plot.

Parameters:

mask (np.ndarray) – mask with shape (n_time, n_channels).
time_scale (str) – time scale in which to plot.
color (str, array, dict) – color or dictionary of colors for plotting the labels in mask.
skip_value (int, bool, float or list) – value(s) in mask to not plot.
ax (plt.Axes) – axes to plot in.
**kwargs – for plot().

power_analysis(verbose=1, **kwargs)[source]: Calls the paretn method, but sets some common frequency bands for EEG.

static read_begin_end_time(filepath)[source]

Read the start and end time (wrt time offset) of the EEG data in a HDF5 file.

Parameters:: filepath (str) – filepath to read.
Returns:: begin, end (float) – begin and end time in seconds.

static read_edf(filepath, begin=None, end=None, **kwargs)[source]

Read an EegDataset object from an .edf file.

Parameters:

filepath (str) – filepath to read.
begin (float, optional) – start second.
end (float, optional) – end second.
**kwargs (optional) – keyword arguments for EdfReader.read_eeg_dataset().

Returns:

ds (nnsa.EegDataset) – EegDataset object with data read from the file.

static read_hdf5(filepath, begin=None, end=None, **kwargs)[source]

Read an EegDataset object from an .hdf5 file.

Parameters:

filepath (str) – filepath to read.
begin (float, optional) – start second (wrt time offset).
end (float, optional) – end second (wrt time offset).
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ds (nnsa.EegDataset) – EegDataset object with data read from the file.

Examples

>>> signal = np.random.rand(8, 1000)
>>> eeg_ds = EegDataset()
>>> ts_all = [TimeSeries(signal=signal[i], fs=10, label=i) for i in range(len(signal))]
>>> eeg_ds.append(ts_all)
>>> eeg_ds.save_hdf5('testfile.hdf5')
>>> ds_read = EegDataset.read_hdf5('testfile.hdf5')
>>> ds_read_epoch = EegDataset.read_hdf5('testfile.hdf5', begin=10, end=20)
>>> os.remove('testfile.hdf5')
>>> assert_equal(eeg_ds.signal, ds_read.signal)
>>> assert_equal(eeg_ds.extract_epoch(begin=10, end=20).signal, ds_read_epoch.signal)

static read_mat(filepath, begin=None, end=None, loadmat_kwargs=None, **kwargs)[source]

Read an EegDataset object from a .mat file.

Parameters:

filepath (str) – filepath to read.
begin (float, optional) – start second (wrt time offset).
end (float, optional) – end second (wrt time offset).
loadmat_kwargs (dict, optional) – dict with keyword arguments for scipy.io.loadmat()/
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ds (nnsa.EegDataset) – EegDataset object with data read from the file.

static read_pickle(filepath, begin=None, end=None, **kwargs)[source]

Read an EegDataset object from a .pkl file.

Parameters:

filepath (str) – filepath to read.
begin (float, optional) – start second (wrt time offset).
end (float, optional) – end second (wrt time offset).
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ds (nnsa.EegDataset) – EegDataset object with data read from the file.

static read_set(filepath, begin=None, end=None, loadmat_kwargs=None, **kwargs)[source]

Read an EegDataset object from a .set file (from Matlab EEGLAB).

Parameters:

filepath (str) – filepath to read.
begin (float, optional) – start second (wrt time offset).
end (float, optional) – end second (wrt time offset).
loadmat_kwargs (dict, optional) – dict with keyword arguments for scipy.io.loadmat()/
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ds (nnsa.EegDataset) – EegDataset object with data read from the file.

reference(reference_channel='Cz', remove_reference=True, inplace=False, verbose=1)[source]

Reference all EEG signals to reference_channel, i.e. subtract the signal of the reference_channel from all other EEG channels.

Parameters:

reference_channel (str, optional) – label of the channel to use as reference. Can also be ‘average’ to subtract the average channel. Default is ‘Cz’.
remove_reference (bool, optional) – if True, remove the reference channel from the referenced dataset. If False, keep the reference channel after referencing (this channel will be zero everywhere). Default is True.
inplace (bool, optional) – if True, the referenced signals will replace the original signals in this EegDataset. If False (default), the function returns a new EegDataset object containing the referenced signals, leaving the data in the current EegDataset unchanged. Note that if only certain channels are referenced, the newly created EegDataset object will only contain those channels.
verbose (int, optional) – verbose level. Defaults to 1.

remove_artefact_channels(inplace=False, **kwargs)[source]

Remove channels that do not meet the quality criteria.

Parameters:

inplace (bool, optional) – If True, the channel is removed directly from the EegDataset object itself. If False, the function returns a copy of the original EegDataset object in which the artefacted channels are removed, leaving the data in the current EegDataset unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for overruling default signal quality criteria (see nnsa.artefacts.artefact_detection.default_eeg_signal_quality_criteria()).

Returns:

(EegDataset) – new EegDataset object containing the same signals, except for the removed channels (only if inplace is False).

remove_artefacts_amplitude(notch_filter=True, bp_filter=True, inplace=False)[source]: Remove artefacts as detected by self.detect_artefacts_amplitude().

remove_artefacts_derivative(threshold=23000, inplace=False)[source]

Remove artefacts based on a threshold on the derivative of the filtered signal.

Apply this to raw EEG data.

Args: TODO: inplace:

Returns:: EegDataset where the artefacts are replaced by nans.

remove_artefacts_kota(notch_filter=True, bp_filter=True, inplace=False, verbose=1)[source]: Remove artefacts as detected by self.detect_artefacts_kota().

remove_artefacts_mask(mask_ds, inplace=False)[source]

Insert nans where boolean mask is True.

Parameters:: mask_ds (BaseDataset) – dataset with boolean masks for each of the signals in self.

remove_artefacts_method(how, **kwargs)[source]: Shortcut to any of the artefact removal functions.

remove_artefacts_rfc(pma, preprocess=None, inplace=False, **kwargs)[source]

Remove artefacts based on a sample supervised random forest classifier from the artefact_detection package.

EEG data must be referenced to Cz. If Cz is in self, referencing will be done automatically. If Cz is not present, referencing will be ignored (assuming the EEG data is already referenced).

To apply to raw EEG data: set preprocess_eeg to True.

See also

RfcArtefactDetector, self.detect_artefacts_rfc().

Parameters:

pma (np.ndarray) – PMA of the neonate at time of recording.
preprocess (bool) – specify whether the EEG needs to be preprocessed (filtered, resampled). Set to True if eeg is raw data (but it should still be referenced to Cz). If not specified, preprocessing will be done if fs is not 128, otherwise not.
inplace (bool) – whether to remove in place or not.
**kwargs (dict) – for RfcArtefactDetector().

Returns:

ds_out (EegDataset) – EegDataset where the artefacts are replaced by nans.

save_csv(filepath, overwrite=False, **kwargs)[source]

Save the EegDataset data to a .csv (comma-separated value) file.

This is slow, as it used the pandas functionality.

Parameters:

filepath (str) – filepath to save to.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists. Defaults to False.
**kwargs (dict, optional) – for pandas.DataFrame.to_csv().

save_hdf5(filepath, mode='w', overwrite=False)[source]

Save the EegDataset data to a .hdf5 file.

Parameters:

filepath (str) – filepath to save to.
mode (str, optional) – ‘w’ for write mode or ‘a’ for append mode. Defaults to ‘w’.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists. Defaults to False.

save_mat(filepath, overwrite=False)[source]

Save the EegDataset data to a .mat file.

Parameters:

filepath (str) – filepath to save to.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists. Defaults to False.

save_pickle(filepath, overwrite=False, **kwargs)[source]

Save the EegDataset data to a .pkl (pickle) file.

Parameters:

filepath (str) – filepath to save to.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists. Defaults to False.
**kwargs (dict, optional) – for nnsa.pickle_save().

property signal

Return the EEG data as a numpy array (channels, time).

Returns:: (np.ndarray) – EEG data matrix.

sleep_stages_cnn(preprocess=None, remove_flats=True, remove_baseline_wander=False, stepsize=None, verbose=1, preprocess_kwargs=None, **kwargs)[source]

Automatic sleep stage classification using a Convolutional Neural Network.

This is a wrapper that prepares the input for SleepStagesCnn.sleep_stages_cnn() and returns the result.

Parameters:

preprocess (bool, optional) – if True, the EEG data in ds will be processed by filtering and resampling correspondingly. If False, the data in ds will not be preprocessed (use this when the ds already contains correspondingly prepreocessed data). If None, preprocessing will be done if the sampling frequency of the data does not match the required fs by the model.
remove_flats (bool, optional) – if True, removes flatlines.
remove_baseline_wander (bool) – if True, removes excessive baseline wander by applying a HP filter. This was not part of original preprocessing during training, and most EEGs don’t need this (in the original preprocessing there is already a HP filter, but milder). If not needed, don’t do this additional baseline removal.
stepsize (float) – stepsize (in seconds) for sleep stage prediction. If None, stepsize is equal to segment length (no overlap).
verbose (int, optional) – verbose level (0 or 1). Defaults to 1.
preprocess_kwargs (dict, optional) – dict with optional keyword arguments for SleepStagesCnn.preprocess_recording(). Defaults to None.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the SleepStagesCnn class.

Returns:

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

sleep_stages_robust(verbose=1, **kwargs)[source]

Automatic robust sleep stage classification.

This is a wrapper that prepares the input for SleepStagesRobust.process() and returns the result.

Args:

verbose (int, optional): verbose level (0 or 1).
Defaults to 1.

**kwargs (optional): optional keyword arguments to the SleepStagesRobust class.

Returns:: result (nnsa.SleepStagesCnnResult) – nnsa object containing the results.

substitute_bad_channels(af_mask, inplace=False, **kwargs)[source]

Find segments with bad channels in the EEG and substitute by the mean of the good channels.

Parameters:

af_mask (np.ndarray or EegDataset) – boolean mask for the EEG array data with True at locations of artefacts. Shape should be (n_channels, n_time). An incompatible shape will be transposed if that makes it compatible, or raises an error otherwise.
inplace (bool) – whether to apply inplace (True) or not (False).
kwargs – for substitute_bad_channels.

Returns:

ds_out (EegDataset) – cleaned EegDataset with bad channels substituted.

class nnsa.containers.datasets.OxygenDataset(*args, label=None)[source]

Bases: BaseDataset

High-level interface for processing oxygen data for neonatal signal analysis.

Methods:

`nirs_features`([verbose])	Compute feature set for NIRS.
`remove_artefacts`([inplace])	Replace samples that are artefacts by np.nan

nirs_features(verbose=1, **kwargs)[source]

Compute feature set for NIRS.

This is a wrapper that prepares the input for NirsFeatures.wct() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the NirsFeatures class.

Returns:

result (nnsa.FeatureSetResult) – the result with the features.

remove_artefacts(inplace=False, **kwargs)[source]

Replace samples that are artefacts by np.nan

Parameters:

inplace (bool, optional) – If True, the samples are replaced directly from the Dataset object itself. If False, the function returns a copy of the original Dataset object in which the artefacted samples are replaced, leaving the data in the current Dataset unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for overruling default sample quality criteria (see nnsa.artefacts.artefact_detection.default_oxygen_sample_quality_criteria()).

Returns:

(OxygenDataset) – new Dataset object containing the same signals,but with artefacted samples changed to np.nan (only returned if inplace is False).

nnsa.containers.time_series module

Module for creating an object that holds the data of a time series.

Classes:

TimeSeries(signal, fs[, label, unit, info, ...])

High-level interface for processing of any type of time series.

class nnsa.containers.time_series.TimeSeries(signal, fs, label='no label', unit='a.u.', info=None, time_offset=0, check_label=False, check_unit=False, **kwargs)[source]

Bases: ClassWithParameters

High-level interface for processing of any type of time series.

Parameters:

signal (np.ndarray) – 1D array containing the signal.
fs (float) – sampling frequency of the signal array.
label (str, optional) – the label of the signal (if check_label is True, should be a valid standardized name, see check_label()).
unit (str, optional) – the unit of the signal (should be a valid standardized unit, see check_unit()). Defaults to ‘a.u’.
info (dict, optional) – dict with info about the signal. Dict can contain ‘source’, specifying the path to the source file of the signal. It may have an optional additional field ‘processing’, which is a list of strings specifying several processing steps that were applied to the original signal loaded from ‘source’. If None, the ‘source’ field in the dict is set to ‘UNKNOWN’. Defaults to None.
time_offset (float, optional) – optional time offset in seconds. Time array starts at this offset. Defaults to 0.
check_label (bool, optional) – if True, the passed label is checked whether it is valid. If False, no check is performed and any label may be given. Defaults to True.
check_unit (bool, optional) – if True, the passed unit is checked whether it is valid. If False, no check is performed and any unit may be given. Defaults to True.
**kwargs (optional) – optional keyword arguments for setting parameters.

Methods:

`amplitude_eeg`([verbose])	Compute amplitude-integrated EEG (aEEG) from single channel continuous EEG.
`as_dict`()	Return the TimeSeries data in a dictionary.
`astype`(dtype[, inplace])
`burst_detection`([verbose])	Perform burst detection.
`clamp`(threshold[, inplace])	Clamp values by applying a clamping function to reduce dynamic range.
`compute_power_cwt`([freq_low, freq_high, inplace])	Compute power in specified band.
`cwt`([verbose])	Apply a continuous wavelet transform on the signal.
`default_parameters`()	Return the default parameters as a dictionary.
`demean`([mean_fun, inplace])	Demean the time series.
`detrend`(args, *kwargs)
`detrend_poly`(order[, inplace])	Detrend the time series using a polynomial of a specific order.
`envelope`([verbose])	Compute envelope.
`extract_epoch`([begin, end, error_mode])	Extract a piece of data in the specified interval.
`fill_nan`(value[, inplace, verbose])	Replace nans in the signal by a constant value.
`filter`(filter_obj[, remove_mean, inplace, ...])	Filter the signal with the given 1-D digital filter.
`filter_saved_filter`(filter_name[, ...])	Filter the signal with a specified saved filter.
`filtfilt`(filter_obj[, remove_mean, inplace, ...])	Filter the signal with the given filter using zero-phase filtering (filtfilt).
`interp`(t, **kwargs)	Wrapper for np.interp, performing linear interpolation to get the signal values at times t.
`interp_nan`(args, *kwargs)
`interpolate_nan`([inplace, max_nan_length])	Linearly interpolate nan values.
`line_length`([verbose])	Compute line length feature.
`mean`([max_nan_frac])	Return the mean.
`median`([max_nan_frac])	Return the median.
`merge`(other[, inplace])	Merge other TimeSeries object(s) into one object based on their time arrays.
`moving_average`(args, *kwargs)	Helper-function to apply a moving average.
`moving_max`(window[, inplace])	Helper-function to apply a moving maximum.
`moving_mean`(window[, inplace])	Helper-function to apply a moving average.
`moving_median`(window[, inplace])	Helper-function to apply a moving average.
`multi_scale_entropy`([verbose])	Perform a multi-scale entropy (mse) analysis.
`multifractal_analysis`([verbose])	Perform a multifractal analysis (mfa).
`normalize`([how, inplace])	Normalize the signal.
`notch_filt`([f0, verbose, inplace])	Helper-function to apply a notch filter to remove e.g.
`plot`(*args[, begin, end, time_scale, ax])	Plot (part of) the signal.
`power_analysis`([verbose])	Perform a Fourier based power analysis.
`psd`([verbose])	Estimate power spectral density.
`read_hdf5`(filepath[, label, begin, end])	Read a TimeSeries object from a .hdf5 file.
`read_mat`(filepath, **kwargs)	Read a TimeSeries object from a .mat file.
`read_pickle`(filepath, **kwargs)	Read a TimeSeries object from a pickle file.
`reference`(reference_signal, reference_label)	Reference the signal to reference_channel by subtracting reference_signal from the signal.
`remove_artefacts`([inplace])	Replace samples that are artefacts by np.nan
`remove_flatlines`(n_flatline[, inplace])	Replace flatlines by np.nan
`remove_neighborhood_artefacts`(size[, inplace])	Replace values by np.nan if sample sin their neighborhood are nan.
`remove_outliers`(*args[, inplace])	Replace outliers by np.nan
`remove_values`(*args[, inplace])	Replace values by np.nan
`resample`(fs_new[, method, inplace, verbose])	Resample the signal data to new sampling frequency fs_new.
`save_hdf5`(filepath[, mode, overwrite])	Save the TimeSeries data to a .hdf5 file.
`save_mat`(filepath[, overwrite])	Save the TimeSeries data to a MATLAB-style .mat file.
`save_pickle`(filepath[, overwrite])	Save the TimeSeries data to a pickle file.
`segment`(segment_length[, overlap])	Segment the signal (into smaller time segments).
`signal_quality`()	Collect some characteristics of the signal related to signal quality.
`stepwise_moving_average`(*args[, avg_fun])
`stepwise_reduce`(window[, stepsize, ...])	Compute stepwise value.
`transform`(fun[, fs, label, unit, ...])	Apply a custom function to the signal.
`zscore`([ddof, nan_policy, inplace])	Normalize the signal by centering and unit standard deviation.

Attributes:

`dtype`	Return the effective dtype (should be consistent with the dtype in the parameters).
`fs`	Return the sampling frequency of the signal.
`info`	Return the info dictionary.
`label`	Return the label of the signal.
`signal`	Return the signal array.
`time`	Shortcut to time_array (return the time array corresponding to self.signal).
`time_array`	Return the time array corresponding to self.signal.
`unit`	Return the unit of the signal.

amplitude_eeg(verbose=1, **kwargs)[source]

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

This is a wrapper that prepares the input for AmplitudeEeg.wct() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the AmplitudeEeg class.

Returns:

result (nnsa.AmplitudeEegResult) – object containing the aEEG.

as_dict()[source]: Return the TimeSeries data in a dictionary.

astype(dtype, inplace=False)[source]

burst_detection(verbose=1, **kwargs)[source]

Perform burst detection.

Note: this should be used on unfiltered data.

This is a wrapper that prepares the input for BurstDetection.burst_detection() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the BurstDetection class.

Returns:

result (nnsa.BurstDetectionResult) – the result of the burst detection.

clamp(threshold, inplace=False)[source]

Clamp values by applying a clamping function to reduce dynamic range.

Parameters:

threshold (float) – threshold for the clamping function.
inplace (bool, optional) – whether to apply inplace (True) or not.

Returns:

ts (TimeSeries) – new Dataset object (only returned if inplace is False).

compute_power_cwt(freq_low=None, freq_high=None, inplace=False, **kwargs)[source]

Compute power in specified band.

Parameters:

freq_low (float, optional) – lower frequency cutoff for bandpower. If None, takes lowest possible.
freq_high (float, optional) – upper frequency cutoff for bandpower. If None, takes highest possible.
inplace (bool, optional) – if True, replaces the signal in place by its power. If False, returns a new object.
**kwargs (optional) – optional keyword arguments for compute_power_cwt().

Returns:

ts (TimeSeries) – TimeSeries with power of the signal (if inplace is False).

cwt(verbose=1, **kwargs)[source]

Apply a continuous wavelet transform on the signal.

Parameters:

verbose (int, optional) – verbosity level.
**kwargs (optional) – keyword arguments for Cwt().

Returns:

CwtResult object containing the result.

static default_parameters()[source]

Return the default parameters as a dictionary.

Returns:: (dict) – a default set of parameters.

demean(mean_fun=<function nanmean>, inplace=False)[source]

Demean the time series.

Parameters:

mean_fun (function) – function that takes in a 1D array and retruns the mean that will be subtracted. Defaults to np.nanmean. Other possibilities could be np.nanmedian, np.mean, …
inplace (bool, optional) – whether to apply the operation inplace or return a new object.

Returns:

ts (nnsa.TimeSeries) – object with demeaned signal (returned if inplace is False).

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

detrend_poly(order, inplace=False)[source]

Detrend the time series using a polynomial of a specific order.

Parameters:

order (int) – degree of the polynomial.
inplace (bool, optional) – whether to apply the operation inplace or return a new object.

Returns:

ts (nnsa.TimeSeries) – object with detrended signal (returned if inplace is False).

property dtype: Return the effective dtype (should be consistent with the dtype in the parameters).

envelope(verbose=1, **kwargs)[source]

Compute envelope.

This is a wrapper that prepares the input for Envelope.envelope() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the Envelope class.

Returns:

result (nnsa.EnvelopeResult) – the result of the envelope computation.

Examples

To get the envelope data as a new TimeSeries object: >>> signal = 4 * np.sin(np.arange(10000)) >>> ts = TimeSeries(signal=signal, fs=100, label=’EEG Cz’, unit=’uV’, info={‘source’: ‘random’}) >>> envelope_result = ts.envelope(verbose=0) >>> ts_envelope = envelope_result.to_time_series() >>> print(type(ts_envelope).__name__) TimeSeries

>>> print(ts_envelope.signal.mean())
3.9998155216320725

extract_epoch(begin=None, end=None, error_mode='raise')[source]

Extract a piece of data in the specified interval.

Parameters:

begin (float, optional) – start time in seconds (including time_offset) of the epoch to extract. If negative, begin is duration + begin (python-like indexing). If None, the beginning of the signal is taken. Defaults to None.
end (float, optional) – end time in seconds (including time_offset) of the epoch to extract. If negative, end is duration + end (python-like indexing). If None, the end of the signal is taken. Must point to a time greater than begin. Defaults to None.
error_mode (str) – whether to ‘raise’ an error when no time overlap is found, or to just ‘warn’.

Returns:

ts_epoch (nnsa.TimeSeries) – a new TimeSeries object with only the data of the specified epoch.

fill_nan(value, inplace=False, verbose=0)[source]

Replace nans in the signal by a constant value.

Parameters:

value (float) – the value to fill with.
inplace (bool, optional) – if True, resamples inplace, else a new object is returned. Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(TimeSeries) – new TimeSeries object containing the new signal (if inplace is False).

filter(filter_obj, remove_mean=False, inplace=False, verbose=1, **kwargs)[source]

Filter the signal with the given 1-D digital filter.

Note: this introduces a delay in the filter signal. For zero-phase filtering use filtfilt.

Parameters:

filter_obj (FilterBase-derived) – a child class from the nnsa.FilterBase class. The fs property does not need to be set correctly, as it will be automatically (re)set in this function.
inplace (bool, optional) – if True, filters inplace, else a new object is returned. Defaults to False.
remove_mean (bool, optional) – remove the mean value after filtering (useful for EEG data).
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments passed on to the filter() function of filter_obj.

Returns:

(TimeSeries) – new TimeSeries object containing the filtered signal (if inplace is False).

filter_saved_filter(filter_name, remove_mean=False, inplace=False, verbose=1, **kwargs)[source]

Filter the signal with a specified saved filter.

This is just a wrapper of the nnsa.preprocessing.filter_saved_filter() function.

Parameters:

filter_name (str) – see nnsa.preprocessing.filter_saved_filter().
remove_mean (bool, optional) – remove the mean value after filtering (useful for EEG data).
inplace (bool, optional) – if True, resamples inplace, else a new object is returned. Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments passed on to nnsa.preprocessing.filter_saved_filter().

Returns:

(TimeSeries) – new TimeSeries object containing the filtered signal (if inplace is False).

filtfilt(filter_obj, remove_mean=False, inplace=False, verbose=1, **kwargs)[source]

Filter the signal with the given filter using zero-phase filtering (filtfilt).

Parameters:

filter_obj (FilterBase-derived) – a child class from the nnsa.FilterBase class. The fs property does not need to be set correctly, as it will be automatically (re)set in this function.
inplace (bool, optional) – if True, filters inplace, else a new object is returned. Defaults to False.
remove_mean (bool, optional) – remove the mean value after filtering (useful for EEG data).
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments passed on to the filtfilt() function of filter_obj.

Returns:

(TimeSeries) – new TimeSeries object containing the filtered signal (if inplace is False).

property fs

Return the sampling frequency of the signal.

Returns:: (float) – the sampling frequency of the signal.

property info

Return the info dictionary.

Returns:: (dict) – info dictionary.

interp(t, **kwargs)[source]

Wrapper for np.interp, performing linear interpolation to get the signal values at times t.

Parameters:

t (np.ndarray) – time instances at which to evaluate the signal.
**kwargs (optional) – optional keyword arguments for np.interp.

Returns:

y (np.ndarray) – 1D array with interpolated values.

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

interpolate_nan(inplace=False, max_nan_length=None)[source]

Linearly interpolate nan values.

Parameters:

inplace (bool, optional) – interpolate inplace (True) or return a copy (False). Defaults to False.
max_nan_length (int or str, optional) – number of maximum allowable length of a nan segment that we interpolate (in seconds). If ‘auto’, the average duration of a constant value in the signal is taken. If None, no limit is applied, i.e. all nans are interpolated. Defaults to None.

Returns:

ts (TimeSeries) – time series with nans interpolated (if inplace is False).

property label

Return the label of the signal.

Returns:: (str) – the label of the signal.

line_length(verbose=1, **kwargs)[source]

Compute line length feature.

This is a wrapper that prepares the input for LineLength.line_length() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the LineLength class.

Returns:

result (nnsa.LineLengthResult) – the result of the line length computation.

mean(max_nan_frac=1)[source]: Return the mean.

median(max_nan_frac=1)[source]: Return the median.

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

Merge other TimeSeries object(s) into one object based on their time arrays.

Fills gaps in between the time arrays with nan.

Parameters:

other (TimeSeries or list) – list with (compatible) TimeSeries objects.
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:

out (TimeSeries) – new TimeSeries object containing the merged time series (if inplace is False).

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

Helper-function to apply a moving average.

Parameters:

window (float) – window of the moving average (in seconds).
inplace (bool) – whether to apply the filter inplace or not.
**kwargs – for nnsa.moving_average()

Returns:

(TimeSeries) – filtered data (if inplace is True).

moving_max(window, inplace=False, **kwargs)[source]

Helper-function to apply a moving maximum.

Parameters:

window (float) – window of the moving maximum (in seconds).
inplace (bool) – whether to apply the filter inplace or not.
**kwargs – for nnsa.moving_max()

Returns:

(TimeSeries) – filtered data (if inplace is True).

moving_mean(window, inplace=False, **kwargs)[source]

Helper-function to apply a moving average.

Parameters:

window (float) – window of the moving average (in seconds).
inplace (bool) – whether to apply the filter inplace or not.
**kwargs – for nnsa.moving_average()

Returns:

(TimeSeries) – filtered data (if inplace is True).

moving_median(window, inplace=False, **kwargs)[source]

Helper-function to apply a moving average.

Parameters:

window (float) – window of the moving average (in seconds).
inplace (bool) – whether to apply the filter inplace or not.
**kwargs – for nnsa.moving_average()

Returns:

(TimeSeries) – filtered data (if inplace is True).

multi_scale_entropy(verbose=1, **kwargs)[source]

Perform a multi-scale entropy (mse) analysis.

This is a wrapper that prepares the input for MultiScaleEntropy.multi_scale_entropy() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the MultiScaleEntropy class.

Returns:

result (nnsa.MultiScaleEntropyResult) – the result of the mse analysis.

multifractal_analysis(verbose=1, **kwargs)[source]

Perform a multifractal analysis (mfa).

This is a wrapper that prepares the input for MultifractalAnalysis.multifractal_analysis() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the MultifractalAnalysis class.

Returns:

result (nnsa.MultifractalAnalysisResult) – the result of the mfa analysis.

normalize(how='zscore', inplace=False, **kwargs)[source]

Normalize the signal.

Parameters:

how (str) – how to normalize. Choose from: - “zscore”
inplace (bool, optional) – whether to normalize inplace (True) or not.
**kwargs (dict) – for normalization functions. Depends on how (see code).

Returns:

(TimeSeries) – normalized signal (only returned if inplace is False).

notch_filt(f0=50, verbose=1, inplace=False, **kwargs)[source]

Helper-function to apply a notch filter to remove e.g. power line interference.

Parameters:

f0 (float or list) – frequencie(s) to suppress.
verbose (int) – verbosity level.
inplace (bool) – whether to apply the filter inplace or not.
**kwargs (optional) – for self.filtfilt().

Returns:

(TimeSeries) – filtered data (if inplace is True).

plot(*args, begin=None, end=None, time_scale='seconds', ax=None, **kwargs)[source]

Plot (part of) the signal.

Parameters:

*args (optional) – optional arguments for the plt.plot() function.
begin (float, optional) – begin time in seconds. If None, plots from the first sample. Default is None.
end (float, optional) – end time in seconds or None to specify the end of the entire signal. Default is None.
time_scale (str, optional) – the time scale to use. Choose from ‘seconds’, ‘minutes’, ‘hours’. Defaults to ‘seconds’.
ax (plt.Axes, optional) – axes to plot is. If None, plots in a new figure. Defaults to None.
**kwargs (optional) – optional keyword arguments for the plt.plot() function.

power_analysis(verbose=1, **kwargs)[source]

Perform a Fourier based power analysis.

This is a wrapper that prepares the input for PowerAnalysis.power_analysis() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the PowerAnalysis class.

Returns:

result (nnsa.PowerAnalysisResult) – the result of the power analysis.

psd(verbose=1, **kwargs)[source]

Estimate power spectral density.

This is a wrapper that prepares the input for Psd.psd() and returns the results.

Parameters:

verbose (int, optional) – verbose level. Defaults to 0.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the Psd class.

Returns:

result (nnsa.PsdResult) – object containing the result of the psd.

static read_hdf5(filepath, label=None, begin=None, end=None, **kwargs)[source]

Read a TimeSeries object from a .hdf5 file.

Parameters:

filepath (str or opened file) – filepath to read or an open HDF5 file.
label (str, optional) – label of the hdf5 dataset to read. If None, reads the first TimeSeries that it can find in the file. Defaults to None.
begin (float, optional) – start second (wrt time offset).
end (float, optional) – end second (wrt time offset).
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ts (nnsa.TimeSeries) – TimeSeries object with data read from the file.

Examples

>>> signal = np.random.rand(1000)
>>> ts = TimeSeries(signal=signal, fs=10, label='EEG Cz')
>>> ts.save_hdf5('testfile.hdf5')
>>> ts_read = TimeSeries.read_hdf5('testfile.hdf5')
>>> ts_read_epoch = TimeSeries.read_hdf5('testfile.hdf5', begin=10, end=20)
>>> os.remove('testfile.hdf5')
>>> assert_equal(ts.signal, ts_read.signal)
>>> assert_equal(ts.extract_epoch(begin=10, end=20).signal, ts_read_epoch.signal)

static read_mat(filepath, **kwargs)[source]

Read a TimeSeries object from a .mat file.

Parameters:

filepath (str) – filepath to read.
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ts (nnsa.TimeSeries) – TimeSeries object with data read from the file.

Examples

>>> signal = np.random.rand(1000)
>>> ts = TimeSeries(signal=signal, fs=10, label='EEG Cz')
>>> ts.save_mat('testfile.mat')
>>> ts_read = TimeSeries.read_mat('testfile.mat')
>>> os.remove('testfile.mat')
>>> assert_equal(ts.signal, ts_read.signal)

static read_pickle(filepath, **kwargs)[source]

Read a TimeSeries object from a pickle file.

Parameters:

filepath (str) – filepath to read.
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ts (nnsa.TimeSeries) – TimeSeries object with data read from the file.

Examples

>>> signal = np.random.rand(1000)
>>> ts = TimeSeries(signal=signal, fs=10, label='EEG Cz')
>>> ts.save_pickle('testfile.pkl')
>>> ts_read = TimeSeries.read_pickle('testfile.pkl')
>>> os.remove('testfile.pkl')
>>> assert_equal(ts.signal, ts_read.signal)

reference(reference_signal, reference_label, inplace=False, verbose=1)[source]

Reference the signal to reference_channel by subtracting reference_signal from the signal.

Parameters:

reference_signal (TimeSeries or np.ndarray) – 1D array containing the reference signal to subtract.
reference_label (str) – label of the reference signal.
inplace (bool, optional) – if True, referenced inplace, else a new object is returned. Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(TimeSeries) – new TimeSeries object containing the referenced signal.

remove_artefacts(inplace=False, **kwargs)[source]

Replace samples that are artefacts by np.nan

Parameters:

inplace (bool, optional) – If True, the samples are replaced directly from the TimeSeries object itself. If False, the function returns a copy of the original TimeSeries object in which the artefacted samples are replaced, leaving the data in the current TimeSeries unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for overruling default sample quality criteria (see nnsa.artefacts.artefact_detection.detect_artefact_samples()).

Returns:

(TimeSeries) – new TimeSeries object containing the same signal, but with artefacted samples changed to np.nan (only returned if inplace is False).

remove_flatlines(n_flatline, inplace=False, **kwargs)[source]

Replace flatlines by np.nan

Parameters:

n_flatline (float) – minimal number of seconds for a non-changing segment to be a flatline.
inplace (bool, optional) – If True, the samples are replaced directly from the TimeSeries object itself. If False, the function returns a copy of the original TimeSeries object in which the flatline samples are replaced, leaving the data in the current TimeSeries unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for remove_flatlines.

Returns:

(TimeSeries) – new TimeSeries object containing the same signal, but with flatline samples changed to np.nan (only returned if inplace is False).

remove_neighborhood_artefacts(size, inplace=False, **kwargs)[source]

Replace values by np.nan if sample sin their neighborhood are nan.

Parameters:

size (int) – size of the neighborhood (in seconds). E.g., if the neighborhood is 3, sample at t=t is an artefact if there is an artefact in the signal between t-1:t+1.
inplace (bool, optional) – If True, the samples are replaced directly from the TimeSeries object itself. If False, the function returns a copy of the original TimeSeries object in which the flatline samples are replaced, leaving the data in the current TimeSeries unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for remove_neighborhood_artefacts().

Returns:

(TimeSeries) – new TimeSeries object containing the same signal, but with specific samples changed to np.nan (only returned if inplace is False).

remove_outliers(*args, inplace=False, **kwargs)[source]

Replace outliers by np.nan

Parameters:

*args (float) – arguments for remove_outliers().
inplace (bool, optional) – If True, the samples are replaced directly from the TimeSeries object itself. If False, the function returns a copy of the original TimeSeries object in which the flatline samples are replaced, leaving the data in the current TimeSeries unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for remove_outliers().

Returns:

(TimeSeries) – new TimeSeries object containing the same signal, but with outlier samples changed to np.nan (only returned if inplace is False).

remove_values(*args, inplace=False, **kwargs)[source]

Replace values by np.nan

Parameters:

*args (float) – arguments for remove_values().
inplace (bool, optional) – If True, the samples are replaced directly from the TimeSeries object itself. If False, the function returns a copy of the original TimeSeries object in which the flatline samples are replaced, leaving the data in the current TimeSeries unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for remove_values().

Returns:

(TimeSeries) – new TimeSeries object containing the same signal, but with specific samples changed to np.nan (only returned if inplace is False).

resample(fs_new, method='polyphase_filtering', inplace=False, verbose=1, **kwargs)[source]

Resample the signal data to new sampling frequency fs_new.

Deals with nans by interpolating them before resampling and putting nans back at locations near the artefacts.

Parameters:

fs_new (float) – new sampling frequency to resample to.
method (str, optional) –
the resampling method: If ‘polyphase_filtering’, the data will be resampled using polyphase filtering (see

scipy.signal.resample_poly).

If ‘interpolation’, the data will be resampled using interpolation (see scipy.interpolate.interp1d). Default is ‘polyphase_filtering’.
inplace (bool, optional) – if True, resamples inplace, else a new object is returned. Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for scipy’s resample/interpolation function that is applied (which depends on the method argument).

Returns:

(nnsa.TimeSeries) – TimeSeries object with the resampled signal.

save_hdf5(filepath, mode='w', overwrite=False)[source]

Save the TimeSeries data to a .hdf5 file.

Parameters:

filepath (str) – filepath to save to.
mode (str, optional) – ‘w’ for write mode or ‘a’ for append mode. Defaults to ‘w’.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists and mode is ‘w’. Defaults to False.

save_mat(filepath, overwrite=False)[source]

Save the TimeSeries data to a MATLAB-style .mat file.

Parameters:

filepath (str) – filepath to save to.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists. Defaults to False.

save_pickle(filepath, overwrite=False)[source]

Save the TimeSeries data to a pickle file.

Parameters:

filepath (str) – filepath to save to.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists. Defaults to False.

segment(segment_length, overlap=0)[source]

Segment the signal (into smaller time segments).

First segment starts at the start of the signal. Any left over samples at the end of the signal that cannot make up a segment of the specified length are ignored.

Parameters:

segment_length (float) – length of a segment in seconds.
overlap (float, optional) – overlap between succesive segments in seconds. Defaults to 0.

Yields:

(TimeSeries) – TimeSeries object holding the data of the next segment.

property signal

Return the signal array.

Returns:: (np.ndarray) – the (1D) signal array.

signal_quality()[source]

Collect some characteristics of the signal related to signal quality.

This is a wrapper of nnsa.artefacts.artefact_detection.signal_quality()

Returns:: (dict) – see nnsa.artefacts.artefact_detection.signal_quality()

stepwise_moving_average(*args, avg_fun=<function nanmean>, **kwargs)[source]

stepwise_reduce(window, stepsize=None, reduce_fun=<function nanmean>, max_nan=0.5, inplace=False, verbose=1)[source]

Compute stepwise value.

Parameters:

window (float) – length of the segments /moving window to compute the average in (in seconds).
stepsize (float) – stepsize of the moving average window in seconds. The output will have a sample frequency of 1/stepsize Hz. If None, stepsize will be eqaul to window.
reduce_fun (function, optional) – function to reduce a block a data. Must handle nan and accept an axis keyword. Defaults to np.nanmean.
max_nan (float, optional) – maximum fraction (0-1) of nan values in a window. If the fraction of nan samples exceeds max_nan, the mean is nan for that window. Defaults to 0.5.
inplace (bool, optional) – if True, operates inplace, else a new object is returned. Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(nnsa.TimeSeries) – TimeSeries object with the new signal.

property time

Shortcut to time_array (return the time array corresponding to self.signal).

Returns:: (np.ndarray) – time array (in seconds).

property time_array

Return the time array corresponding to self.signal.

Returns:: (np.ndarray) – time array (in seconds).

transform(fun, fs=None, label=None, unit=None, maintain_dtype=True, inplace=False)[source]

Apply a custom function to the signal.

Parameters:

fun (function) – function that transform the data. Takes in a 1D array and returns a 1D array.
fs (float) – sampling frequency of the transformed signal. If not specified, assumes that the transformed signal has the same sampling frequency as the original and an extra check will be performed to verify that the signal length (number of samples) did not change.
label (str) – optional new label for the transformed signal. If not provided, will keep the original label.
unit (str) – optional new unit for the transformed signal. If not provided, will keep the original unit.
maintain_dtype (bool) – if True, the new signal is forced to have the same dtype as self.
inplace (bool) – transform the data inplace (True) or return a new TimeSeries instance (False).

Returns:

ts (TimeSeries) – TimeSeries with the transformed data (if inplace is False).

property unit

Return the unit of the signal.

Returns:: (str) – the unit of the signal.

zscore(ddof=0, nan_policy='omit', inplace=False)[source]

Normalize the signal by centering and unit standard deviation.

Parameters:

ddof (int, optional) – degrees of freedom correction in the calculation of the standard deviation.
nan_policy (str, optional) – {‘propagate’, ‘raise’, ‘omit’} defines how to handle when input contains nan. ‘propagate’ returns nan, ‘raise’ throws an error, ‘omit’ performs the calculations ignoring nan values.
inplace (bool) – transform the data inplace (True) or return a new TimeSeries instance (False).

Returns:

ts (TimeSeries) – TimeSeries with the transformed data (if inplace is False).

Module contents

This package defines objects that contain data.

Classes:

`EegDataset`(*args[, label])	High-level interface for processing (multichannel) EEG for neonatal signal analysis.
`TimeSeries`(signal, fs[, label, unit, info, ...])	High-level interface for processing of any type of time series.

class nnsa.containers.EegDataset(*args, label=None)[source]

Bases: BaseDataset

High-level interface for processing (multichannel) EEG for neonatal signal analysis.

Methods:

`amplitude_eeg`([channel_1, channel_2, verbose])	Compute amplitude-integrated EEG (aEEG) from single bipolar channel continuous EEG.
`as_brain_rt`([bp_filter])	Preprocess the data to make it similar to the view as in BrainRT.
`brain_age_rf`([verbose])	Compute the brain age from the EEG using the random forest approach.
`brain_age_sinc`([verbose])	Compute the brain age from the EEG using the deep Sinc network.
`burst_detection`([create_bipolar_channels, ...])	Perform burst detection on all channels in the dataset.
`clamp`([threshold, channels, inplace, verbose])	Clamp EEG values by applying a clamping function to reduce dynamic range.
`coherence_graph`([preprocess, verbose])	Compute a connectivity graph, where the weights of the edges are based on the coherence between channels.
`compute_features`([verbose, chunk_size])	Compute EEG feature set.
`create_bipolar_channel`(channel_1, channel_2)	Create a bipolar channel by subtracting channel_2 from channel_1, i.e. bipolar channel = channel_1 - channel_2.
`create_bipolar_channels`(channels_1, channels_2)	Create a set of bipolar channels by subtracting channels_2 from channels_1.
`detect_anomalous_channels`([window, ...])	Simple method to detect anomalous high-frequency/amplitude channels by setting a threshold on the line length.
`detect_artefacts`([multi_channel_cnn, verbose])	Helper function to quickly detect artefacts using a combination of methods (see code).
`detect_artefacts_amplitude`(threshold_high[, ...])	Detect locations of artefacts by settings thresholds on the running mean/maximum of the absolute amplitude.
`detect_artefacts_amplitude_kaupilla`([...])	Detect locations of artefacts by settings thresholds on the amplitude as proposed by Kaupilla et al. 2018.
`detect_artefacts_cnn`([preprocess, ...])	Detect locations of artefacts based on clean EEG detection with CNN.
`detect_artefacts_kota`([notch_filter, bp_filter])	Simple method to detect small and large amplitude artefacts.
`detect_artefacts_method`(how, **kwargs)	Shortcut to any of the artefact removal functions.
`detect_artefacts_rfc`([pma, preprocess, verbose])	Detect locations of artefacts based on a sample supervised random forest classifier from the artefact_detection package.
`filter`(*args[, remove_mean])	Calls the parent function, but with remove_mean set to True by default.
`filter_saved_filter`(*args[, remove_mean])	Calls the parent function, but with remove_mean set to True by default.
`filtfilt`(*args[, remove_mean])	Calls the parent function, but with remove_mean set to True by default.
`from_array`(eeg, fs[, channel_labels])	Create an EegDataset from a 2D array (channels x time).
`get_channel`(channel[, make_copy])	Return a channel as TimeSeries.
`get_segments`(segment_length[, overlap, ...])	Segment the EEG data and return the segmented data as a 3D array.
`kirubin_features`([reference_channel, ...])	Compute Kirubin's feature set.
`mean`([channels, label])	Return the nanmean of the specified channels as a TimeSeries.
`median`([channels, label])	Return the nanmedian of the specified channels as a TimeSeries.
`notch_filt`(*args[, remove_mean])	Calls the parent function, but with remove_mean set to True by default.
`plot`([begin, end, channels, color, scale, ...])	Plot the EEG data of specified channels for a specifiec time frame.
`plot_mask`(mask[, time_scale, color, ...])	Plot a shaded mask over an EEG plot.
`power_analysis`([verbose])	Calls the paretn method, but sets some common frequency bands for EEG.
`read_begin_end_time`(filepath)	Read the start and end time (wrt time offset) of the EEG data in a HDF5 file.
`read_edf`(filepath[, begin, end])	Read an EegDataset object from an .edf file.
`read_hdf5`(filepath[, begin, end])	Read an EegDataset object from an .hdf5 file.
`read_mat`(filepath[, begin, end, loadmat_kwargs])	Read an EegDataset object from a .mat file.
`read_pickle`(filepath[, begin, end])	Read an EegDataset object from a .pkl file.
`read_set`(filepath[, begin, end, loadmat_kwargs])	Read an EegDataset object from a .set file (from Matlab EEGLAB).
`reference`([reference_channel, ...])	Reference all EEG signals to reference_channel, i.e. subtract the signal of the reference_channel from all other EEG channels.
`remove_artefact_channels`([inplace])	Remove channels that do not meet the quality criteria.
`remove_artefacts_amplitude`([notch_filter, ...])	Remove artefacts as detected by self.detect_artefacts_amplitude().
`remove_artefacts_derivative`([threshold, inplace])	Remove artefacts based on a threshold on the derivative of the filtered signal.
`remove_artefacts_kota`([notch_filter, ...])	Remove artefacts as detected by self.detect_artefacts_kota().
`remove_artefacts_mask`(mask_ds[, inplace])	Insert nans where boolean mask is True.
`remove_artefacts_method`(how, **kwargs)	Shortcut to any of the artefact removal functions.
`remove_artefacts_rfc`(pma[, preprocess, inplace])	Remove artefacts based on a sample supervised random forest classifier from the artefact_detection package.
`save_csv`(filepath[, overwrite])	Save the EegDataset data to a .csv (comma-separated value) file.
`save_hdf5`(filepath[, mode, overwrite])	Save the EegDataset data to a .hdf5 file.
`save_mat`(filepath[, overwrite])	Save the EegDataset data to a .mat file.
`save_pickle`(filepath[, overwrite])	Save the EegDataset data to a .pkl (pickle) file.
`sleep_stages_cnn`([preprocess, remove_flats, ...])	Automatic sleep stage classification using a Convolutional Neural Network.
`sleep_stages_robust`([verbose])	Automatic robust sleep stage classification.
`substitute_bad_channels`(af_mask[, inplace])	Find segments with bad channels in the EEG and substitute by the mean of the good channels.

Attributes:

signal

Return the EEG data as a numpy array (channels, time).

amplitude_eeg(channel_1='EEG C3', channel_2='EEG C4', verbose=1, **kwargs)[source]

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

Use on raw EEG data.

Parameters:

channel_1 (str, optional) – the label of the first channel. Defaults to ‘EEG C3’.
channel_2 (str, optional) – the label of the second channel (will be subtracted from the first channel). Defaults to ‘EEG C4’.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the AmplitudeEeg class.

Returns:

result (nnsa.AmplitudeEegResult) – object containing the aEEG.

as_brain_rt(bp_filter=True)[source]

Preprocess the data to make it similar to the view as in BrainRT.

Creates bipolar channels and filter.

Parameters:: bp_filter (bool) – if True, filter the data as in Brain RT (with a first order bandpass Butterworth).
Returns:: eeg_ds (nnsa.EegDataset) – preprocessed dataset (new object).

brain_age_rf(verbose=1, **kwargs)[source]

Compute the brain age from the EEG using the random forest approach.

Use on raw EEG data.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the BrainAge class.

Returns:

result (BrainAgeResult) – object containing the brain age.

brain_age_sinc(verbose=1, **kwargs)[source]

Compute the brain age from the EEG using the deep Sinc network.

Use on raw EEG data.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the BrainAgeSinc class.

Returns:

result (BrainAgeResult) – object containing the brain age.

burst_detection(create_bipolar_channels=True, verbose=1, **kwargs)[source]

Perform burst detection on all channels in the dataset.

This is a wrapper that prepares the input for BurstDetection.burst_detection() and returns the result.

Parameters:

create_bipolar_channels (bool, optional) – if True, automatically create bipolar channels according to the method used. If False, run the algorithm on the channels as currently in the object. Defaults to True.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the BurstDetection class.

Returns:

result (nnsa.BurstDetectionResult) – the result of the burst detection.

clamp(threshold=250, channels=None, inplace=False, verbose=1)[source]

Clamp EEG values by applying a clamping function to reduce dynamic range.

Parameters:

threshold (float) – threshold for the clamping function.
inplace (bool, optional) – whether to apply inplace (True) or not.
verbose (int, optional) – verbosity level.

Returns:

ds_out (EegDataset) – new Dataset object (only returned if inplace is False).

coherence_graph(preprocess=False, verbose=1, **kwargs)[source]

Compute a connectivity graph, where the weights of the edges are based on the coherence between channels.

This is a wrapper that prepares the input for CoherenceGraph.coherence_graph() and returns the result.

Parameters:

preprocess (bool, optional) – apply a default preprocessing routine on the data before feature computation (True) or not (False). Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the CoherenceGraph class.

Returns:

result (nnsa.CoherenceGraphResult) – an object containing the resulting adjacency matrices of the graphs.

compute_features(verbose=1, chunk_size=None, **kwargs)[source]

Compute EEG feature set.

Parameters:

kwargs – for EegFeatures().
verbose (int) – verbosity level.
chunk_size (int) – number of time samples to process at once. If None, a suitable chunk_size is chosen automatically.

Returns:

result (FeatureSetResult) – feature set result.

create_bipolar_channel(channel_1, channel_2, label=None)[source]

Create a bipolar channel by subtracting channel_2 from channel_1, i.e. bipolar channel = channel_1 - channel_2.

Parameters:

channel_1 (str) – the label of the first channel.
channel_2 (str) – the label of the second channel (will be subtracted from the first channel).
label (str, optional) – label for the new bipolar channel. If None, a label will automatically be created from channel_1 and channel_2. Defaults to None.

Returns:

ts_bipolar (nnsa.TimeSeries) – TimeSeries object holding the bipolar channel data.

create_bipolar_channels(channels_1, channels_2, labels=None, missing_mode='error')[source]

Create a set of bipolar channels by subtracting channels_2 from channels_1.

channels_new[i] = channels_1[i] - channels_2[i]

Parameters:

channels_1 (list) – the labels of the first channels.
channels_2 (list) – the labels of the second channels (will be subtracted from the first channel). Must have the same length as channels_1.
labels (str, optional) – label for the new bipolar channels. Must have the same length as channels_1. If None, labels will automatically be created from channels_1 and channels_2. Defaults to None.
missing_mode (str, optional) – what to do if a specified channel is missing from the dataset. Choose from: - ‘error’: raise a ValueError if a channel is specified that is not in the EEG dataset. - ‘ignore’: ignore the requested bipolar channels that could not be created. - ‘warn’: ignore, but display a warning.

Returns:

ds_bipolar (nnsa.EegDataset) – EegDataset object holding the bipolar channels data.

detect_anomalous_channels(window=3, std_factor=8, p_trim=0.25, verbose=0)[source]

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

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

Parameters:

window (float) – the window length (seconds) in which to compute line length.
std_factor (float) – the factor for std determining the threshold (mean+`std_factor*std).
p_trim (float) – the relative amount of channels to strip before computing the mean and std. The channels with the highest line lengths are stripped/excluded.
verbose (int) – verbosity level.

detect_artefacts(multi_channel_cnn=True, verbose=1)[source]

Helper function to quickly detect artefacts using a combination of methods (see code).

Apply to raw EEG.

Parameters:

multi_channel_cnn (bool) – whether to use the multi-channel CNN (True) or not (False).
verbose (int) – verbosity level.

Returns:

af_ds (EegDataset) – EegDataset with artefact masks consisting of boolean values: True at locations of artefacts, False otherwise.

detect_artefacts_amplitude(threshold_high, threshold_low=0, window=1, how='max')[source]

Detect locations of artefacts by settings thresholds on the running mean/maximum of the absolute amplitude.

Returns a boolean mask where True values indicate locations where x < threshold_low or x > threshold_high, where x is the moving average/maximum of the absolute signal values in a window of window seconds.

Parameters:

threshold_high (float) – threshold in uV.
threshold_low (float) – threshold in uV.
window (float) – window for the moving average in seconds.
how (str) – whether to take the moving ‘mean’ or ‘max’.

Returns:

af_ds (EegDataset) – EegDataset with artefact masks consisting of boolean values: True at locations of artefacts, False otherwise.

detect_artefacts_amplitude_kaupilla(notch_filter=True, bp_filter=True)[source]

Detect locations of artefacts by settings thresholds on the amplitude as proposed by Kaupilla et al. 2018.

To apply to raw EEG data: set notch_filter and bp_filter to True.

Parameters:

notch_filter (bool) – specify whether the EEG needs to be filtered. Set to True if eeg is raw data.
bp_filter (bool) – specify whether the EEG needs to be filtered. Set to True if eeg is raw data.

Returns:

af_ds (EegDataset) – EegDataset with artefact masks consisting of boolean values: True at locations of artefacts, False otherwise.

detect_artefacts_cnn(preprocess=None, detect_flats=True, detect_peaks=True, verbose=1, **kwargs)[source]

Detect locations of artefacts based on clean EEG detection with CNN.

EEG data must be referenced to Cz. If Cz is in self, referencing will be done automatically. If Cz is not present, referencing will be ignored (assuming the EEG data is already referenced).

Apply to raw EEG data and set preprocess_eeg to True.

Parameters:

preprocess (bool) – specify whether the EEG needs to be preprocessed (filtered, resampled). Set to True if eeg is raw data. If not specified, preprocessing will be done if fs is not as required by the model, otherwise not.
detect_flats (bool) – if True, computes moving std in short windows and if its below a threshold, the sample is marked as artefact (since the CNN might not catch this).
detect_peaks (bool) – if True, computes moving max abs amplitude in short windows and if its above a threshold, the sample is marked as artefact (since the CNN might not catch this).
verbose (int) – verbosity level.
**kwargs (dict) – for CleanDetectorCnn().

Returns:

af_ds (EegDataset) – EegDataset with artefact masks consisting of boolean values: True at locations of artefacts, False otherwise.

detect_artefacts_kota(notch_filter=True, bp_filter=True)[source]

Simple method to detect small and large amplitude artefacts.

Apply to raw data referenced to Cz with notch_filter and bp_filter set to True.

https://doi.org/10.1016/j.pediatrneurol.2021.06.001

detect_artefacts_method(how, **kwargs)[source]: Shortcut to any of the artefact removal functions.

detect_artefacts_rfc(pma=None, preprocess=None, verbose=1, **kwargs)[source]

Detect locations of artefacts based on a sample supervised random forest classifier from the artefact_detection package.

EEG data must be referenced to Cz. If Cz is in self, referencing will be done automatically. If Cz is not present, referencing will be ignored (assuming the EEG data is already referenced).

To apply to raw EEG data: set preprocess_eeg to True.

See also

RfcArtefactDetector

Parameters:

pma (float) – PMA of the neonate at time of recording. Optional dependeing on model, see RfcArtefactDetector.predict().
preprocess (bool) – specify whether the EEG needs to be preprocessed (filtered, resampled). Set to True if eeg is raw data (but it should still be referenced to Cz). If not specified, preprocessing will be done if fs is not 128, otherwise not.
verbose (int) – verbosity level.
**kwargs (dict) – for RfcArtefactDetector().

Returns:

af_ds (EegDataset) – EegDataset with artefact masks consisting of boolean values: True at locations of artefacts, False otherwise.

filter(*args, remove_mean=True, **kwargs)[source]: Calls the parent function, but with remove_mean set to True by default.

filter_saved_filter(*args, remove_mean=True, **kwargs)[source]: Calls the parent function, but with remove_mean set to True by default.

filtfilt(*args, remove_mean=True, **kwargs)[source]: Calls the parent function, but with remove_mean set to True by default.

static from_array(eeg, fs, channel_labels=None, **kwargs)[source]

Create an EegDataset from a 2D array (channels x time).

Parameters:

eeg (np.ndarray) – 2d array with dimensions (channels, time).
fs (float) – sample frequency in Hz.
channel_labels (list) – list with length len(eeg) containing labels for the channels. If None, will create default numbered names, like Ch1, Ch2, Ch3, …
**kwargs – optional keyword arguments for nnsa.TimeSeries.

Returns:

ds (nnsa.EegDataset) – EegDataset with the data from the array.

Examples

>>> eeg = np.random.rand(8, 10000)
>>> eeg_ds = EegDataset.from_array(eeg, fs=250, channel_labels=list(range(8)))

get_channel(channel, make_copy=True)[source]

Return a channel as TimeSeries. Can also be a bipolar channel.

Parameters:

channel (str) – channel label, or a bipolar channel.
make_copy (bool) – if True, the returned TimeSeries is always a copy. If False, the returned TimeSeries may be the same object as in self, if channel is in self.

Returns:

ts (TimeSeries) – time series containing the channel signal.

get_segments(segment_length, overlap=0, channels_last=True)[source]

Segment the EEG data and return the segmented data as a 3D array.

Parameters:

segment_length (float) – segment length in seconds.
overlap (float) – segment overlap in seconds.
channels_last (bool) – if True, the returned array has shape (n_segments, n_time, n_channels). If False, the shape is (n_segments, n_channels, n_time).

Returns:

eeg_seg (np.ndarray) – 3D array with length equal to the number of segments. The other two dimensions are time and channels, their order depends on channels_last.

kirubin_features(reference_channel=None, preprocess=False, inplace=False, verbose=1, **kwargs)[source]

Compute Kirubin’s feature set.

This is a wrapper that prepares the input for KirubinFeatures.wct() and returns the result.

Parameters:

reference_channel (str, optional) – specify how to reference the data. If no referencing is desired, specify None.
preprocess (bool, optional) – apply a default preprocessing routine on the data before feature computation (True) or not (False). Defaults to False.
inplace (bool, optional) – if preprocess_eeg is True, specify if the preprocessing should be inplace or not. Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the KirubinFeatures class.

Returns:

result (nnsa.KirubinFeaturesResult) – the result with the features.

mean(channels=None, label=None, **kwargs)[source]

Return the nanmean of the specified channels as a TimeSeries.

Parameters:

channels (list, optional) – list with labels of the signals to be average. If None, all signals in the Dataset are averaged. Defaults to None.
label (str, optional) – label for returned TimeSeries.
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ts (nnsa.TimeSeries) – TimeSeries containing the median of the channels.

median(channels=None, label=None, **kwargs)[source]

Return the nanmedian of the specified channels as a TimeSeries.

Parameters:

channels (list, optional) – list with labels of the signals to be average. If None, all signals in the Dataset are averaged. Defaults to None.
label (str, optional) – label for returned TimeSeries.
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ts (nnsa.TimeSeries) – TimeSeries containing the median of the channels.

notch_filt(*args, remove_mean=True, **kwargs)[source]: Calls the parent function, but with remove_mean set to True by default.

plot(begin=None, end=None, channels=None, color=None, scale=None, relative_time=False, time_scale=None, ax=None, legend=True, **kwargs)[source]

Plot the EEG data of specified channels for a specifiec time frame.

Assumes that all channels have same sampling frequency and unit. Raises a NotImplementedError if this is not the case.

Parameters:

begin (float, optional) – begin time in seconds, relative to the beginning of the loaded signal (ignores any offset). Defaults to 0.
end (float, optional) – end time in seconds or None to specify the end of the entire signal. Relative to the beginning of the loaded signal ignores any offset. Defaults to None.
channels (list, optional) – list of labels specifying the channels to plot, in order bottom to up. If None, all EEG channels in the EegDataset are plotted. Defaults to None.
color (str or array or None) – if str or array, use this as the color for all channels. If None, the default colors will be used to plot each channel in a different color.
scale (int, optional) – value (in the same unit as the data) by which to scale the data (data is divided by scale). This factor must aim to squeeze most data between -0.5 and 0.5. If None, this scale is determined automatically. Default is None.
relative_time (bool, optional) – if True, the time axis is relative to the start of the segment to plot. If False, the time axis will correspond to the time in the recording.
time_scale (str, optional) – the time scale to use. Choose from ‘seconds’, ‘minutes’, ‘hours’, None. If None or ‘timedelta’, plots with a datetime.timedelta format (hh:mm:ss).
ax (plt.Axes, optional) – axes to plot in. If None, plots in a new figure. Defaults to None.
legend (bool, optional) – add a legend (True) indicating the scale or not (False). Defaults to True.
**kwargs (optional) – optional keyword arguments for the plt.plot() function.

Returns:

ax (plt.axes) – axes instance.

plot_mask(mask, time_scale='seconds', color=None, skip_value=0, ax=None, **kwargs)[source]

Plot a shaded mask over an EEG plot.

Parameters:

mask (np.ndarray) – mask with shape (n_time, n_channels).
time_scale (str) – time scale in which to plot.
color (str, array, dict) – color or dictionary of colors for plotting the labels in mask.
skip_value (int, bool, float or list) – value(s) in mask to not plot.
ax (plt.Axes) – axes to plot in.
**kwargs – for plot().

power_analysis(verbose=1, **kwargs)[source]: Calls the paretn method, but sets some common frequency bands for EEG.

static read_begin_end_time(filepath)[source]

Read the start and end time (wrt time offset) of the EEG data in a HDF5 file.

Parameters:: filepath (str) – filepath to read.
Returns:: begin, end (float) – begin and end time in seconds.

static read_edf(filepath, begin=None, end=None, **kwargs)[source]

Read an EegDataset object from an .edf file.

Parameters:

filepath (str) – filepath to read.
begin (float, optional) – start second.
end (float, optional) – end second.
**kwargs (optional) – keyword arguments for EdfReader.read_eeg_dataset().

Returns:

ds (nnsa.EegDataset) – EegDataset object with data read from the file.

static read_hdf5(filepath, begin=None, end=None, **kwargs)[source]

Read an EegDataset object from an .hdf5 file.

Parameters:

filepath (str) – filepath to read.
begin (float, optional) – start second (wrt time offset).
end (float, optional) – end second (wrt time offset).
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ds (nnsa.EegDataset) – EegDataset object with data read from the file.

Examples

>>> signal = np.random.rand(8, 1000)
>>> eeg_ds = EegDataset()
>>> ts_all = [TimeSeries(signal=signal[i], fs=10, label=i) for i in range(len(signal))]
>>> eeg_ds.append(ts_all)
>>> eeg_ds.save_hdf5('testfile.hdf5')
>>> ds_read = EegDataset.read_hdf5('testfile.hdf5')
>>> ds_read_epoch = EegDataset.read_hdf5('testfile.hdf5', begin=10, end=20)
>>> os.remove('testfile.hdf5')
>>> assert_equal(eeg_ds.signal, ds_read.signal)
>>> assert_equal(eeg_ds.extract_epoch(begin=10, end=20).signal, ds_read_epoch.signal)

static read_mat(filepath, begin=None, end=None, loadmat_kwargs=None, **kwargs)[source]

Read an EegDataset object from a .mat file.

Parameters:

filepath (str) – filepath to read.
begin (float, optional) – start second (wrt time offset).
end (float, optional) – end second (wrt time offset).
loadmat_kwargs (dict, optional) – dict with keyword arguments for scipy.io.loadmat()/
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ds (nnsa.EegDataset) – EegDataset object with data read from the file.

static read_pickle(filepath, begin=None, end=None, **kwargs)[source]

Read an EegDataset object from a .pkl file.

Parameters:

filepath (str) – filepath to read.
begin (float, optional) – start second (wrt time offset).
end (float, optional) – end second (wrt time offset).
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ds (nnsa.EegDataset) – EegDataset object with data read from the file.

static read_set(filepath, begin=None, end=None, loadmat_kwargs=None, **kwargs)[source]

Read an EegDataset object from a .set file (from Matlab EEGLAB).

Parameters:

filepath (str) – filepath to read.
begin (float, optional) – start second (wrt time offset).
end (float, optional) – end second (wrt time offset).
loadmat_kwargs (dict, optional) – dict with keyword arguments for scipy.io.loadmat()/
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ds (nnsa.EegDataset) – EegDataset object with data read from the file.

reference(reference_channel='Cz', remove_reference=True, inplace=False, verbose=1)[source]

Reference all EEG signals to reference_channel, i.e. subtract the signal of the reference_channel from all other EEG channels.

Parameters:

reference_channel (str, optional) – label of the channel to use as reference. Can also be ‘average’ to subtract the average channel. Default is ‘Cz’.
remove_reference (bool, optional) – if True, remove the reference channel from the referenced dataset. If False, keep the reference channel after referencing (this channel will be zero everywhere). Default is True.
inplace (bool, optional) – if True, the referenced signals will replace the original signals in this EegDataset. If False (default), the function returns a new EegDataset object containing the referenced signals, leaving the data in the current EegDataset unchanged. Note that if only certain channels are referenced, the newly created EegDataset object will only contain those channels.
verbose (int, optional) – verbose level. Defaults to 1.

remove_artefact_channels(inplace=False, **kwargs)[source]

Remove channels that do not meet the quality criteria.

Parameters:

inplace (bool, optional) – If True, the channel is removed directly from the EegDataset object itself. If False, the function returns a copy of the original EegDataset object in which the artefacted channels are removed, leaving the data in the current EegDataset unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for overruling default signal quality criteria (see nnsa.artefacts.artefact_detection.default_eeg_signal_quality_criteria()).

Returns:

(EegDataset) – new EegDataset object containing the same signals, except for the removed channels (only if inplace is False).

remove_artefacts_amplitude(notch_filter=True, bp_filter=True, inplace=False)[source]: Remove artefacts as detected by self.detect_artefacts_amplitude().

remove_artefacts_derivative(threshold=23000, inplace=False)[source]

Remove artefacts based on a threshold on the derivative of the filtered signal.

Apply this to raw EEG data.

Args: TODO: inplace:

Returns:: EegDataset where the artefacts are replaced by nans.

remove_artefacts_kota(notch_filter=True, bp_filter=True, inplace=False, verbose=1)[source]: Remove artefacts as detected by self.detect_artefacts_kota().

remove_artefacts_mask(mask_ds, inplace=False)[source]

Insert nans where boolean mask is True.

Parameters:: mask_ds (BaseDataset) – dataset with boolean masks for each of the signals in self.

remove_artefacts_method(how, **kwargs)[source]: Shortcut to any of the artefact removal functions.

remove_artefacts_rfc(pma, preprocess=None, inplace=False, **kwargs)[source]

Remove artefacts based on a sample supervised random forest classifier from the artefact_detection package.

EEG data must be referenced to Cz. If Cz is in self, referencing will be done automatically. If Cz is not present, referencing will be ignored (assuming the EEG data is already referenced).

To apply to raw EEG data: set preprocess_eeg to True.

See also

RfcArtefactDetector, self.detect_artefacts_rfc().

Parameters:

pma (np.ndarray) – PMA of the neonate at time of recording.
preprocess (bool) – specify whether the EEG needs to be preprocessed (filtered, resampled). Set to True if eeg is raw data (but it should still be referenced to Cz). If not specified, preprocessing will be done if fs is not 128, otherwise not.
inplace (bool) – whether to remove in place or not.
**kwargs (dict) – for RfcArtefactDetector().

Returns:

ds_out (EegDataset) – EegDataset where the artefacts are replaced by nans.

save_csv(filepath, overwrite=False, **kwargs)[source]

Save the EegDataset data to a .csv (comma-separated value) file.

This is slow, as it used the pandas functionality.

Parameters:

filepath (str) – filepath to save to.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists. Defaults to False.
**kwargs (dict, optional) – for pandas.DataFrame.to_csv().

save_hdf5(filepath, mode='w', overwrite=False)[source]

Save the EegDataset data to a .hdf5 file.

Parameters:

filepath (str) – filepath to save to.
mode (str, optional) – ‘w’ for write mode or ‘a’ for append mode. Defaults to ‘w’.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists. Defaults to False.

save_mat(filepath, overwrite=False)[source]

Save the EegDataset data to a .mat file.

Parameters:

filepath (str) – filepath to save to.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists. Defaults to False.

save_pickle(filepath, overwrite=False, **kwargs)[source]

Save the EegDataset data to a .pkl (pickle) file.

Parameters:

filepath (str) – filepath to save to.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists. Defaults to False.
**kwargs (dict, optional) – for nnsa.pickle_save().

property signal

Return the EEG data as a numpy array (channels, time).

Returns:: (np.ndarray) – EEG data matrix.

sleep_stages_cnn(preprocess=None, remove_flats=True, remove_baseline_wander=False, stepsize=None, verbose=1, preprocess_kwargs=None, **kwargs)[source]

Automatic sleep stage classification using a Convolutional Neural Network.

This is a wrapper that prepares the input for SleepStagesCnn.sleep_stages_cnn() and returns the result.

Parameters:

preprocess (bool, optional) – if True, the EEG data in ds will be processed by filtering and resampling correspondingly. If False, the data in ds will not be preprocessed (use this when the ds already contains correspondingly prepreocessed data). If None, preprocessing will be done if the sampling frequency of the data does not match the required fs by the model.
remove_flats (bool, optional) – if True, removes flatlines.
remove_baseline_wander (bool) – if True, removes excessive baseline wander by applying a HP filter. This was not part of original preprocessing during training, and most EEGs don’t need this (in the original preprocessing there is already a HP filter, but milder). If not needed, don’t do this additional baseline removal.
stepsize (float) – stepsize (in seconds) for sleep stage prediction. If None, stepsize is equal to segment length (no overlap).
verbose (int, optional) – verbose level (0 or 1). Defaults to 1.
preprocess_kwargs (dict, optional) – dict with optional keyword arguments for SleepStagesCnn.preprocess_recording(). Defaults to None.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the SleepStagesCnn class.

Returns:

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

sleep_stages_robust(verbose=1, **kwargs)[source]

Automatic robust sleep stage classification.

This is a wrapper that prepares the input for SleepStagesRobust.process() and returns the result.

Args:

verbose (int, optional): verbose level (0 or 1).
Defaults to 1.

**kwargs (optional): optional keyword arguments to the SleepStagesRobust class.

Returns:: result (nnsa.SleepStagesCnnResult) – nnsa object containing the results.

substitute_bad_channels(af_mask, inplace=False, **kwargs)[source]

Find segments with bad channels in the EEG and substitute by the mean of the good channels.

Parameters:

af_mask (np.ndarray or EegDataset) – boolean mask for the EEG array data with True at locations of artefacts. Shape should be (n_channels, n_time). An incompatible shape will be transposed if that makes it compatible, or raises an error otherwise.
inplace (bool) – whether to apply inplace (True) or not (False).
kwargs – for substitute_bad_channels.

Returns:

ds_out (EegDataset) – cleaned EegDataset with bad channels substituted.

class nnsa.containers.TimeSeries(signal, fs, label='no label', unit='a.u.', info=None, time_offset=0, check_label=False, check_unit=False, **kwargs)[source]

Bases: ClassWithParameters

High-level interface for processing of any type of time series.

Parameters:

signal (np.ndarray) – 1D array containing the signal.
fs (float) – sampling frequency of the signal array.
label (str, optional) – the label of the signal (if check_label is True, should be a valid standardized name, see check_label()).
unit (str, optional) – the unit of the signal (should be a valid standardized unit, see check_unit()). Defaults to ‘a.u’.
info (dict, optional) – dict with info about the signal. Dict can contain ‘source’, specifying the path to the source file of the signal. It may have an optional additional field ‘processing’, which is a list of strings specifying several processing steps that were applied to the original signal loaded from ‘source’. If None, the ‘source’ field in the dict is set to ‘UNKNOWN’. Defaults to None.
time_offset (float, optional) – optional time offset in seconds. Time array starts at this offset. Defaults to 0.
check_label (bool, optional) – if True, the passed label is checked whether it is valid. If False, no check is performed and any label may be given. Defaults to True.
check_unit (bool, optional) – if True, the passed unit is checked whether it is valid. If False, no check is performed and any unit may be given. Defaults to True.
**kwargs (optional) – optional keyword arguments for setting parameters.

Methods:

`amplitude_eeg`([verbose])	Compute amplitude-integrated EEG (aEEG) from single channel continuous EEG.
`as_dict`()	Return the TimeSeries data in a dictionary.
`astype`(dtype[, inplace])
`burst_detection`([verbose])	Perform burst detection.
`clamp`(threshold[, inplace])	Clamp values by applying a clamping function to reduce dynamic range.
`compute_power_cwt`([freq_low, freq_high, inplace])	Compute power in specified band.
`cwt`([verbose])	Apply a continuous wavelet transform on the signal.
`default_parameters`()	Return the default parameters as a dictionary.
`demean`([mean_fun, inplace])	Demean the time series.
`detrend`(args, *kwargs)
`detrend_poly`(order[, inplace])	Detrend the time series using a polynomial of a specific order.
`envelope`([verbose])	Compute envelope.
`extract_epoch`([begin, end, error_mode])	Extract a piece of data in the specified interval.
`fill_nan`(value[, inplace, verbose])	Replace nans in the signal by a constant value.
`filter`(filter_obj[, remove_mean, inplace, ...])	Filter the signal with the given 1-D digital filter.
`filter_saved_filter`(filter_name[, ...])	Filter the signal with a specified saved filter.
`filtfilt`(filter_obj[, remove_mean, inplace, ...])	Filter the signal with the given filter using zero-phase filtering (filtfilt).
`interp`(t, **kwargs)	Wrapper for np.interp, performing linear interpolation to get the signal values at times t.
`interp_nan`(args, *kwargs)
`interpolate_nan`([inplace, max_nan_length])	Linearly interpolate nan values.
`line_length`([verbose])	Compute line length feature.
`mean`([max_nan_frac])	Return the mean.
`median`([max_nan_frac])	Return the median.
`merge`(other[, inplace])	Merge other TimeSeries object(s) into one object based on their time arrays.
`moving_average`(args, *kwargs)	Helper-function to apply a moving average.
`moving_max`(window[, inplace])	Helper-function to apply a moving maximum.
`moving_mean`(window[, inplace])	Helper-function to apply a moving average.
`moving_median`(window[, inplace])	Helper-function to apply a moving average.
`multi_scale_entropy`([verbose])	Perform a multi-scale entropy (mse) analysis.
`multifractal_analysis`([verbose])	Perform a multifractal analysis (mfa).
`normalize`([how, inplace])	Normalize the signal.
`notch_filt`([f0, verbose, inplace])	Helper-function to apply a notch filter to remove e.g.
`plot`(*args[, begin, end, time_scale, ax])	Plot (part of) the signal.
`power_analysis`([verbose])	Perform a Fourier based power analysis.
`psd`([verbose])	Estimate power spectral density.
`read_hdf5`(filepath[, label, begin, end])	Read a TimeSeries object from a .hdf5 file.
`read_mat`(filepath, **kwargs)	Read a TimeSeries object from a .mat file.
`read_pickle`(filepath, **kwargs)	Read a TimeSeries object from a pickle file.
`reference`(reference_signal, reference_label)	Reference the signal to reference_channel by subtracting reference_signal from the signal.
`remove_artefacts`([inplace])	Replace samples that are artefacts by np.nan
`remove_flatlines`(n_flatline[, inplace])	Replace flatlines by np.nan
`remove_neighborhood_artefacts`(size[, inplace])	Replace values by np.nan if sample sin their neighborhood are nan.
`remove_outliers`(*args[, inplace])	Replace outliers by np.nan
`remove_values`(*args[, inplace])	Replace values by np.nan
`resample`(fs_new[, method, inplace, verbose])	Resample the signal data to new sampling frequency fs_new.
`save_hdf5`(filepath[, mode, overwrite])	Save the TimeSeries data to a .hdf5 file.
`save_mat`(filepath[, overwrite])	Save the TimeSeries data to a MATLAB-style .mat file.
`save_pickle`(filepath[, overwrite])	Save the TimeSeries data to a pickle file.
`segment`(segment_length[, overlap])	Segment the signal (into smaller time segments).
`signal_quality`()	Collect some characteristics of the signal related to signal quality.
`stepwise_moving_average`(*args[, avg_fun])
`stepwise_reduce`(window[, stepsize, ...])	Compute stepwise value.
`transform`(fun[, fs, label, unit, ...])	Apply a custom function to the signal.
`zscore`([ddof, nan_policy, inplace])	Normalize the signal by centering and unit standard deviation.

Attributes:

`dtype`	Return the effective dtype (should be consistent with the dtype in the parameters).
`fs`	Return the sampling frequency of the signal.
`info`	Return the info dictionary.
`label`	Return the label of the signal.
`signal`	Return the signal array.
`time`	Shortcut to time_array (return the time array corresponding to self.signal).
`time_array`	Return the time array corresponding to self.signal.
`unit`	Return the unit of the signal.

amplitude_eeg(verbose=1, **kwargs)[source]

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

This is a wrapper that prepares the input for AmplitudeEeg.wct() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the AmplitudeEeg class.

Returns:

result (nnsa.AmplitudeEegResult) – object containing the aEEG.

as_dict()[source]: Return the TimeSeries data in a dictionary.

astype(dtype, inplace=False)[source]

burst_detection(verbose=1, **kwargs)[source]

Perform burst detection.

Note: this should be used on unfiltered data.

This is a wrapper that prepares the input for BurstDetection.burst_detection() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the BurstDetection class.

Returns:

result (nnsa.BurstDetectionResult) – the result of the burst detection.

clamp(threshold, inplace=False)[source]

Clamp values by applying a clamping function to reduce dynamic range.

Parameters:

threshold (float) – threshold for the clamping function.
inplace (bool, optional) – whether to apply inplace (True) or not.

Returns:

ts (TimeSeries) – new Dataset object (only returned if inplace is False).

compute_power_cwt(freq_low=None, freq_high=None, inplace=False, **kwargs)[source]

Compute power in specified band.

Parameters:

freq_low (float, optional) – lower frequency cutoff for bandpower. If None, takes lowest possible.
freq_high (float, optional) – upper frequency cutoff for bandpower. If None, takes highest possible.
inplace (bool, optional) – if True, replaces the signal in place by its power. If False, returns a new object.
**kwargs (optional) – optional keyword arguments for compute_power_cwt().

Returns:

ts (TimeSeries) – TimeSeries with power of the signal (if inplace is False).

cwt(verbose=1, **kwargs)[source]

Apply a continuous wavelet transform on the signal.

Parameters:

verbose (int, optional) – verbosity level.
**kwargs (optional) – keyword arguments for Cwt().

Returns:

CwtResult object containing the result.

static default_parameters()[source]

Return the default parameters as a dictionary.

Returns:: (dict) – a default set of parameters.

demean(mean_fun=<function nanmean>, inplace=False)[source]

Demean the time series.

Parameters:

mean_fun (function) – function that takes in a 1D array and retruns the mean that will be subtracted. Defaults to np.nanmean. Other possibilities could be np.nanmedian, np.mean, …
inplace (bool, optional) – whether to apply the operation inplace or return a new object.

Returns:

ts (nnsa.TimeSeries) – object with demeaned signal (returned if inplace is False).

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

detrend_poly(order, inplace=False)[source]

Detrend the time series using a polynomial of a specific order.

Parameters:

order (int) – degree of the polynomial.
inplace (bool, optional) – whether to apply the operation inplace or return a new object.

Returns:

ts (nnsa.TimeSeries) – object with detrended signal (returned if inplace is False).

property dtype: Return the effective dtype (should be consistent with the dtype in the parameters).

envelope(verbose=1, **kwargs)[source]

Compute envelope.

This is a wrapper that prepares the input for Envelope.envelope() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the Envelope class.

Returns:

result (nnsa.EnvelopeResult) – the result of the envelope computation.

Examples

To get the envelope data as a new TimeSeries object: >>> signal = 4 * np.sin(np.arange(10000)) >>> ts = TimeSeries(signal=signal, fs=100, label=’EEG Cz’, unit=’uV’, info={‘source’: ‘random’}) >>> envelope_result = ts.envelope(verbose=0) >>> ts_envelope = envelope_result.to_time_series() >>> print(type(ts_envelope).__name__) TimeSeries

>>> print(ts_envelope.signal.mean())
3.9998155216320725

extract_epoch(begin=None, end=None, error_mode='raise')[source]

Extract a piece of data in the specified interval.

Parameters:

begin (float, optional) – start time in seconds (including time_offset) of the epoch to extract. If negative, begin is duration + begin (python-like indexing). If None, the beginning of the signal is taken. Defaults to None.
end (float, optional) – end time in seconds (including time_offset) of the epoch to extract. If negative, end is duration + end (python-like indexing). If None, the end of the signal is taken. Must point to a time greater than begin. Defaults to None.
error_mode (str) – whether to ‘raise’ an error when no time overlap is found, or to just ‘warn’.

Returns:

ts_epoch (nnsa.TimeSeries) – a new TimeSeries object with only the data of the specified epoch.

fill_nan(value, inplace=False, verbose=0)[source]

Replace nans in the signal by a constant value.

Parameters:

value (float) – the value to fill with.
inplace (bool, optional) – if True, resamples inplace, else a new object is returned. Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(TimeSeries) – new TimeSeries object containing the new signal (if inplace is False).

filter(filter_obj, remove_mean=False, inplace=False, verbose=1, **kwargs)[source]

Filter the signal with the given 1-D digital filter.

Note: this introduces a delay in the filter signal. For zero-phase filtering use filtfilt.

Parameters:

filter_obj (FilterBase-derived) – a child class from the nnsa.FilterBase class. The fs property does not need to be set correctly, as it will be automatically (re)set in this function.
inplace (bool, optional) – if True, filters inplace, else a new object is returned. Defaults to False.
remove_mean (bool, optional) – remove the mean value after filtering (useful for EEG data).
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments passed on to the filter() function of filter_obj.

Returns:

(TimeSeries) – new TimeSeries object containing the filtered signal (if inplace is False).

filter_saved_filter(filter_name, remove_mean=False, inplace=False, verbose=1, **kwargs)[source]

Filter the signal with a specified saved filter.

This is just a wrapper of the nnsa.preprocessing.filter_saved_filter() function.

Parameters:

filter_name (str) – see nnsa.preprocessing.filter_saved_filter().
remove_mean (bool, optional) – remove the mean value after filtering (useful for EEG data).
inplace (bool, optional) – if True, resamples inplace, else a new object is returned. Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments passed on to nnsa.preprocessing.filter_saved_filter().

Returns:

(TimeSeries) – new TimeSeries object containing the filtered signal (if inplace is False).

filtfilt(filter_obj, remove_mean=False, inplace=False, verbose=1, **kwargs)[source]

Filter the signal with the given filter using zero-phase filtering (filtfilt).

Parameters:

filter_obj (FilterBase-derived) – a child class from the nnsa.FilterBase class. The fs property does not need to be set correctly, as it will be automatically (re)set in this function.
inplace (bool, optional) – if True, filters inplace, else a new object is returned. Defaults to False.
remove_mean (bool, optional) – remove the mean value after filtering (useful for EEG data).
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments passed on to the filtfilt() function of filter_obj.

Returns:

(TimeSeries) – new TimeSeries object containing the filtered signal (if inplace is False).

property fs

Return the sampling frequency of the signal.

Returns:: (float) – the sampling frequency of the signal.

property info

Return the info dictionary.

Returns:: (dict) – info dictionary.

interp(t, **kwargs)[source]

Wrapper for np.interp, performing linear interpolation to get the signal values at times t.

Parameters:

t (np.ndarray) – time instances at which to evaluate the signal.
**kwargs (optional) – optional keyword arguments for np.interp.

Returns:

y (np.ndarray) – 1D array with interpolated values.

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

interpolate_nan(inplace=False, max_nan_length=None)[source]

Linearly interpolate nan values.

Parameters:

inplace (bool, optional) – interpolate inplace (True) or return a copy (False). Defaults to False.
max_nan_length (int or str, optional) – number of maximum allowable length of a nan segment that we interpolate (in seconds). If ‘auto’, the average duration of a constant value in the signal is taken. If None, no limit is applied, i.e. all nans are interpolated. Defaults to None.

Returns:

ts (TimeSeries) – time series with nans interpolated (if inplace is False).

property label

Return the label of the signal.

Returns:: (str) – the label of the signal.

line_length(verbose=1, **kwargs)[source]

Compute line length feature.

This is a wrapper that prepares the input for LineLength.line_length() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the LineLength class.

Returns:

result (nnsa.LineLengthResult) – the result of the line length computation.

mean(max_nan_frac=1)[source]: Return the mean.

median(max_nan_frac=1)[source]: Return the median.

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

Merge other TimeSeries object(s) into one object based on their time arrays.

Fills gaps in between the time arrays with nan.

Parameters:

other (TimeSeries or list) – list with (compatible) TimeSeries objects.
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:

out (TimeSeries) – new TimeSeries object containing the merged time series (if inplace is False).

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

Helper-function to apply a moving average.

Parameters:

window (float) – window of the moving average (in seconds).
inplace (bool) – whether to apply the filter inplace or not.
**kwargs – for nnsa.moving_average()

Returns:

(TimeSeries) – filtered data (if inplace is True).

moving_max(window, inplace=False, **kwargs)[source]

Helper-function to apply a moving maximum.

Parameters:

window (float) – window of the moving maximum (in seconds).
inplace (bool) – whether to apply the filter inplace or not.
**kwargs – for nnsa.moving_max()

Returns:

(TimeSeries) – filtered data (if inplace is True).

moving_mean(window, inplace=False, **kwargs)[source]

Helper-function to apply a moving average.

Parameters:

window (float) – window of the moving average (in seconds).
inplace (bool) – whether to apply the filter inplace or not.
**kwargs – for nnsa.moving_average()

Returns:

(TimeSeries) – filtered data (if inplace is True).

moving_median(window, inplace=False, **kwargs)[source]

Helper-function to apply a moving average.

Parameters:

window (float) – window of the moving average (in seconds).
inplace (bool) – whether to apply the filter inplace or not.
**kwargs – for nnsa.moving_average()

Returns:

(TimeSeries) – filtered data (if inplace is True).

multi_scale_entropy(verbose=1, **kwargs)[source]

Perform a multi-scale entropy (mse) analysis.

This is a wrapper that prepares the input for MultiScaleEntropy.multi_scale_entropy() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the MultiScaleEntropy class.

Returns:

result (nnsa.MultiScaleEntropyResult) – the result of the mse analysis.

multifractal_analysis(verbose=1, **kwargs)[source]

Perform a multifractal analysis (mfa).

This is a wrapper that prepares the input for MultifractalAnalysis.multifractal_analysis() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for the MultifractalAnalysis class.

Returns:

result (nnsa.MultifractalAnalysisResult) – the result of the mfa analysis.

normalize(how='zscore', inplace=False, **kwargs)[source]

Normalize the signal.

Parameters:

how (str) – how to normalize. Choose from: - “zscore”
inplace (bool, optional) – whether to normalize inplace (True) or not.
**kwargs (dict) – for normalization functions. Depends on how (see code).

Returns:

(TimeSeries) – normalized signal (only returned if inplace is False).

notch_filt(f0=50, verbose=1, inplace=False, **kwargs)[source]

Helper-function to apply a notch filter to remove e.g. power line interference.

Parameters:

f0 (float or list) – frequencie(s) to suppress.
verbose (int) – verbosity level.
inplace (bool) – whether to apply the filter inplace or not.
**kwargs (optional) – for self.filtfilt().

Returns:

(TimeSeries) – filtered data (if inplace is True).

plot(*args, begin=None, end=None, time_scale='seconds', ax=None, **kwargs)[source]

Plot (part of) the signal.

Parameters:

*args (optional) – optional arguments for the plt.plot() function.
begin (float, optional) – begin time in seconds. If None, plots from the first sample. Default is None.
end (float, optional) – end time in seconds or None to specify the end of the entire signal. Default is None.
time_scale (str, optional) – the time scale to use. Choose from ‘seconds’, ‘minutes’, ‘hours’. Defaults to ‘seconds’.
ax (plt.Axes, optional) – axes to plot is. If None, plots in a new figure. Defaults to None.
**kwargs (optional) – optional keyword arguments for the plt.plot() function.

power_analysis(verbose=1, **kwargs)[source]

Perform a Fourier based power analysis.

This is a wrapper that prepares the input for PowerAnalysis.power_analysis() and returns the result.

Parameters:

verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the PowerAnalysis class.

Returns:

result (nnsa.PowerAnalysisResult) – the result of the power analysis.

psd(verbose=1, **kwargs)[source]

Estimate power spectral density.

This is a wrapper that prepares the input for Psd.psd() and returns the results.

Parameters:

verbose (int, optional) – verbose level. Defaults to 0.
**kwargs (optional) – optional keyword arguments to overrule default parameters of the Psd class.

Returns:

result (nnsa.PsdResult) – object containing the result of the psd.

static read_hdf5(filepath, label=None, begin=None, end=None, **kwargs)[source]

Read a TimeSeries object from a .hdf5 file.

Parameters:

filepath (str or opened file) – filepath to read or an open HDF5 file.
label (str, optional) – label of the hdf5 dataset to read. If None, reads the first TimeSeries that it can find in the file. Defaults to None.
begin (float, optional) – start second (wrt time offset).
end (float, optional) – end second (wrt time offset).
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ts (nnsa.TimeSeries) – TimeSeries object with data read from the file.

Examples

>>> signal = np.random.rand(1000)
>>> ts = TimeSeries(signal=signal, fs=10, label='EEG Cz')
>>> ts.save_hdf5('testfile.hdf5')
>>> ts_read = TimeSeries.read_hdf5('testfile.hdf5')
>>> ts_read_epoch = TimeSeries.read_hdf5('testfile.hdf5', begin=10, end=20)
>>> os.remove('testfile.hdf5')
>>> assert_equal(ts.signal, ts_read.signal)
>>> assert_equal(ts.extract_epoch(begin=10, end=20).signal, ts_read_epoch.signal)

static read_mat(filepath, **kwargs)[source]

Read a TimeSeries object from a .mat file.

Parameters:

filepath (str) – filepath to read.
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ts (nnsa.TimeSeries) – TimeSeries object with data read from the file.

Examples

>>> signal = np.random.rand(1000)
>>> ts = TimeSeries(signal=signal, fs=10, label='EEG Cz')
>>> ts.save_mat('testfile.mat')
>>> ts_read = TimeSeries.read_mat('testfile.mat')
>>> os.remove('testfile.mat')
>>> assert_equal(ts.signal, ts_read.signal)

static read_pickle(filepath, **kwargs)[source]

Read a TimeSeries object from a pickle file.

Parameters:

filepath (str) – filepath to read.
**kwargs (optional) – keyword arguments for TimeSeries().

Returns:

ts (nnsa.TimeSeries) – TimeSeries object with data read from the file.

Examples

>>> signal = np.random.rand(1000)
>>> ts = TimeSeries(signal=signal, fs=10, label='EEG Cz')
>>> ts.save_pickle('testfile.pkl')
>>> ts_read = TimeSeries.read_pickle('testfile.pkl')
>>> os.remove('testfile.pkl')
>>> assert_equal(ts.signal, ts_read.signal)

reference(reference_signal, reference_label, inplace=False, verbose=1)[source]

Reference the signal to reference_channel by subtracting reference_signal from the signal.

Parameters:

reference_signal (TimeSeries or np.ndarray) – 1D array containing the reference signal to subtract.
reference_label (str) – label of the reference signal.
inplace (bool, optional) – if True, referenced inplace, else a new object is returned. Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(TimeSeries) – new TimeSeries object containing the referenced signal.

remove_artefacts(inplace=False, **kwargs)[source]

Replace samples that are artefacts by np.nan

Parameters:

inplace (bool, optional) – If True, the samples are replaced directly from the TimeSeries object itself. If False, the function returns a copy of the original TimeSeries object in which the artefacted samples are replaced, leaving the data in the current TimeSeries unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for overruling default sample quality criteria (see nnsa.artefacts.artefact_detection.detect_artefact_samples()).

Returns:

(TimeSeries) – new TimeSeries object containing the same signal, but with artefacted samples changed to np.nan (only returned if inplace is False).

remove_flatlines(n_flatline, inplace=False, **kwargs)[source]

Replace flatlines by np.nan

Parameters:

n_flatline (float) – minimal number of seconds for a non-changing segment to be a flatline.
inplace (bool, optional) – If True, the samples are replaced directly from the TimeSeries object itself. If False, the function returns a copy of the original TimeSeries object in which the flatline samples are replaced, leaving the data in the current TimeSeries unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for remove_flatlines.

Returns:

(TimeSeries) – new TimeSeries object containing the same signal, but with flatline samples changed to np.nan (only returned if inplace is False).

remove_neighborhood_artefacts(size, inplace=False, **kwargs)[source]

Replace values by np.nan if sample sin their neighborhood are nan.

Parameters:

size (int) – size of the neighborhood (in seconds). E.g., if the neighborhood is 3, sample at t=t is an artefact if there is an artefact in the signal between t-1:t+1.
inplace (bool, optional) – If True, the samples are replaced directly from the TimeSeries object itself. If False, the function returns a copy of the original TimeSeries object in which the flatline samples are replaced, leaving the data in the current TimeSeries unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for remove_neighborhood_artefacts().

Returns:

(TimeSeries) – new TimeSeries object containing the same signal, but with specific samples changed to np.nan (only returned if inplace is False).

remove_outliers(*args, inplace=False, **kwargs)[source]

Replace outliers by np.nan

Parameters:

*args (float) – arguments for remove_outliers().
inplace (bool, optional) – If True, the samples are replaced directly from the TimeSeries object itself. If False, the function returns a copy of the original TimeSeries object in which the flatline samples are replaced, leaving the data in the current TimeSeries unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for remove_outliers().

Returns:

(TimeSeries) – new TimeSeries object containing the same signal, but with outlier samples changed to np.nan (only returned if inplace is False).

remove_values(*args, inplace=False, **kwargs)[source]

Replace values by np.nan

Parameters:

*args (float) – arguments for remove_values().
inplace (bool, optional) – If True, the samples are replaced directly from the TimeSeries object itself. If False, the function returns a copy of the original TimeSeries object in which the flatline samples are replaced, leaving the data in the current TimeSeries unchanged. Default is False.
**kwargs (optional) – optional keyword arguments for remove_values().

Returns:

(TimeSeries) – new TimeSeries object containing the same signal, but with specific samples changed to np.nan (only returned if inplace is False).

resample(fs_new, method='polyphase_filtering', inplace=False, verbose=1, **kwargs)[source]

Resample the signal data to new sampling frequency fs_new.

Deals with nans by interpolating them before resampling and putting nans back at locations near the artefacts.

Parameters:

fs_new (float) – new sampling frequency to resample to.
method (str, optional) –
the resampling method: If ‘polyphase_filtering’, the data will be resampled using polyphase filtering (see

scipy.signal.resample_poly).

If ‘interpolation’, the data will be resampled using interpolation (see scipy.interpolate.interp1d). Default is ‘polyphase_filtering’.
inplace (bool, optional) – if True, resamples inplace, else a new object is returned. Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.
**kwargs (optional) – optional keyword arguments for scipy’s resample/interpolation function that is applied (which depends on the method argument).

Returns:

(nnsa.TimeSeries) – TimeSeries object with the resampled signal.

save_hdf5(filepath, mode='w', overwrite=False)[source]

Save the TimeSeries data to a .hdf5 file.

Parameters:

filepath (str) – filepath to save to.
mode (str, optional) – ‘w’ for write mode or ‘a’ for append mode. Defaults to ‘w’.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists and mode is ‘w’. Defaults to False.

save_mat(filepath, overwrite=False)[source]

Save the TimeSeries data to a MATLAB-style .mat file.

Parameters:

filepath (str) – filepath to save to.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists. Defaults to False.

save_pickle(filepath, overwrite=False)[source]

Save the TimeSeries data to a pickle file.

Parameters:

filepath (str) – filepath to save to.
overwrite (bool, optional) – if True, overwrites existing files. If False, raises an error when filepath already exists. Defaults to False.

segment(segment_length, overlap=0)[source]

Segment the signal (into smaller time segments).

First segment starts at the start of the signal. Any left over samples at the end of the signal that cannot make up a segment of the specified length are ignored.

Parameters:

segment_length (float) – length of a segment in seconds.
overlap (float, optional) – overlap between succesive segments in seconds. Defaults to 0.

Yields:

(TimeSeries) – TimeSeries object holding the data of the next segment.

property signal

Return the signal array.

Returns:: (np.ndarray) – the (1D) signal array.

signal_quality()[source]

Collect some characteristics of the signal related to signal quality.

This is a wrapper of nnsa.artefacts.artefact_detection.signal_quality()

Returns:: (dict) – see nnsa.artefacts.artefact_detection.signal_quality()

stepwise_moving_average(*args, avg_fun=<function nanmean>, **kwargs)[source]

stepwise_reduce(window, stepsize=None, reduce_fun=<function nanmean>, max_nan=0.5, inplace=False, verbose=1)[source]

Compute stepwise value.

Parameters:

window (float) – length of the segments /moving window to compute the average in (in seconds).
stepsize (float) – stepsize of the moving average window in seconds. The output will have a sample frequency of 1/stepsize Hz. If None, stepsize will be eqaul to window.
reduce_fun (function, optional) – function to reduce a block a data. Must handle nan and accept an axis keyword. Defaults to np.nanmean.
max_nan (float, optional) – maximum fraction (0-1) of nan values in a window. If the fraction of nan samples exceeds max_nan, the mean is nan for that window. Defaults to 0.5.
inplace (bool, optional) – if True, operates inplace, else a new object is returned. Defaults to False.
verbose (int, optional) – verbose level. Defaults to 1.

Returns:

(nnsa.TimeSeries) – TimeSeries object with the new signal.

property time

Shortcut to time_array (return the time array corresponding to self.signal).

Returns:: (np.ndarray) – time array (in seconds).

property time_array

Return the time array corresponding to self.signal.

Returns:: (np.ndarray) – time array (in seconds).

transform(fun, fs=None, label=None, unit=None, maintain_dtype=True, inplace=False)[source]

Apply a custom function to the signal.

Parameters:

fun (function) – function that transform the data. Takes in a 1D array and returns a 1D array.
fs (float) – sampling frequency of the transformed signal. If not specified, assumes that the transformed signal has the same sampling frequency as the original and an extra check will be performed to verify that the signal length (number of samples) did not change.
label (str) – optional new label for the transformed signal. If not provided, will keep the original label.
unit (str) – optional new unit for the transformed signal. If not provided, will keep the original unit.
maintain_dtype (bool) – if True, the new signal is forced to have the same dtype as self.
inplace (bool) – transform the data inplace (True) or return a new TimeSeries instance (False).

Returns:

ts (TimeSeries) – TimeSeries with the transformed data (if inplace is False).

property unit

Return the unit of the signal.

Returns:: (str) – the unit of the signal.

zscore(ddof=0, nan_policy='omit', inplace=False)[source]

Normalize the signal by centering and unit standard deviation.

Parameters:

ddof (int, optional) – degrees of freedom correction in the calculation of the standard deviation.
nan_policy (str, optional) – {‘propagate’, ‘raise’, ‘omit’} defines how to handle when input contains nan. ‘propagate’ returns nan, ‘raise’ throws an error, ‘omit’ performs the calculations ignoring nan values.
inplace (bool) – transform the data inplace (True) or return a new TimeSeries instance (False).

Returns:

ts (TimeSeries) – TimeSeries with the transformed data (if inplace is False).