{ "cells": [ { "cell_type": "markdown", "id": "9602592c-49af-4f2c-99bb-c13b8832d9bd", "metadata": {}, "source": [ "# Use Case 1: Defibrillator data from out-of-hospital cardiac arrest case\n", "\n", "
\n", "\n", "This notebook illustrates the usage of the `vitabel` module to visualize, annotate and process time-series data from the medical field. Please find the detailed, searchable documentation here: \n", "[![Documentation Status](https://readthedocs.org/projects/vitabel/badge/?version=latest)](https://vitabel.readthedocs.io/en/latest/?badge=latest)\n", "\n", "In this case we analyze data recorded by a defibrillator during a real-world out-of-hospital cardiac arrest case.\n", "This notebook in particular demonstrates the capabilities of `vitabel` to **display** and **annote** data.\n", "\n", "
\n", "\n", "If you have never worked with _Jupyter Notebooks_ before, you may find this guide helpful: **[Beginners Guide to Jupyter Notebooks](https://mybinder.org/v2/gh/jupyter/notebook/HEAD?urlpath=%2Fdoc%2Ftree%2Fdocs%2Fsource%2Fexamples%2FNotebook%2FRunning+Code.ipynb)**" ] }, { "cell_type": "code", "execution_count": null, "id": "8865d157-3791-4855-a97f-54350306fd38", "metadata": {}, "outputs": [], "source": [ "from vitabel import Vitals, Label\n", "\n", "import bz2\n", "from pathlib import Path\n", "import tempfile\n", "import shutil\n", "from datetime import datetime\n", "import pandas as pd" ] }, { "cell_type": "markdown", "id": "71ab307b-df58-4187-ac0e-e92cfdc54834", "metadata": {}, "source": [ "## 1. Loading Data\n", "\n", "
\n", "\n", "An empty Vitabel object called `case` is initiated and all channels from a defibrillator recording (in this case a ZOLL X-Series case, stored in a compressed file) are loaded and added to the case.\n", "\n", "
" ] }, { "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": "e89c24f6-ce00-4b9f-8dee-1b9ae39c7040", "metadata": {}, "source": [ "
\n", "\n", "Every Vitabel object as well as every channel and label holds a `metadata` dictionary. In the following we add the usage of the case in this notebook to the metadata.\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "02d8aad2", "metadata": {}, "outputs": [], "source": [ "usage_metadata = {\n", " \"vitabel publication\": {\n", " \"user\": \"ENTER YOUR NAME HERE\",\n", " \"purpose\": \"highlighting capabilities to display and annotate defibrillator data\",\n", " \"remarks\": [\n", " \"a useful tool for researchers\",\n", " \"handling data of devices by other manufacturers should be integrated better in the future\"\n", " ],\n", " }\n", "}\n", "case.metadata.update({\"usage\": usage_metadata})\n", "\n", "print(\"Current case metadata:\")\n", "case.metadata" ] }, { "cell_type": "markdown", "id": "61d0fe0a-0a5b-41bf-9cf5-eb9d6a7a97a8", "metadata": {}, "source": [ "
\n", "\n", "We get an overview over all loaded channels by calling `case.info()`\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "e0f72738-92ab-46b8-ae5f-1b99e7de719f", "metadata": {}, "outputs": [], "source": [ "case.info()" ] }, { "cell_type": "markdown", "id": "db1de316-0b7e-4889-a7df-387f612acb86", "metadata": {}, "source": [ "## 2. Processing Data" ] }, { "cell_type": "markdown", "id": "da69a8fb-2221-483b-bc7f-ed12075f3f5f", "metadata": {}, "source": [ "
\n", "\n", "We use integrated algorithms to extract **etCO₂** values and detect **ventilations** from the capnography signal.\n", "Additionally, we analyze the accelerometer data from the CPR feedback device and the ECG signal from the defibrillation pads to estimate the **probability of spontaneous circulation**.\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "f5b80780-8d7e-40b1-8b71-6737bccc1342", "metadata": {}, "outputs": [], "source": [ "case.compute_etco2_and_ventilations(source='capnography')\n", "case.predict_circulation(cpr_acceleration_source='cpr_acceleration', ecg_pads_source='ecg_pads')" ] }, { "cell_type": "markdown", "id": "c9e621f9-958d-4d3b-9d5f-b765c5b507f3", "metadata": {}, "source": [ "## 3. Adding new Labels" ] }, { "cell_type": "markdown", "id": "3ad19543-11e8-4fa1-b7e1-e497fd5696da", "metadata": {}, "source": [ "
\n", "\n", "We aim to manually **annotate** occurrences of **Return of Spontaneous Circulation (ROSC)**. To do so, we create an empty label and add it to the case. With `metadata` we can store miscellaneous data in the label inside a dictionary (`{}`). Furthermore, we can define the `plotstyle` by passing parameters in another dictionary.\n", "\n", "The argument `plot_type` determines how label data is depicted in the plot. As the type is also dynamically adapted to the available data,\n", "we can explore the different types by adding labels with different data in the later generated plot.\n", "\n", "More details on labels can be found [in our documentation](https://vitabel.readthedocs.io/en/latest/autoapi/vitabel/timeseries/index.html#vitabel.timeseries.Label).\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "d87a3a91-9ab5-4def-bab6-7ca0fd570c37", "metadata": {}, "outputs": [], "source": [ "ROSC_label = Label(\n", " name = \"ROSC\",\n", " time_index = [],\n", " data = [], \n", " text_data = [], \n", " metadata = {\n", " \"source\": \"manual annotation\",\n", " \"label initialization time\" : str(datetime.now())\n", " },\n", " plot_type = \"combined\",\n", " plotstyle = {\"marker\": \"$\\u2665$\", \"color\": \"red\", \"ms\": 10, \"linestyle\": \"\"}, \n", ")\n", "\n", "case.add_global_label(ROSC_label)" ] }, { "cell_type": "markdown", "id": "b8fbdd2a-5511-4338-a32f-be65f7cecac8", "metadata": {}, "source": [ "
\n", "\n", "We see the newly added label (`ROSC`) by checking out all present labels in the case.\n", "\n", "
" ] }, { "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": [ "## 4. Plotting Data interactively" ] }, { "cell_type": "markdown", "id": "6dd0dc57-1945-41a9-a442-65b08394edde", "metadata": {}, "source": [ "
\n", "\n", "We provide a setup for the interactive plot.\n", "\n", "The `channels` to be plottted are defined as lists in a list (`[[],[]]`). Each of the inner lists define a new subplot.\n", "The `labels` to be plotted on top are defined by another lists in a list.\n", "\n", "Subplots below the already defined ones are defined by `channel_overviews`. These subplots serve a special purpose by displaying the entire recording interval and highlighting the depicted subsegement in the upper subplots.\n", "\n", "Above the plot a menu is given to `Annotate`, `Align Timelines`, and deffines `Settings` of the plot.\n", "\n", "Try to annotate the ROSCs by clicking with the right mouse button where you assume a ROSC.\n", "Also try to toggle the checkboxes in various combinations in oder to add different data to the label.\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "25784f03-9ca4-4572-95c2-79a34b155a81", "metadata": {}, "outputs": [], "source": [ "plot = case.plot_interactive(\n", " channels = [\n", " [\"cpr_acceleration\"], \n", " [\"capnography\"], \n", " [\"ecg_pads\"], \n", " []\n", " ],\n", " labels = [\n", " [\"ROSC\", \"cc_periods\"],\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\": (16.5, 8)},\n", ")\n", "plot" ] }, { "cell_type": "markdown", "id": "bd25a8e6-0b93-4d8c-a042-f733f010aeb4", "metadata": {}, "source": [ "
\n", "\n", "The data that has been added to the *ROSC* label can be retrieved by calling the `get_data` method. The result is returned in a `DataSlice` object.\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "b51bcde7-f24a-4f70-b8de-57547dd6cf5d", "metadata": {}, "outputs": [], "source": [ "ROSC_label.get_data()" ] }, { "cell_type": "markdown", "id": "7b985f70-3e29-427a-a33b-32c05f4239ad", "metadata": {}, "source": [ "
\n", "\n", "By accessing `time_index`, `data`, or `text_data` we can explicitly obtain them from the output of `get_data`.\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "f18f9bfe-ee15-4ea6-ad11-fe07e33b2ca0", "metadata": {}, "outputs": [], "source": [ "dt = ROSC_label.get_data()\n", "print(\n", " \"Time Index: \", dt.time_index,\n", " \"\\nNumeric Values: \", dt.data,\n", " \"\\nTextual Values: \", dt.text_data,\n", " \"\\n\"\n", ")" ] }, { "cell_type": "markdown", "id": "e6e66a6d-a70d-40a3-835e-dfa7998c6522", "metadata": {}, "source": [ "## 5. Storing Data\n", "\n", "
\n", "\n", "The entire case can be serialized and stored as a JSON file.\n", "\n", "
\n" ] }, { "cell_type": "code", "execution_count": null, "id": "5d90d861-61df-43cb-a898-042504ea1beb", "metadata": {}, "outputs": [], "source": [ "case.save_data(\"case_1.json\")" ] }, { "cell_type": "markdown", "id": "31e06500-d464-49c9-8b54-6a6cc7496886", "metadata": {}, "source": [ "
\n", "\n", "Raw data of individual channels or labels can also be exported to a CSV file.\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "659c2881-73c6-489c-8e9f-4bfdc7c4918f", "metadata": {}, "outputs": [], "source": [ "case.get_label(\"ROSC\").to_csv()\n", "pd.read_csv(\"ROSC.csv\", index_col = 0)" ] }, { "cell_type": "markdown", "id": "fb98f6b6-cd20-47d7-8901-7213862de02e", "metadata": {}, "source": [ "
\n", "\n", "Alternatively, the label can also be serialized as a dictionary.\n", "\n", "
" ] }, { "cell_type": "code", "execution_count": null, "id": "00fbafcb-e999-4ee0-b809-1c91fac38fc3", "metadata": {}, "outputs": [], "source": [ "case.get_label(\"ROSC\").to_dict()" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "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.13.2" } }, "nbformat": 4, "nbformat_minor": 5 }