resurfemg.data_connector.data_classes module

Copyright 2022 Netherlands eScience Center and University of Twente Licensed under the Apache License, version 2.0. See LICENSE for details.

This file contains data classes for standardized data storage and method automation.

class resurfemg.data_connector.data_classes.EmgDataGroup(y_raw, t_data=None, fs=None, labels=None, units=None)

Bases: TimeSeriesGroup

Child-class of TimeSeriesGroup to store and handle emg data in.

Returns:

None

Return type:

None

filter(signal_type='raw', hp_cf=20.0, lp_cf=500.0, order=3, channel_idxs=None)

Filter raw EMG signals to remove baseline wander and high frequency components. See TimeSeries.filter_emg.

gating(signal_type='filt', gate_width_samples=None, ecg_peak_idxs=None, ecg_raw=None, bp_filter=True, fill_method=3, channel_idxs=None, overwrite=False)

Eliminate ECG artifacts from the provided signal. See TimeSeries.gating.

wavelet_denoising(signal_type='filt', ecg_peak_idxs=None, ecg_raw=None, bp_filter=True, n=None, fixed_threshold=None, channel_idxs=None, overwrite=False)

Eliminate ECG artifacts from the provided signal. See TimeSeries.wavelet_denoising.

class resurfemg.data_connector.data_classes.TimeSeries(y_raw, t_data=None, fs=None, label=None, units=None)

Bases: object

Data class to store, process, and plot single channel time series data

baseline(percentile=33, window_s=None, step_s=None, method='default', signal_type=None, augm_percentile=25, ma_window=None, perc_window=None)

Derive the moving baseline of the provided signal. See postprocessing.baseline submodule. ———————————————————————– :returns: None :rtype: None

calculate_time_products(peak_set_name, include_aub=True, aub_window_s=None, aub_reference_signal=None, parameter_name=None)

Calculate the time product, i.e. area under the curve for a PeaksSet. The results are stored as self.peaks[peak_set_name].peak_df[parameter_name]. If no parameter_name is provided, parameter_name = ‘time_product’ ———————————————————————– :param peak_set_name: PeaksSet name in self.peaks dict :type peak_set_name: str :param include_aub: Include the area under the baseline in the time product :type include_aub: bool :param signal_type: one of ‘env’, ‘clean’, ‘filt’, or ‘raw’ :param aub_window_s: window length in samples in which the local extreme is sought. :param aub_window_s: int :param aub_reference_signal: Optional reference signal to find the local extreme in, else the signal underlying the PeaksSet is taken. :type aub_reference_signal: ~numpy.ndarray :param parameter_name: parameter name in Dataframe self.peaks[peak_set_name].peak_df :type parameter_name: str

Returns:

None

Return type:

None

detect_emg_breaths(threshold=0, prominence_factor=0.5, min_peak_width_s=None, peak_set_name='breaths', start_idx=0, end_idx=None)

Find breath peaks in provided EMG envelope signal. See postprocessing.event_detection submodule. ———————————————————————– :returns: None :rtype: None

envelope(env_window=None, env_type=None, signal_type='clean')

Derive the moving envelope of the provided signal. See preprocessing.envelope submodule. ———————————————————————– :returns: None :rtype: None

filter_emg(signal_type='raw', hp_cf=20.0, lp_cf=500.0, order=3)

Filter raw EMG signal to remove baseline wander and high frequency components. See preprocessing.emg_bandpass_butter submodule. ———————————————————————– :returns: None :rtype: None

gating(signal_type='filt', gate_width_samples=None, ecg_peak_idxs=None, ecg_raw=None, bp_filter=True, fill_method=3, overwrite=False)

Eliminate ECG artifacts from the provided signal. See preprocessing.ecg_removal and pipelines.ecg_removal_gating submodules. ———————————————————————– :returns: None :rtype: None

get_ecg_peaks(ecg_raw=None, bp_filter=True, overwrite=False)

Detect ECG peaks in the provided signal. See preprocessing.ecg_removal submodule. ———————————————————————– :param ecg_raw: ECG signal, if None, the raw signal is used :type ecg_raw: ~numpy.ndarray :bp_filter: Apply band-pass filter to the ECG signal :type bp_filter: bool :overwrite: Overwrite existing peaks :type overwrite: bool

Returns:

None

Return type:

None

