Metadata-Version: 2.4
Name: vitabel
Version: 0.1.1
Summary: A Python framework for loading, visualizing, aligning, and labeling high-resolution physiological time series.
Project-URL: repository, https://github.com/UniGrazMath/vitabel
Project-URL: documentation, https://vitabel.readthedocs.io
Author-email: "Wolfgang J. Kern" <wolfgangjohannkern@gmail.com>, Benjamin Hackl <benjamin.hackl@uni-graz.at>, Simon Orlob <science@orlob.md>
License: MIT License
        
        Copyright (c) 2024, Benjamin Hackl, Wolfgang Kern, Simon Orlob, and individual
        contributors.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: ipykernel>=6.9
Requires-Dist: ipympl>=0.9.5
Requires-Dist: ipython>=8.23.0
Requires-Dist: ipywidgets>=8.1.5
Requires-Dist: joblib>=1.4.0
Requires-Dist: matplotlib>=3.9
Requires-Dist: numpy>=2.0.0
Requires-Dist: pandas>=2.2.3
Requires-Dist: pyedflib>=0.1.41
Requires-Dist: scikit-learn>=1.5.2
Requires-Dist: scipy>=1.14.1
Requires-Dist: typing-extensions>=4.12.2; python_full_version < '3.11'
Requires-Dist: vitaldb>=1.4.11
Description-Content-Type: text/markdown

<table width="100%">
  <tr>
    <td width="170"><img src="https://raw.githubusercontent.com/UniGrazMath/vitabel/main/assets/logo/Vitabel_Logo.png" width="150"></td>
    <td width="850">
      <b><h1 style="margin: 0;">vitabel</h1></b>
      <p style="margin-top: 0;">an open-source Python framework for visualizing and labeling high-resolution physiological data</p>
    </td>
  </tr>
</table>

[![Documentation Status](https://readthedocs.org/projects/vitabel/badge/?version=latest)](https://vitabel.readthedocs.io/en/latest/index.html)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/UniGrazMath/vitabel/main?urlpath=%2Flab%2Ftree%2Fexamples)
![PyPI](https://img.shields.io/pypi/v/vitabel)
[![Anaconda-Server Badge](https://anaconda.org/conda-forge/vitabel/badges/version.svg)](https://anaconda.org/conda-forge/vitabel)


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.

![vitabel annotation screenshot](assets/vitabel-demo.png)

### 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](https://mybinder.org/v2/gh/UniGrazMath/vitabel/main?urlpath=%2Flab%2Ftree%2Fexamples),
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
```sh
$ pip install vitabel
```

Alternatively, if you prefer using **Conda**, you can install `vitabel` from the `conda-forge` channel:
```sh
$ conda install -c conda-forge vitabel
```

The latest development version can be installed [from the `main` branch on
GitHub](https://github.com/UniGrazMath/vitabel) by running
```sh
$ 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:

```py
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](/examples/).

### 📚 Documentation

The documentation provides an overview of the framework, installation and usage guidance,
worked examples, and full API references. Start here:
[vitabel.readthedocs.io](https://vitabel.readthedocs.io/en/latest/)

### 🧾 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`](https://docs.astral.sh/uv/). To setup the environment, simply run
```sh
uv sync
```

Package tests are contained in [the `tests` directory](/tests/); run them locally via
```sh
uv run pytest
```

We use [`ruff`](https://docs.astral.sh/ruff/) for linting and formatting the code base,
and [semantic versioning](https://semver.org/) for the release tags.
