vitabel an open-source Python framework for visualizing and labeling high-resolution physiological data

In a nutshell, vitabel is an open-source Python framework for post-hoc loading, visualizing, aligning, and annotating high-resolution physiological time-series data within Jupyter notebooks. It is designed for retrospective critical care and perioperative research workflows, helping users turn heterogeneous recordings from devices such as defibrillators, anaesthesia systems, and patient monitors into curated, analysis-ready data and labels for downstream signal processing, statistics, and machine learning.

Interactive Demo in the Browser

We have setup an interactive demo illustrating some standard use cases of vitabel with the help of Binder: head over to mybinder.org, or click the binder badge at the top of this README to access the demo right in your browser.

Installation and Usage

The latest stable release of vitabel is distributed via PyPI and can be installed via

$ pip install vitabel

Alternatively, if you prefer using Conda, you can install vitabel from the conda-forge channel:

$ conda install -c conda-forge vitabel

The latest development version can be installed from the main branch on GitHub by running

$ pip install git+https://github.com/UniGrazMath/vitabel.git

vitabel is built around interactive, notebook-based workflows. Its central Vitals class acts as a container for channels, labels, and metadata, allowing users to combine recordings from different sources, align timelines, add derived labels, and curate data for downstream analysis. Data can be loaded, for example, via Vitals.add_defibrillator_recording or Vitals.add_vital_db_recording; multiple output formats of defibrillators and VitalDB-based workflows are supported.

A typical use of this package reads as follows:

from vitabel import Vitals, Label

# create case and load data
case = Vitals()
case.add_defibrillator_recording("path/to/ZOLL_data_file.json")

# use in-built methods for processing available data, compute etco2
# and predict circulatory state
case.compute_etco2_and_ventilations()
case.predict_circulation()

# create a new label for ROSC events
ROSC_label = Label('ROSC', plotstyle={'marker': '$\u2665$', 'color': 'red', 'ms': 10, 'linestyle': ''})
case.add_global_label(ROSC_label)

# display an interactive plot that allows annotations and further data adjustments
case.plot_interactive(
    channels=[['cpr_acceleration'], ['capnography'], ['ecg_pads'], []],
    labels = [['ROSC'], ['etco2_from_capnography', 'ROSC'], ['ROSC'], ['ROSC', 'rosc_probability']],
    channel_overviews=[['cpr_acceleration']],
    time_unit='s',
    subplots_kwargs={'figsize': (22, 9)}
)

More detailed explicit examples (including the required test data) are contained in the examples directory.

📚 Documentation

The documentation provides an overview of the framework, installation and usage guidance, worked examples, and full API references. Start here: vitabel.readthedocs.io

🧾 Citing vitabel

Simon Orlob, Wolfgang J. Kern, Benjamin Hackl, Jan Wnent, Jan-Thorsten Gräsner, Martin Holler
Vitabel: Bridging Clinical Expertise and the Machine Learning Pipeline in Critical Care. PREPRINT (Version 1), 29 September 2025. Research Square. https://doi.org/10.21203/rs.3.rs-7227195/v1

🛠️ Development

Setup a development environment by using the Python project and environment management tool uv. To setup the environment, simply run

uv sync

Package tests are contained in the tests directory; run them locally via

uv run pytest

We use ruff for linting and formatting the code base, and semantic versioning for the release tags.