Find the peaks in the PeaksSet with the peak_set_name closest in time to the provided peak timings in t_reference_peaks ———————————————————————– :param peak_set_name: PeaksSet name in self.peaks dict :type peak_set_name: str :param t_reference_peaks: Refernce peak timings in t_reference_peaks :type t_reference_peaks: ~numpy.ndarray :param linked_peak_set_name: Name of the new PeaksSet :type linked_peak_set_name: str

Returns:

None

Return type:

None

plot_aub(peak_set_name, axes, signal_type, valid_only=False, colors=None)

Plot the area under the baseline (AUB) for the peak set in the provided axes in the provided colours using the provided markers. ———————————————————————– :param peak_set_name: PeaksSet name in self.peaks dict :type peak_set_name: str :param axes: matplotlib Axes object. If none provided, a new figure is created. :type axes: matplotlib.Axes :param signal_type: the signal (‘env’, ‘clean’, ‘filt’, ‘raw’) to plot :type signal_type: str :param valid_only: when True, only valid peaks are plotted. :type valid_only: bool :param colors: 1 color or list of up to 3 colors for the peak :type colors: str or list

Returns:

None

Return type:

None

plot_curve_fits(peak_set_name, axes, valid_only=False, colors=None)

Plot the curve-fits for the peak set in the provided axes in the provided colours using the provided markers. ———————————————————————– :param peak_set_name: PeaksSet name in self.peaks dict :type peak_set_name: str :param axes: matplotlib Axes object. If none provided, a new figure is created. :type axes: matplotlib.Axes :param valid_only: when True, only valid peaks are plotted. :type valid_only: bool :param colors: 1 color or list of colors for the fitted curve peak :type colors: str or list

Returns:

None

Return type:

None

plot_full(axis=None, signal_type=None, colors=None, baseline_bool=True)

Plot the indicated signals in the provided axes. By default the most advanced signal type (envelope > clean > filt > raw) is plotted in the provided colours. ———————————————————————– :param axis: matplotlib Axis object. If none provided, a new figure is created. :type axis: matplotlib.Axis :param signal_type: the signal (‘env’, ‘clean’, ‘filt’, ‘raw’) to plot :type signal_type: str :param colors: list of colors to plot the 1) signal, 2) the baseline :type colors: list :param baseline_bool: plot the baseline :type baseline_bool: bool

Returns:

None

Return type:

None

plot_markers(peak_set_name, axes, valid_only=False, colors=None, markers=None)

Plot the markers for the peak set in the provided axes in the provided colours using the provided markers. ———————————————————————– :param peak_set_name: PeaksSet name in self.peaks dict :type peak_set_name: str :param axes: matplotlib Axes object. If none provided, a new figure is created. :type axes: matplotlib.Axes :param valid_only: when True, only valid peaks are plotted. :type valid_only: bool :param colors: 1 color of list of up to 3 colors for the markers, peak, start, and end markers. If 2 colors are provided, start and end have the same colors :type colors: str or list :param markers: 1 markers or list of up to 3 markers for peak, start, and end markers. If 2 markers are provided, start and end have the same marker :type markers: str or list

Returns:

None

Return type:

None

plot_peaks(peak_set_name, axes=None, signal_type=None, margin_s=None, valid_only=False, colors=None, baseline_bool=True)

Plot the indicated peaks in the provided axes. By default the most advanced signal type (envelope > clean > filt > raw) is plotted in the provided colours. ———————————————————————– :param peak_set_name: The name of the peak_set to be plotted. :type peak_set_name: str :param axes: matplotlib Axes object. If none provided, a new figure is created. :type axes: matplotlib.Axes :param signal_type: the signal (‘env’, ‘clean’, ‘filt’ ‘raw’) to plot :type signal_type: str :param margin_s: margins in samples plotted before the peak onset and after the peak offset :param valid_only: when True, only valid peaks are plotted. :type valid_only: bool :param colors: list of colors to plot the 1) signal, 2) the baseline :type colors: list :param baseline_bool: plot the baseline :type baseline_bool: bool

Returns:

None

Return type:

None

set_peaks(peak_idxs, signal, peak_set_name)

Store a new PeaksSet object in the self.peaks dict

returns:

None

rtype:

None

signal_type_data(signal_type=None)

Automatically select the most advanced data type eligible for a subprocess (‘env’ {=envelope} > ‘clean’ > ‘raw’) ———————————————————————– :param signal_type: one of ‘env’, ‘clean’, or ‘raw’ :type signal_type: str

Returns y_data:

data of the selected signal type

Rtype y_data:

