vitabel.analysis.ventilation.volumes
====================================

.. py:module:: vitabel.analysis.ventilation.volumes

.. autoapi-nested-parse::

   Utilities for deriving ventilation-volume metrics from phase labels.

   ..
       !! processed by numpydoc !!


Functions
---------

.. autoapisummary::

   vitabel.analysis.ventilation.volumes.integrate_trapezoid
   vitabel.analysis.ventilation.volumes.concat_and_sort_dataslices
   vitabel.analysis.ventilation.volumes.argmax_dataslices
   vitabel.analysis.ventilation.volumes.compute_breath_duration_and_rate_labels
   vitabel.analysis.ventilation.volumes.compute_inspiratory_pressure_labels
   vitabel.analysis.ventilation.volumes.compute_volume_channels_and_labels
   vitabel.analysis.ventilation.volumes.compute_cumulative_volume_channels
   vitabel.analysis.ventilation.volumes.compute_reverse_airflow_labels


Module Contents
---------------

.. py:function:: 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.











   ..
       !! processed by numpydoc !!

.. py:function:: 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.











   ..
       !! processed by numpydoc !!

.. py:function:: 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.











   ..
       !! processed by numpydoc !!

.. py:function:: 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.











   ..
       !! processed by numpydoc !!

.. py:function:: 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.











   ..
       !! processed by numpydoc !!

.. py:function:: 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)``.











   ..
       !! processed by numpydoc !!

.. py:function:: 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)``.











   ..
       !! processed by numpydoc !!

.. py:function:: 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)``.











   ..
       !! processed by numpydoc !!