Pixel Breath

eitprocessing.features.pixel_breath.PixelBreath dataclass

PixelBreath(
    *,
    breath_detection: BreathDetection = _return_sentinel_breath_detection(),
    breath_detection_kwargs: InitVar[dict | None] = None,
    phase_correction_mode: (
        Literal["negative amplitude", "phase shift", "none"] | None
    ) = "negative amplitude"
)

Algorithm for detecting timing of pixel breaths in pixel impedance data.

This algorithm detects the position of start of inspiration, end of inspiration and end of expiration in pixel impedance data. It uses BreathDetection to find the global start and end of inspiration and expiration. These points are then used to find the start/end of pixel inspiration/expiration in pixel impedance data.

Since this algorithm uses the previous and next global breath to determine the start and end of a pixel breath, the first and last global breaths can not be used to determine pixel breaths. They are always set to None in the return list. Breaths that could not properly be detected are set to None as well.

Some pixel breaths may be phase shifted (inflation starts and ends later compared to others, e.g., due to pendelluft or late airway opening). Other pixel breaths may have a negative amplitude (impedance decreases during inspiration, e.g., due to pleural effusion or reconstruction artifacts). It is not always possible to determine whether a pixel is out of phase or has a negative amplitude. PixelBreath has three different phase correction modes. In 'negative amplitude' mode (default), pixels that have a decrease in amplitude between the start and end of globally defined inspiration, will have a negative amplitude and smaller phase shift. In 'phase shift' mode, all pixel breaths will have positive amplitudes, but can have large phase shifts. In 'none'/None mode, all pixels are assumed to be within rouglhy -90 to 90 degrees of phase. Note that the 'none' mode can lead to unexpected results, such as ultra-short (down to 2 frames) or very long breaths.

Example:

>>> pi = PixelBreath()
>>> eit_data = sequence.eit_data['raw']
>>> continuous_data = sequence.continuous_data['global_impedance_(raw)']
>>> pixel_breaths = pi.find_pixel_breaths(eit_data, continuous_data, sequence)

PARAMETER	DESCRIPTION
breath_detection	BreathDetection object to use for detecting breaths. TYPE: BreathDetection DEFAULT: _return_sentinel_breath_detection()
phase_correction_mode	How to resolve pixels that are out-of-phase. Defaults to "negative amplitude". TYPE: Literal['negative amplitude', 'phase shift', 'none'] | None DEFAULT: 'negative amplitude'

find_pixel_breaths

find_pixel_breaths(
    eit_data: EITData,
    continuous_data: ContinuousData,
    sequence: Sequence | None = None,
    store: bool | None = None,
    result_label: str = "pixel_breaths",
) -> IntervalData

Find pixel breaths in the data.

This method finds the pixel start/end of inspiration/expiration based on the start/end of inspiration/expiration as detected in the continuous data.

For most pixels, the start of a breath (start inspiration) is the valley between the middles (start of expiration) of the globally defined breaths on either side. The end of a pixel breath is the start of the next pixel breath. The middle of the pixel breath is the peak between the start and end of the pixel breath.

If the pixel is out of phase or has negative amplitude, the definition of the breath depends on the phase correction mode. In 'negative amplitude' mode, the start of a breath is the peak between the middles of the globally defined breaths on either side, while the middle of the pixel breath is the valley of the start and end of the pixel breath. In 'phase shift' mode, first the phase shift between the pixel impedance and global impedance is determined as the highest crosscorrelation between the signals near a phase shift of 0. The start of breath is the valley between the phase shifted middles of the globally defined breaths on either side.

Pixel 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
eit_data	EITData to apply the algorithm to. TYPE: EITData
continuous_data	ContinuousData to use for global breath detection. TYPE: ContinuousData
result_label	label of the returned IntervalData object, defaults to 'pixel_breaths'. TYPE: str DEFAULT: 'pixel_breaths'
sequence	optional, Sequence that contains the object to detect pixel breaths in, and/or to store the result 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.

RAISES	DESCRIPTION
RuntimeError	If store is set to true but no sequence is provided.
ValueError	If the provided sequence is not an instance of the Sequence dataclass.