vitabel.vitals¶

Core module, contains the central data container class Vitals.

Attributes¶

logger

Global package logger.

Classes¶

Vitals

Container for vital data and labels, central interface of this package.

Module Contents¶

vitabel.vitals.logger: logging.Logger¶: Global package logger.

class vitabel.vitals.Vitals¶

Container for vital data and labels, central interface of this package.

The Vitals class supports adding data using various methods, such as loading data from files directly via add_defibrillator_recording(), or add_vital_db_recording(). It also supports adding data channels and labels directly from a pandas DataFrame via add_data_from_DataFrame().

Internally, the data is stored using the TimeDataCollection class, which stores data channels and labels as Channel and Label objects, respectively. These can also be added directly to the Vitals object using add_channel() and add_global_label().

Examples

>>> import pandas as pd
>>> from vitabel import Vitals, Channel
>>> case = Vitals()
>>> event_channel = Channel(
...     "events",
...     pd.date_range("2021-01-01", periods=10, freq="H"),
...     [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
... )
>>> case.add_channel(event_channel)

data: vitabel.timeseries.TimeDataCollection¶: The internal data collection containing all channels and labels.

metadata: dict¶: Metadata dictionary containing information about the data collection.

start_time = 0¶: The start time of the recording.

property channels: list[vitabel.timeseries.Channel]¶: List of all channels in the data collection.

property labels: list[vitabel.timeseries.Label]¶: List of all labels in the data collection.

print_data_summary() → None¶: Print a summary of the data contained in the internal data collection.

add_defibrillator_recording(filepath: pathlib.Path | str, metadata={}) → None¶

Add the (defibrillator) recording to the cardio object.

Imports from the following defibrillator device families are supported:

ZOLL X-Series: data needs to be exported from device as JSON or XML.
ZOLL E-Series and ZOLL AED-Pro: Data needs to be exported from the device in two files, filename_ecg.txt and filename.xml, where filename can be arbitrary. Both files are assumed to be in the same directory. Pass the path to filename_ecg.txt to import the data.
Stryker LIFEPAK 15: Data needs to be exported to XML in Stryker’s CodeStat Software. To load the data, we require at least the files filename_Continuous.xml, filename_Continuous_Waveform.xml, and filename_CprEventLog.xml, where filename is an arbitrary prefix. All files are assumed to be in the same directory. Pass the path to filename_Continuous.xml to import the data.
Stryker LUCAS: Data needs to be exported to XML in Stryker’s CodeStat Software. We require at leas the files filename_Lucas.xml and filename_CprEventLog.xml, where filename is an arbitrary prefix. Both files are assumed to be in the same directory. Pass the path to filename_Lucas.xml to import the data.
Corpuls: The data needs to be exported as a BDF file in Corpuls analysis software. The export will create a filename.bdf file, containing the waveform data, as well as a directory with various other files containing event logs. We assume this directory is placed in the same directory as the .bdf file. Pass the path to filename.bdf to import the data.

The actual loading routines are implemented in the utils.loading module.

Parameters:

filepath: The path to a file exported from the defibrillator. Check the description above to see, depending on the device type, which file path should be passed.
metadata: Metadata to be added to the imported data.

add_ventilatory_feedback(filepath: pathlib.Path | str, metadata: dict[str, Any] | None = None) → None¶

Add ventilatory feedback from a given data source.

Currently only EOlife export files (exported CSV files) are supported.

Parameters:

filepath: The path to the data source file.
metadata: Metadata to be added to the imported data. If not provided, an empty dictionary is used.

add_vital_db_recording(filepath: pathlib.Path | str, metadata: dict[str, Any] | None = None) → None¶

Loading channels and labels from a vitalDB recording.

Parameters:

filepath: The path to the recording. Must be a *.vit file.

add_edfplus(file_path: pathlib.Path | str, channel_names: list[str] | None = None, label_names: list[str] | None = None, metadata: dict[str, Any] | None = None) → None¶

Load channels and labels from an EDF+ file.

Reads biosignal channels and annotation labels from an EDF+ file using utils.loading.read_edfplus() and adds them to the internal data collection.

Parameters:

file_path: Path to the EDF+ file.
channel_names: List of channel names to import. If None, all channels are imported.
label_names: List of label names to import. If None, all labels are imported.
metadata: Additional metadata to merge into the recording metadata. If None, no extra metadata is added.

add_old_cardio_label(filepath: pathlib.Path | str) → None¶

Add labels from legacy version of this package.

Can read both consensual as well as singular annotations.

Parameters:

filepath: Path to legacy-style label file.

add_data_from_dict(source: dict[str, dict] | pathlib.Path, time_start=None, datatype: Literal['channel', 'label', 'interval_label'] = 'channel', anchored_channel: vitabel.timeseries.Channel | None = None, metadata: dict | None = None)¶

Add multiple channels from a dictionary.

Each value must be a dictionary accepted by _add_single_dict().

Parameters:

source: The data which is added in the from {'key1': {'timestamp': [], 'data': []}, 'key2': { ... }, ... }. If source is a Path, then it is assumed to be a JSON file and loaded via json.load.
time_start: time_start value for the timeseries, in case of a relative timeseries. The default is None.
datatype: Either 'channel' or 'label' or 'interval_label', depending on which kind of container to construct. The default is 'channel'.
anchored_channel: If a label is constructed, then this is the channel to which the label is anchored. Irrelevant if datatype is 'channel'.
metadata: Metadata that will be attached to all individual timeseries.

Raises:

ValueError: In case the dictionary does not have the expected form.

add_data_from_DataFrame(source: pandas.DataFrame, time_start: str | None = None, time_unit=None, datatype: Literal['channel', 'label', 'interval_label'] = 'channel', anchored_channel: vitabel.timeseries.Channel | None = None, metadata: dict[str, Any] | None = None, column_metadata: dict[str, dict[str, Any]] | None = None)¶

Adds Data from a pandas.DataFrame.

Parameters:

source: The DataFrame containing the data. The index of the DataFrame contains the time (either as DatetimeIndex, TimedeltaIndex or numeric Index), and the columns contain the channels. NaN-Values in the columns are not taken into account an ignored.
time_start: A starting time for the data. Must be accepted by pd.Timestamp(time_start) In case the index is timedelta or numeric. The times will be interpreted as relative to this value. The default is 0 and means no information is given.
time_unit: The time unit of the data. Must be accepted by pd.Timestamp(time_unit).
datatype: Either 'channel' or 'label' or 'interval_label', depending on which kind of container to construct. The default is 'channel'.
anchored_channel: If a label is constructed, then this is the channel to which the label is anchored. Irrelevant if datatype is 'channel'.
metadata: A dictionary containing all the metadata for the channels / labels.
column_metadata: A dictionary containing metadata for individual columns in the dataframe. The keys are the column names, the values are dictionaries. When storing the data, the metadata from this dictionary is merged with the global metadata (and overriding it in case of conflicts).

Raises:

ValueError: The DataFrame does not contain a DateTime or Numeric Index.

add_data_from_csv(file_path: pathlib.Path | str, time_start=None, time_unit=None, datatype: Literal['channel', 'label', 'interval_label'] = 'channel', anchored_channel: vitabel.timeseries.Channel | None = None, metadata: dict[str, Any] | None = None, **kwargs)¶

Adds data from a CSV file.

The CSV file must contain a header with the channel names and a timestamp column. The data is loaded into a pandas DataFrame and passed to the add_data_from_DataFrame() method.

Parameters:

file_path: The path to the CSV file. The file must contain a header with the channel names and a timestamp column.
time_start: A starting time for the data. Must be accepted by pd.Timestamp(time_start) In case the index is numeric. The times will be interpreted as relative to this value. The default is 0 and means no information is given.
time_unit: The time unit of the data. Must be accepted by pd.Timestamp(time_unit).
datatype: Either 'channel' or 'label' or 'interval_label', depending on which kind of container to construct. The default is 'channel'.
anchored_channel: If a label is constructed, then this is the channel to which the label is anchored. Irrelevant if datatype is 'channel'.
metadata: A dictionary containing all the metadata for the channels/labels. Is parsed to channel/Label and saved there as general argument.
kwargs: Additional keyword arguments are passed to the pandas.read_csv function.

add_channel(channel: vitabel.timeseries.Channel)¶

add_global_label(label: vitabel.timeseries.Label)¶

remove_channel(*, channel: vitabel.timeseries.Channel | None = None, **kwargs) → vitabel.timeseries.Channel¶

Remove a channel from the data collection.

Parameters:

channel: The channel object to remove. If not provided, the channel is fetched from the collection using the other provided keyword arguments.
kwargs: Keyword arguments to filter the channels by. Passed to TimeDataCollection.get_channel(), resulting channel needs to be uniquely identified.

Returns:

Channel: The removed channel object.

remove_label(*, label: vitabel.timeseries.Label | None = None, **kwargs) → vitabel.timeseries.Label¶

Remove a label from the data collection.

Parameters:

label: The label object to remove. If not provided, the label is fetched from the collection using the other provided keyword arguments.
kwargs: Keyword arguments to filter the channels by. Passed to TimeDataCollection.get_label(), resulting label needs to be uniquely identified.

Returns:

Label: The removed label object.

set_channel_plotstyle(channel_specification: vitabel.typing.ChannelSpecification | None = None, **kwargs)¶

Set the plot style for a channel.

Parameters:

channel_specification: A specification of all channels to set the plot style for. See get_channels() for valid specifications.
kwargs: The plot style properties to set. Passing None unsets the key from the plotstyle dictionary.

set_label_plotstyle(label_specification: vitabel.typing.LabelSpecification | None = None, **kwargs)¶

Set the plot style for specified labels.

Parameters:

label_specification: A specification of all labels to set the plot style for. See get_labels() for valid specifications.
kwargs: The plot style properties to set. Passing None unsets the key from the plotstyle dictionary.

save_data(path: pathlib.Path | str)¶

Exports channels, labels, and metadata and saves it in a JSON file. In particular, adds a data hash and the vitabel version to the metadata.

Parameters:

path: The path of the output JSON file.

load_data(path: pathlib.Path | str, check_channel_hash=True)¶

Loads all Channels and Labels from a previously saved JSON file.

Parameters:

path: The Path of the channel data.

get_channels(name: str | None = None, **kwargs) → list[vitabel.timeseries.Channel]¶

Returns a list of channels based on their name.

This method retrieves all channels that match the given name and keyword arguments. If no name is specified, all channels are returned.

Parameters:

name: The name of the channels to retrieve.
kwargs: Keyword arguments to filter the channels by.

Returns:

list[Channel]: A list of channels that match the specification. If no channel matches the specification, an empty list is returned.

get_channel(name: str | int | None = None, **kwargs) → vitabel.timeseries.Channel¶

Returns a single channel based on its name.

Parameters:

name: The name of the channel to retrieve. If an integer is passed, it is interpreted as the index of the channel in the list of all channels.
kwargs: Keyword arguments to filter the channels by.

Returns:

Channel: The channel that matches the specification.

Raises:

ValueError: If the specification is ambiguous, i.e., if more than one or no channel matches the specification.

get_labels(name: str | None = None, label_type: type[vitabel.timeseries.Label] | None = None, **kwargs) → list[vitabel.timeseries.Label]¶

Returns a list of labels based on their name.

Parameters:

name: The name of the labels to retrieve.
label_typeTYPE, optional: A specification of the label type (IntervalLabel or Label) to retrieve
kwargs: Keyword arguments to filter the labels by.

Returns:

list[Label]: A list of labels that match the specification. If no label matches the specification, an empty list is returned.

get_label(name: str | int | None = None, **kwargs) → vitabel.timeseries.Label¶

Return a list of labels.

Parameters:

name: The name of the label to retrieve. Allowed to be passed either as a positional or a keyword argument. If name is an integer, it is interpreted as the index of the label in the list of all labels.
kwargs: Keyword arguments to filter the labels by. The specified arguments are compared to the attributes of the labels.

get_channels_or_labels(name: str | None = None, label_type: type[vitabel.timeseries.Label] | None = None, **kwargs) → list[vitabel.timeseries.Channel | vitabel.timeseries.Label]¶

Returns a list of channels or labels based on their name.

This method combines the results of get_channels() and get_labels() to return both channels and labels that match the given parameters. If a label_type is specified, it filters the labels accordingly.

Parameters:

name: The name of the channels or labels to retrieve. See get_channels() and get_labels() for valid specifications.
label_type: The class of the labels (e.g., IntervalLabel) to retrieve.
kwargs: Keyword arguments to filter the channels or labels by. See get_channels() and get_labels() for valid specifications.

Returns:

list[Channel | Label]: A list of channels or labels that match the specification. If no channel or label matches the specification, an empty list is returned.

get_channel_or_label(name: str | None = None, label_type: type[vitabel.timeseries.Label] | None = None, **kwargs) → vitabel.timeseries.Channel | vitabel.timeseries.Label¶

Returns a single channel or label based on its name.

Parameters:

name: The name of the channel or label to retrieve. See get_channel() and get_label() for valid specifications.
label_type: The class of the label (e.g., IntervalLabel) to retrieve.
kwargs: Keyword arguments to filter the channels or labels by. See get_channel() and get_label() for valid specifications.

Returns:

Channel | Label: The channel or label that matches the specification.

Raises:

ValueError: If the specification is ambiguous, i.e., if more than one channel or label matches the specification.

get_channel_names(**kwargs) → list[str]¶

Return a list with the names of all channels in the recording.

Parameters:

kwargs: Keyword arguments to filter the channels by.

Returns:

list[str]: A list with the names of all channels in the recording. If no channel matches the specification, an empty list is returned.

get_label_names(**kwargs) → list[str]¶

Returns a list with the names of all labels.

Parameters:

kwargs: Keyword arguments to filter the labels by. See get_label() for valid specifications.

Returns:

list[str]: A list with the names of all labels in the recording. If no label matches the specification, an empty list is returned.

get_channel_or_label_names(**kwargs) → list[str]¶

Returns a list with all names from either channels or labels.

Parameters:

kwargs: Keyword arguments to filter the channels and labels by. See get_channel() and get_label() for valid specifications.

Returns:

list[str]: A list with the names of all channels and labels in the recording. If no channel or label matches the specification, an empty list is returned.

keys(**kwargs) → list[str]¶: Alias for get_channel_or_label_names().

detach_label_from_channel(*, label: vitabel.timeseries.Label | str, channel: vitabel.timeseries.Channel | str | None = None, reattach_as_global: bool = True) → vitabel.timeseries.Label¶

Detach a label from a channel in the collection.

Parameters:

label: The label to detach. Can be specified either as a Label object or by its name.
channel: The channel to detach the label from or None (the default) if the channel should be determined from the label. Can be specified either as a Channel object or by its name.
reattach_as_global: If True, the label is reattached as a global label after detaching it from the channel. If False, the label is removed from the collection.

rec_start() → pandas.Timestamp¶: Returns the first timestamp among all channels in this case.

rec_stop() → pandas.Timestamp¶: Returns the last timestamp among all channels in this case.

get_channel_infos(**kwargs) → pandas.DataFrame¶

Returns information about all channels in a nicely formatted pandas.DataFrame. This includes the channel name, number of datapoints, first entry, last entry, offset, auxiliary metadata.

Parameters:

kwargs: Keyword arguments to filter the channels by. See get_channels() for valid specifications.

Returns:

pd.DataFrame: A DataFrame containing the channel information.
The DataFrame contains the following columns:

Name: The name of the channel.
Length: The number of data points in the channel.
First Entry: The first timestamp of the channel.
Last Entry: The last timestamp of the channel.
Offset: The offset of the channel, i.e., the time difference
metadata: All auxillary metadata of the channel.

get_label_infos(**kwargs) → pandas.DataFrame¶

Returns information about all labels in a nicely formatted pandas.DataFrame. This includes the label name, number of datapoints, first entry, last entry, offset, auxiliary metadata.

Parameters:

kwargs: Keyword arguments to filter the labels by. See get_labels() for valid specifications.

Returns:

pd.DataFrame: A DataFrame containing the label information.
The DataFrame contains the following columns:

Name: The name of the label.
Length: The number of data points in the label.
First Entry: The first timestamp of the label.
Last Entry: The last timestamp of the label.
Offset: The offset of the label, i.e., the time difference
metadata: All auxillary metadata of the label.

info(**kwargs) → None¶

Display relevant information about the channels and labels currently present in the recording in two separate pandas.DataFrame objects.

Parameters:

kwargs: Keyword arguments to filter the channels and labels by. See get_channels() and get_labels() for valid specifications.

Returns:

None

truncate(start_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None, stop_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None, **kwargs) → Vitals¶

Return a new object where time data has been truncated to a specified interval.

Parameters:

start_time: The start time of the truncated recording.
stop_time: The stop time of the truncated recording.
kwargs: Additional keyword arguments to filter the channels by

Returns:

Vitals: A new Vitals object containing the truncated recording.

Plot the data in the collection.

See also

TimeDataCollection.plot()

Parameters:

channels: The channels to plot. If not specified, all channels are plotted. Specified as a list of lists with individual lists containing channels to be collected in one subplot.
labels: The labels to plot. If not specified, all labels are plotted. Specified as a list of lists, same as for the channels.
start: The start time for the plot. If not specified, the plot starts from the first time point.
stop: The stop time for the plot. If not specified, the plot stops at the last time point.
resolution: The resolution of the plot in the time unit of the channels. If not specified, the channel and label data is not downsampled.
time_unit: The time unit in which channel and label data are represented in. If not specified, the time unit of the channels is used.
include_attached_labels: Whether to automatically include labels attached to the specified channels.
subplots_kwargs: Keyword arguments passed to matplotlib.pyplot.subplots.

Plot the data in the collection using ipywidgets.

This allows to annotate the data with labels, and to modify channel offsets interactively.

See also

TimeDataCollection.plot_interactive()

Parameters:

channels: The channels to plot. If not specified, all channels are plotted. Specified as a list of lists with individual lists containing channels to be collected in one subplot.
labels: The labels to plot. If not specified, all labels are plotted. Specified as a list of lists, same as for the channels.
start: The start time for the plot. If not specified, the plot starts from the first time point.
stop: The stop time for the plot. If not specified, the plot stops at the last time point.
time_unit: The time unit in which channel and label data are represented in. If not specified, the time unit of the channels is used.
include_attached_labels: Whether to automatically include labels attached to the specified channels.
channel_overviews: Similar to channel, but plots the specified channels in a separate subplot in a condensed way including a location map of the main plot. If set to True, all chosen channels are plotted in a single overview.
limited_overview: Whether the time interval of the overview subplots should be limited to the recording interval of the channels being plotted.
subplots_kwargs: Keyword arguments passed to matplotlib.pyplot.subplots.

shocks()¶

Return a list of all defibrillations with all stored information in a DataFrame.

Returns:

shockspandas.DataFrame: DESCRIPTION.

compute_etco2_and_ventilations(source: vitabel.timeseries.Channel | str = 'capnography', mode: Literal['threshold', 'filter'] = 'filter', breath_threshold: float = 2, etco2_threshold: float = 3, **kwargs)¶

Computes end-tidal CO2 (etCO₂) values and timestamps of ventilations from the capnography waveform, and adds them as labels.

The capnography signal must be present as a channel named ‘capnography’. Two detection methods are supported:

'filter': An unpublished method by Wolfgang Kern (default).
'threshold': The method described by Aramendi et al. in [AEA+17].

Parameters:

mode: Method to use for detecting ventilations from the CO₂ signal.
breath_threshold: Threshold below which a minimum is identified as a ventilation (default: 2 mmHg). Used by the 'filter' method.
etco2_threshold: Threshold above which a maximum is identified as an etCO₂ value of an expiration (default: 3 mmHg). Used by the 'filter' method.

cycle_duration_analysis(cc_events_channel: vitabel.timeseries.Channel | str | None = None) → None¶

Determines periods of continuous chest compressions based on single chest compression events.

Parameters:

cc_events_channel: The channel containing the data of single chest compression events, such that every timepoint in the timeindex represents a chest compression. Defaults to ‘cc’ or ‘cc_depth’ depending on the availability.

Returns:

None
Attaches an IntervalLabel withe the name cc_periods to the channel of single chest compressions.

See also

The method is described in [OKA+22], or in the PhD thesis [Ker24] of Wolfgang Kern in more detail.

find_CC_periods_acc(accelerometer_channel: vitabel.timeseries.Channel | str = 'cpr_acceleration') → None¶

Automatically detects periods of continuous chest compressions.

The procedure is implemented as described in [OKA+22] and [KOA+22]. In essence it uses the root mean square of the accelerometer signal of feedback sensor for cardiopulmonary resuscitation to detect the rise in “power” of the signal linked to the alteration by the accelerations of continous chest compressions.

Parameters:

accelerometer_channel: The channel containing the accelerometer signal. Defaults to ‘cpr_acceleration’.

Returns:

None.
Attaches an IntervalLabel withe the name cc_periods to the accelerometer channel.
Every entry in the label describes a single period of chest compressions.

See also

Details are given in [OKA+22] or in the PhD thesis [Ker24] by Wolfgang Kern in more detail.

predict_circulation(cpr_acceleration_source: vitabel.timeseries.Channel | str = 'cpr_acceleration', ecg_pads_source: vitabel.timeseries.Channel | str = 'ecg_pads') → None¶

Predicts the circulation of a case by using the channels 'cpr_acceleration' channel and the 'ecg_pads' channel.

The procedure that is used has been published by Kern et al. in [KOB+23]. Here 'rosc_decision_function' is the output of the kernelized SVM used in and trained for the paper.

Parameters:

cpr_acceleration_source: The (name of the) channel containing the accelerometer signal of the CPR feedback sensor. Defaults to 'cpr_acceleration'.
ecg_pads_source: The (name of the) channel containing the ECG signal from the pads. Defaults to 'ecg_pads'.

Returns:

None.
Adds three labels ‘rosc_prediction’, ‘rosc_probability’, and
‘rosc_decision_function’. ‘rosc_decision_function’ is a
pseudo-probability computed from the decision function, and
‘rosc_prediction’ is the binary prediction.

make_cprdat_analysis(model='') → dict¶: Automatically analyses a defibrillator recording and and returns a dictionary with all derived information. This functions is used in the German Resuscitation Registry to generate a case timeline as interactive visualisation.

area_under_threshold(source: vitabel.timeseries.Channel | vitabel.timeseries.Label | str, start_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None, stop_time: vitabel.typing.Timestamp | vitabel.typing.Timedelta | None = None, threshold: int = 0) → vitabel.typing.ThresholdMetrics¶

Calculates the area and duration where the signal falls below a specified threshold.

The calculations might be used with a mean arterial pressure to asses for hypotension. They are implemented following the proposed metrics by Maheswari et al. in [MKB+18].

Parameters:

source: The name of a label or channel as a string, which is passed to meth:.get_channel_or_label, or a Channel or Label object.
start_time: Start time for truncating the timeseries (meth:truncate). If None, starts from the beginning.
stop_time: End time for truncating the timeseries (meth:truncate). If None, goes until the end.
threshold: The threshold value relative to which the area under the curve (AUC) is calculated. Specifically, it computes the area where the signal lies below this threshold.

Returns:

ThresholdMetrics

See also

utils.helpers.area_under_threshold()

compute_respiratory_phases(flow: vitabel.timeseries.Channel, pressure: vitabel.timeseries.Channel, inspiratory_threshold: float = 6.55, expiratory_threshold: float = 0.85, add_labels: bool = True, add_intermediate_channels: bool = False, return_landmarks: bool = False, overwrite_existing_output: bool = False) → None¶

Derives the respiratory phases from air flow and airway pressure channels and adds them as global labels as described in Orlob et al. [OPG+26].

It expects flow in L/min and pressure in cmH₂O.

This function derives the begin of inspiration based on the product of flow and pressure see _get_inspiration_start(). The begin of expiration is derived from the product of flow and slope of pressure see _get_expiration_start(). The begin of inspiration and expiration as well as the inspiration and expiration intervals are added as global labels to the Vitals object. Additionally, an interval label for the inspiration phase is created.

Parameters:

self: :class:`.Vitals`: The Vitals object to which the respiratory phases will be added.
flow: :class:`.Channel`: The air flow channel.
pressure: :class:`.Channel`: The airway pressure channel.
inspiratory_threshold: float: The threshold for detecting the start of inspiration.
expiratory_threshold: float: The threshold for detecting the start of expiration.
add_labels: bool: Whether to add the derived respiratory phases as labels to the Vitals object. If True, the following labels are added: - Inspiration Begin as Label - Expiration Begin as Label - Inspiration as IntervalLabel - Expiration as IntervalLabel
add_intermediate_channels: bool: Whether to add intermediate channels to the Vitals object. If True, the following channels are added: - interpolated flow and pressure - product of flow and pressure (power of ventilation) in J/min - slope of pressure in cmH₂O/s - product of negative flow and slope of pressure in W/s
return_landmarks: bool: Whether to return the computed landmarks.
overwrite_existing_output: bool: Whether to overwrite existing respiratory phase labels and intermediate channels if they already exist in the Vitals object. If False and such labels exist, the function will raise an exception to avoid unintentional overwriting.

Returns:

None or RespPhases: A RespPhases object containing the timestamps of computed landmarks to derive the respiratory phases if return_landmarks is True, otherwise None.

Notes

This function and its thresholds are developed and tested on data from the following sensors:

Flow: Sensirion SFM3000, recording at ~200Hz in slm
Pressure: All Sensors DLVR-L60D, recording at ~500Hz in cmH₂O

compute_ventilation_volumes(correction_factor: float = 1.0, overwrite_existing_output: bool = False) → None¶

Compute ventilation-related volume, pressure, and reverse-flow outputs.

This method expects respiratory phases to have been computed beforehand with both intermediate channels and phase labels added to the Vitals object. It derives breath timing labels, inspiratory pressure summaries, net and phase-specific volume channels, cumulative inspiratory/expiratory volumes, and reverse-airflow summaries as described in [SWKO25].

Parameters:

correction_factor: Multiplicative factor applied to flow before all integrations. This can be used for unit conversion or sensor-specific correction.
overwrite_existing_output: If True, previously derived ventilation outputs with the same names are removed before recomputation. Otherwise a ValueError is raised if such outputs already exist.

Returns:

None: The derived channels and labels are attached to the current Vitals object.

filter_by_intervallabel(channel_or_label_to_filter: vitabel.timeseries.Channel | vitabel.timeseries.Label, filter_by: vitabel.timeseries.IntervalLabel, invert: bool = False, start_inclusive: bool = True, end_inclusive: bool = True, full_cover: bool = False) → vitabel.timeseries.Channel | vitabel.timeseries.Label¶

Filters a channel or label by a given interval label.

This creates a new channel or label containing only the data points that fall within the intervals specified in the given interval label.

Parameters:

channel_or_label_to_filter: The channel or label to filter.
filter_by: The interval label to filter by.
invert: If True, inverts the filter, i.e., keeps the parts outside the intervals defined by filter_by.
start_inclusive: If True, the start of the intervals in filter_by is considered inclusive for filtering. If invert is True, this parameter becomes inverted too.
end_inclusive: If True, the end of the intervals in filter_by is considered inclusive for filtering. If invert is True, this parameter becomes inverted too.
full_cover: Only relevant for interval Labels: - If True, keep label intervals only if they are fully contained in at least one filter interval. - If False, keep label intervals if they overlap at all with any filter interval.

Returns:

Channel | Label: The filtered channel or label.