vitabel 0.0.1__tar.gz

vitabel-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: "Release"
+
+on:
+  release:
+    types: ["published"]
+
+jobs:
+  run:
+    name: "Publish release"
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v5
+      
+      - name: Install dependencies and package
+        run: uv sync
+      
+      - name: Build package for distribution
+        run: uv build
+      
+      - name: Publish package
+        run: uv publish

vitabel-0.0.1/.github/workflows/tests.yml

@@ -0,0 +1,32 @@
+# This workflow installs the package and runs all tests
+
+name: Tests
+
+on:
+    push:
+        branches: [ "main" ]
+    pull_request:
+        branches: [ "main" ]
+
+jobs:
+    build:
+        runs-on: ${{ matrix.os }}
+        strategy:
+            matrix:
+                os: [ubuntu-latest, macos-latest, windows-latest]
+                python-version: ["3.10", "3.11", "3.12"]
+        
+        steps:
+            - uses: actions/checkout@v4
+            - name: Set up Python ${{ matrix.python-version }}
+              uses: actions/setup-python@v5
+              with:
+                  python-version: ${{ matrix.python-version }}
+            - name: Install uv
+              uses: astral-sh/setup-uv@v5
+            - name: Install dependencies and package
+              run: |
+                uv sync
+            - name: Run tests
+              run: |
+                uv run pytest

vitabel-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+*.pyc
+__pycache__
+
+dist
+
+.ipynb_checkpoints
+.venv
+
+.ruff_cache
+.pytest_cache
+.coverage
+
+.vscode

vitabel-0.0.1/LICENSE

@@ -0,0 +1,22 @@
+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.

vitabel-0.0.1/PKG-INFO

@@ -0,0 +1,116 @@
+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.

vitabel-0.0.1/README.md

@@ -0,0 +1,73 @@
+# 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.

vitabel-0.0.1/examples/01_defibrillator.ipynb

@@ -0,0 +1,259 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "9602592c-49af-4f2c-99bb-c13b8832d9bd",
+   "metadata": {},
+   "source": [
+    "# Use Case 1: Defibrillator data from real-world out-of-hospital cardiac arrest cases\n",
+    "#### This notebook illustrates the usage of the pyvital class to visualize, annotate and process time-series data from the medical field.\n",
+    "#### In this case we analyze data recorded by a defibrillator during a real-world out-of-hospital cardiac arrest case.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "8865d157-3791-4855-a97f-54350306fd38",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import bz2\n",
+    "import tempfile\n",
+    "import shutil\n",
+    "\n",
+    "from vitabel import Vitals, Label\n",
+    "from pathlib import Path"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "71ab307b-df58-4187-ac0e-e92cfdc54834",
+   "metadata": {},
+   "source": [
+    "## 1) Load Data\n",
+    "\n",
+    "An empty pyvital object is initiated and all the channels from a defibrillator recording (in this case a ZOLL X-Series case, stored in a `bz2`-compressed file) are loaded."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "680a8cdb-9363-43e7-85fe-c887eaa4923c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "case = Vitals()\n",
+    "\n",
+    "compressed_defi_file = Path(\"data/ZOLL_test_case.json.bz2\")\n",
+    "with tempfile.TemporaryDirectory() as tmpdir:\n",
+    "    defi_file = Path(tmpdir) / compressed_defi_file.stem\n",
+    "    with bz2.open(compressed_defi_file, \"rb\") as source:\n",
+    "        with open(defi_file, \"wb\") as dest:\n",
+    "            shutil.copyfileobj(source, dest)\n",
+    "\n",
+    "    case.add_defibrillator_recording(defi_file)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "61d0fe0a-0a5b-41bf-9cf5-eb9d6a7a97a8",
+   "metadata": {},
+   "source": [
+    " We get an overview over all loaded channels by calling case.info()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "02d8aad2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "case.metadata"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e0f72738-92ab-46b8-ae5f-1b99e7de719f",
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "case.info()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "db1de316-0b7e-4889-a7df-387f612acb86",
+   "metadata": {},
+   "source": [
+    "## 2) Process Data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "da69a8fb-2221-483b-bc7f-ed12075f3f5f",
+   "metadata": {},
+   "source": [
+    " We use the integrated methods to determine etco2 values from the capnography signal. \\\n",
+    "Furthermore we use the cpr_acceleration signal and the ecg from the defibrillation pads to determine predictions for the circulatory state"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f5b80780-8d7e-40b1-8b71-6737bccc1342",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "case.compute_etco2_and_ventilations()\n",
+    "case.predict_circulation()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3ad19543-11e8-4fa1-b7e1-e497fd5696da",
+   "metadata": {},
+   "source": [
+    "We want to annotate occurances of Return of spontaneous circulation (ROSC), thus we create a label and add it to our case. \n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d87a3a91-9ab5-4def-bab6-7ca0fd570c37",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ROSC_label = Label(\n",
+    "    \"ROSC\", plotstyle={\"marker\": \"$\\u2665$\", \"color\": \"red\", \"ms\": 10, \"linestyle\": \"\"}\n",
+    ")\n",
+    "case.add_global_label(ROSC_label)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b8fbdd2a-5511-4338-a32f-be65f7cecac8",
+   "metadata": {},
+   "source": [
+    " We see the new labels if check out all labels present in our case"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fa41b2ae-4e84-4781-8981-4bdbcd58d6e0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "case.get_label_names()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "28ea434a-9206-4315-8bbc-78d5d628dd65",
+   "metadata": {},
+   "source": [
+    "## 3) Interactively Plot Data\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6dd0dc57-1945-41a9-a442-65b08394edde",
+   "metadata": {},
+   "source": [
+    "We provide a setup for the interactive plot. Then we check the validity of the etco2-values and additionally label the ROSCS which we think occured in this case. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "25784f03-9ca4-4572-95c2-79a34b155a81",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "plot = case.plot_interactive(\n",
+    "    channels=[[\"cpr_acceleration\"], [\"capnography\"], [\"ecg_pads\"], []],\n",
+    "    labels=[\n",
+    "        [\"ROSC\"],\n",
+    "        [\"etco2_from_capnography\", \"ROSC\"],\n",
+    "        [\"ROSC\"],\n",
+    "        [\"ROSC\", \"rosc_probability\"],\n",
+    "    ],\n",
+    "    channel_overviews=[[\"cpr_acceleration\"]],\n",
+    "    time_unit=\"s\",\n",
+    "    subplots_kwargs={\"figsize\": (22, 9)},\n",
+    ")\n",
+    "plot"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bd25a8e6-0b93-4d8c-a042-f733f010aeb4",
+   "metadata": {},
+   "source": [
+    "Show annotated ROSC data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b51bcde7-f24a-4f70-b8de-57547dd6cf5d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ROSC_label.get_data()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e6e66a6d-a70d-40a3-835e-dfa7998c6522",
+   "metadata": {},
+   "source": [
+    "## 4) Store Data\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1b70fdc2-9650-4630-8d7f-dda463fe5972",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "case.save_data(\"case_1.json\")\n",
+    "case.get_label(\"ROSC\").to_csv()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "00fbafcb-e999-4ee0-b809-1c91fac38fc3",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}