~numpy.ndarray

test_emg_quality(peak_set_name, cutoff=None, skip_tests=None, parameter_names=None, verbose=True)

Test EMG PeaksSet according to quality criteria in Warnaar et al. (2024), extended with relative area under the baseline and relative ETP evaluation. Peak validity is updated in the PeaksSet object. ———————————————————————– :param peak_set_name: PeaksSet name in self.peaks dict :type peak_set_name: str :param cutoff: Cut-off criteria for passing the tests, including ratio between ECG and EMG interpeak time (interpeak_distance), signal- to-noise ratio (snr), percentage area under the baseline (aub), percentage miss fit with bell curve (curve_fit), the aub relative to all detected aubs (relative_aub), and the electrical time product (ETP) relative to all ETPs (relative_ETP). ‘tolerant’ and ‘strict’ can also be provided instead of a dict to use the respective values from Warnaar et al. :type cutoff: dict :param skip_tests: List of tests to skip. :type skip_tests: list :param parameter_names: Optionally refer to custom parameter names for default PeaksSet (ecg) :type parameter_names: dict :param verbose: Output the test values, and pass/fail to console. :type verbose: bool

Returns:

None

Return type:

None

test_linked_peak_sets(peak_set_name, linked_timeseries, linked_peak_set_name, parameter_names=None, cutoff=None, skip_tests=None, verbose=True)

Test number of detected breaths in the native PeaksSet compared to number of and timing peaks in the linked PeaksSet. Peak validity is updated in the PeaksSet object. ———————————————————————– :param peak_set_name: PeaksSet name in self.peaks dict :type peak_set_name: str :param linked_timeseries: TimeSeries object with linked signal :type linked_timeseries: TimeSeries :param linked_peak_set_name: PeaksSet name in linked_timeseries.peaks :type linked_peak_set_name: str :param parameter_names: Optionally refer to custom parameter names for default PeaksSet and parameter names (‘rr’, ) :type parameter_names: dict :param cutoff: Cut-off criteria for passing the tests, including fraction of detected breaths (fraction_emg_breaths), and event timing (event_timing). ‘tolerant’ and ‘strict’ can also be provided instead of a dict to use the pre-defined values. :type cutoff: dict :param skip_tests: List of tests to skip. :type skip_tests: list :param verbose: Output the test values, and pass/fail to console. :type verbose: bool

Returns:

None

Return type:

None

test_pocc_quality(peak_set_name, cutoff=None, skip_tests=None, parameter_names=None, verbose=True)

Test EMG PeaksSet according to quality criteria in Warnaar et al. (2024). Peak validity is updated in the PeaksSet object. ———————————————————————– :param peak_set_name: PeaksSet name in self.peaks dict :type peak_set_name: str :param cutoff: Cut-off criteria for passing the tests, including consecutiveness of Pocc manoeuvre (consecutive_poccs), and p_vent upslope (dP_up_10, dP_up_90, and dP_up_90_norm). ‘tolerant’ and ‘strict’ can also be provided instead of a dict to use the respective values from Warnaar et al. :type cutoff: dict :param skip_tests: List of tests to skip. :type skip_tests: list :param parameter_names: Optionally refer to custom parameter names for default PeaksSet and parameter names (ventilator_breaths, time_product, AUB, ) :type parameter_names: dict :param verbose: Output the test values, and pass/fail to console. :type verbose: bool

Returns:

None

Return type:

None

wavelet_denoising(signal_type='filt', ecg_peak_idxs=None, ecg_raw=None, n=None, fixed_threshold=None, bp_filter=True, overwrite=False)

Eliminate ECG artifacts from the provided signal. See preprocessing.wavelet_denoising submodules. ———————————————————————– :returns: None :rtype: None

class resurfemg.data_connector.data_classes.TimeSeriesGroup(y_raw, t_data=None, fs=None, labels=None, units=None)

Bases: object

Data class to store, process, and plot time series data

baseline(percentile=33, window_s=None, step_s=None, method='default', signal_type=None, augm_percentile=25, ma_window=None, perc_window=None, channel_idxs=None)

Derive the moving baseline of the provided signal. See TimeSeries.baseline. ———————————————————————– :returns: None :rtype: None

envelope(env_window=None, env_type=None, signal_type='clean', channel_idxs=None)

Derive the moving envelope of the provided signal. See TimeSeries.envelope. ———————————————————————– :returns: None :rtype: None

