Breath Detection

eitprocessing.features.breath_detection.BreathDetection dataclass

BreathDetection(
    *,
    minimum_duration: float = 2 / 3,
    averaging_window_duration: float = 15,
    averaging_window_function: Callable[[int], ArrayLike] | None = blackman,
    amplitude_cutoff_fraction: float | None = 0.25,
    invalid_data_removal_window_length: float = 0.5,
    invalid_data_removal_percentile: int = 5,
    invalid_data_removal_multiplier: int = 4
)

Algorithm for detecting breaths in data representing respiration.

This algorithm detects the position of breaths in data by detecting valleys (local minimum values) and peaks (local maximum values) in data. BreathDetection has a default minimum duration of breaths to be detected. The minimum duration should be short enough to include the shortest expected breath in the data. The minimum duration is implemented as the minimum time between peaks and between valleys.

Examples:

>>> bd = BreathDetection(minimum_duration=0.5)
>>> breaths = bd.find_breaths(
...     sequency=seq,
...     continuousdata_label="global_impedance_(raw)"
... )

>>> global_impedance = seq.continuous_data["global_impedance_(raw)"]
>>> breaths = bd.find_breaths(continuous_data=global_impedance)

PARAMETER	DESCRIPTION
minimum_duration	minimum expected duration of breaths, defaults to 2/3 of a second TYPE: float DEFAULT: 2 / 3
averaging_window_duration	duration of window used for averaging the data, defaults to 15 seconds TYPE: float DEFAULT: 15
averaging_window_function	function used to create a window for averaging the data, defaults to np.blackman TYPE: Callable[[int], ArrayLike] | None DEFAULT: blackman
amplitude_cutoff_fraction	fraction of the median amplitude below which breaths are removed, defaults to 0.25 TYPE: float | None DEFAULT: 0.25
invalid_data_removal_window_length	window around invalid data in which breaths are removed, defaults to 0.5 TYPE: float DEFAULT: 0.5
invalid_data_removal_percentile	the nth percentile of values used to remove outliers, defaults to 5 TYPE: int DEFAULT: 5
invalid_data_removal_multiplier	the multiplier used to remove outliers, defaults to 4 TYPE: int DEFAULT: 4

find_breaths

find_breaths(
    continuous_data: ContinuousData,
    result_label: str = "breaths",
    sequence: Sequence | None = None,
    store: bool | None = None,
) -> IntervalData

Find breaths based on peaks and valleys, removing edge cases and breaths during invalid data.

First, it naively finds any peaks that are a certain distance apart and higher than the moving average, and similarly valleys that are a certain distance apart and below the moving average.

Next, valleys at the start and end of the signal are removed to ensure the first and last valleys are actual valleys, and not just the start or end of the signal. Peaks before the first or after the last valley are removed, to ensure peaks always fall between two valleys.

At this point, it is possible multiple peaks exist between two valleys. Lower peaks are removed leaving only the highest peak between two valleys. Similarly, multiple valleys between two peaks are reduced to only the lowest valley.

As a last step, breaths with a low amplitude (the average between the inspiratory and expiratory amplitudes) are removed.

Breaths are constructed as a valley-peak-valley combination, representing the start of inspiration, the end of inspiration/start of expiration, and end of expiration.

PARAMETER	DESCRIPTION
continuous_data	optional, a ContinuousData object that contains the data TYPE: ContinuousData
result_label	label of the returned IntervalData object, defaults to 'breaths'. TYPE: str DEFAULT: 'breaths'
sequence	optional, Sequence that contains the object to detect breaths in, and/or to store the result in TYPE: Sequence | None DEFAULT: None
store	whether to store the result in the sequence, defaults to True if a Sequence if provided. TYPE: bool | None DEFAULT: None

RETURNS	DESCRIPTION
IntervalData	An IntervalData object containing Breath objects.