Metadata-Version: 2.4
Name: vitabel
Version: 0.0.1
Summary: A toolbox for plotting and interactively labeling vital data.
Project-URL: repository, https://github.com/UniGrazMath/vitabel
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: antropy>=0.1.6
Requires-Dist: ipykernel>=6.29.5
Requires-Dist: ipympl>=0.9.5
Requires-Dist: ipython>=8.30.0
Requires-Dist: ipywidgets>=8.1.5
Requires-Dist: matplotlib<3.10
Requires-Dist: numpy<2.0.0
Requires-Dist: pandas>=2.2.3
Requires-Dist: pyedflib>=0.1.38
Requires-Dist: scipy>=1.14.1
Requires-Dist: vitaldb>=1.4.11
Description-Content-Type: text/markdown

# vitabel: a toolbox for interactively annotating and labeling vital data

In a nutshell, the `vitabel` package allows loading, processing, and annotating vital
data (e.g., medical time-series data e.g. from defibrillators, anesthesia charts or critical care) interactively in a Jupyter notebook.

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

### Installation and Usage

The latest stable release of `vitabel` is distributed via PyPI and can be installed via
```sh
$ pip install 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
```

The main feature of `vitabel`, interactive plots that can be used to annotate data,
is designed to work in Jupyter notebooks. Start a new server by running `jupyter notebook`
(or create a new notebook in an existing server), then import the central `Vitals` class
that acts as a container for the vital data. A set of data can be added using, for example,
the `Vitals.add_defibrillator_recording` method, or `Vitals.add_vital_db_recording`; various output formats of defibrillators
and VitalDB 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/).

### 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.