plot_full(axes=None, channel_idxs=None, signal_type=None, colors=None, baseline_bool=True)

Plot the indicated signals in the provided axes. By default the most advanced signal type (envelope > clean > filt > raw) is plotted in the provided colours. See TimeSeries.plot_full. ———————————————————————– :param axes: matplotlib Axes object. If none provided, a new figure is created. :type axes: ~numpy.ndarray :param channel_idxs: list of which channels indices to plot. If none provided, all channels are plot. :type channel_idxs: list :param signal_type: the signal (‘env’, ‘clean’, ‘filt’, ‘raw’) to plot :type signal_type: str :param colors: list of colors to plot the 1) signal, 2) the baseline :type colors: list :param baseline_bool: plot the baseline :type baseline_bool: bool

Returns:

None

Return type:

None

plot_markers(peak_set_name, axes=None, channel_idxs=None, valid_only=False, colors=None, markers=None)

Plot the indicated peak markers for all provided channels in the provided axes using the provided colours and markers. See TimeSeries.plot_markers ———————————————————————– :param peak_set_name: PeaksSet name in self.peaks dict :type peak_set_name: str :param axes: matplotlib Axes object. If none provided, a new figure is created. :type axes: matplotlib.Axes :param channel_idxs: list of which channels indices to plot. If none provided, all channels are plot. :type channel_idxs: list :param valid_only: when True, only valid peaks are plotted. :type valid_only: bool :param colors: 1 color of list of up to 3 colors for the markers, peak, start, and end markers. If 2 colors are provided, start and end have the same colors :type colors: str or list :param markers: 1 markers or list of up to 3 markers for peak, start, and end markers. If 2 markers are provided, start and end have the same marker :type markers: str or list

Returns:

None

Return type:

None

plot_peaks(peak_set_name, axes=None, channel_idxs=None, signal_type=None, margin_s=None, valid_only=False, colors=None, baseline_bool=True)

Plot the indicated peaks for all provided channels in the provided axes. By default the most advanced signal type (env > clean > filt > raw) is plotted in the provided colours. See TimeSeries.plot_peaks ———————————————————————– :param peak_set_name: The name of the peak_set to be plotted. :type peak_set_name: str :param axes: matplotlib Axes object. If none provided, a new figure is created. :type axes: matplotlib.Axes :param channel_idxs: list of which channels indices to plot. If none provided, all channels are plot. :type channel_idxs: list :param signal_type: the signal (‘env’, ‘clean’, ‘filt’, ‘raw’) to plot :type signal_type: str :param margin_s: margins in samples plotted before the peak onset and after the peak offset :type margin_s: int :param valid_only: when True, only valid peaks are plotted. :type valid_only: bool :param colors: list of colors to plot the 1) signal, 2) the baseline :type colors: list :param baseline_bool: plot the baseline :type baseline_bool: bool

Returns:

None

Return type:

None

class resurfemg.data_connector.data_classes.VentilatorDataGroup(y_raw, t_data=None, fs=None, labels=None, units=None)

Bases: TimeSeriesGroup

Child-class of TimeSeriesGroup to store and handle ventilator data in.

find_occluded_breaths(pressure_idx, peep=None, start_idx=0, end_idx=None, prominence_factor=0.8, min_width_s=None, distance_s=None)

Find end-expiratory occlusion manoeuvres in ventilator pressure timeseries data. See postprocessing.event_detection submodule. ———————————————————————– :param pressure_idx: Channel index of the ventilator pressure data :type pressure_idx: int For other arguments, see postprocessing.event_detection submodule.

Returns:

None

Return type:

None

find_peep(pressure_idx, volume_idx)

Calculate PEEP as the median value of p_vent at end-expiration.

param pressure_idx:

Channel index of the ventilator pressure data

type pressure_idx:

int

param volume_idx:

Channel index of the ventilator volume data

type volume_idx:

int

returns:

None

rtype:

None

find_tidal_volume_peaks(volume_idx=None, start_idx=0, end_idx=None, width_s=None, threshold=None, prominence=None, threshold_new=None, prominence_new=None, pressure_idx=None)

Find tidal-volume peaks in ventilator volume signal. Peaks are stored in PeaksSet named ‘ventilator_breaths’ in ventilator pressure and volume TimeSeries. ———————————————————————– :param volume_idx: Channel index of the ventilator volume data :type volume_idx: int For other arguments, see postprocessing.event_detection submodule.

Returns:

None

Return type:

None