vitabel.analysis.ventilation.volumes¶

Utilities for deriving ventilation-volume metrics from phase labels.

Functions¶

`integrate_trapezoid`(→ vitabel.typing.DataSlice)	Integrate a sampled signal cumulatively with the trapezoidal rule.
`concat_and_sort_dataslices`(→ vitabel.typing.DataSlice)	Concatenate multiple data slices and sort the result by time.
`argmax_dataslices`(→ vitabel.typing.DataSlice)	Extract the maximum value and its timestamp from each data slice.
`compute_breath_duration_and_rate_labels`(...)	Create breath-duration and respiratory-rate labels from phase intervals.
`compute_inspiratory_pressure_labels`(...)	Create per-breath inspiratory pressure summary labels.
`compute_volume_channels_and_labels`(...)	Compute primary ventilation-volume channels and tidal-volume labels.
`compute_cumulative_volume_channels`(...)	Compute cumulative inspiratory and expiratory volume channels.
`compute_reverse_airflow_labels`(...)	Compute labels describing reverse airflow within respiratory phases.

Module Contents¶

vitabel.analysis.ventilation.volumes.integrate_trapezoid(signal: vitabel.typing.DataSlice, correction_factor: float = 1.0) → vitabel.typing.DataSlice¶

Integrate a sampled signal cumulatively with the trapezoidal rule.

Parameters:

signal: Input samples to integrate. The time index is expected to be ordered and to have the same length as the data array.
correction_factor: Multiplicative factor applied to the data before integration. This is typically used for unit conversion or device-specific flow correction.

Returns:

DataSlice: Cumulative integral with the same time index as the input.

vitabel.analysis.ventilation.volumes.concat_and_sort_dataslices(dataslices: list[vitabel.typing.DataSlice]) → vitabel.typing.DataSlice¶

Concatenate multiple data slices and sort the result by time.

Parameters:

dataslices: Data slices to combine. All slices are expected to contain numeric data.

Returns:

DataSlice: A single chronologically ordered data slice containing all samples.

vitabel.analysis.ventilation.volumes.argmax_dataslices(dataslices: list[vitabel.typing.DataSlice]) → vitabel.typing.DataSlice¶

Extract the maximum value and its timestamp from each data slice.

Empty slices and slices containing only NaN values are ignored.

Parameters:

dataslices: Data slices for which peak values should be determined.

Returns:

DataSlice: One timestamp/value pair per valid input slice.

vitabel.analysis.ventilation.volumes.compute_breath_duration_and_rate_labels(inspiration: vitabel.timeseries.IntervalLabel, expiration: vitabel.timeseries.IntervalLabel) → tuple[vitabel.timeseries.Label, vitabel.timeseries.Label, vitabel.timeseries.Label]¶

Create breath-duration and respiratory-rate labels from phase intervals.

Parameters:

inspiration: Inspiration intervals.
expiration: Expiration intervals.

Returns:

tuple[Label, Label, Label]: Labels for inspiratory time, expiratory time, and respiratory rate.

vitabel.analysis.ventilation.volumes.compute_inspiratory_pressure_labels(pressure: vitabel.timeseries.Channel, insp_t: numpy.ndarray) → tuple[vitabel.timeseries.Label, vitabel.timeseries.Label]¶

Create per-breath inspiratory pressure summary labels.

Parameters:

pressure: Pressure channel sampled on the common respiratory-phase time base.
insp_t: Array of inspiration intervals as (start, stop) pairs.

Returns:

tuple[Label, Label]: Labels for maximal and minimal inspiratory airway pressure.

vitabel.analysis.ventilation.volumes.compute_volume_channels_and_labels(flow: vitabel.timeseries.Channel, inspiration: vitabel.timeseries.IntervalLabel, expiration: vitabel.timeseries.IntervalLabel, correction_factor: float) → tuple[vitabel.timeseries.Channel, vitabel.timeseries.Channel, vitabel.timeseries.Channel, vitabel.timeseries.Label, vitabel.timeseries.Label, vitabel.timeseries.Label]¶

Compute primary ventilation-volume channels and tidal-volume labels.

This function derives the net cycle integral (Volume), a phase-specific inspiratory volume curve, a phase-specific expiratory volume curve, and the associated tidal-volume summary labels.

Parameters:

flow: Interpolated flow channel.
inspiration: Inspiration intervals.
expiration: Expiration intervals.
correction_factor: Multiplicative factor applied before integrating flow.

Returns:

tuple[Channel, Channel, Channel, Label, Label, Label]: (volume, inspiratory_volume, expiratory_volume, delta_vt, vt_insp, vt_exp).

vitabel.analysis.ventilation.volumes.compute_cumulative_volume_channels(flow: vitabel.timeseries.Channel, inspiration: vitabel.timeseries.IntervalLabel, correction_factor: float) → tuple[vitabel.timeseries.Channel, vitabel.timeseries.Channel, vitabel.timeseries.Label, vitabel.timeseries.Label]¶

Compute cumulative inspiratory and expiratory volume channels.

Positive and negative flow are integrated separately on a cycle basis to obtain cumulative inspiratory and expiratory volume curves.

Parameters:

flow: Interpolated flow channel.
inspiration: Inspiration intervals used to define complete breathing cycles.
correction_factor: Multiplicative factor applied before integrating flow.

Returns:

tuple[Channel, Channel, Label, Label]: (cumulative_inspiratory_volume, cumulative_expiratory_volume, vt_insp_cum, vt_exp_cum).

vitabel.analysis.ventilation.volumes.compute_reverse_airflow_labels(flow: vitabel.timeseries.Channel, inspiration: vitabel.timeseries.IntervalLabel, expiration: vitabel.timeseries.IntervalLabel, correction_factor: float) → tuple[vitabel.timeseries.Label, vitabel.timeseries.IntervalLabel, vitabel.timeseries.Label, vitabel.timeseries.Label, vitabel.timeseries.IntervalLabel, vitabel.timeseries.Label]¶

Compute labels describing reverse airflow within respiratory phases.

Reverse airflow is quantified on zero-crossing-delimited flow segments and then summarized per inspiration and per expiration.

Parameters:

flow: Interpolated flow channel.
inspiration: Inspiration intervals.
expiration: Expiration intervals.
correction_factor: Multiplicative factor applied before integrating segment flow.

Returns:

tuple[Label, IntervalLabel, Label, Label, IntervalLabel, Label]: (insp_reverse_volume, insp_reverse_airflow, insp_reverse_sum, exp_reverse_volume, exp_reverse_airflow, exp_reverse_sum).