diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index d06c43ca..bdd25604 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -1,9 +1,9 @@ -name: HeartKit CI +name: heartKIT CI on: [push] env: - PYTHON_VERSION: '3.11' + PYTHON_VERSION: '3.12' jobs: build: diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index cd2b1fcf..14018123 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -8,12 +8,20 @@ on: - "v*" workflow_dispatch: +env: + PACKAGE_NAME: heartkit + PYTHON_VERSION: "3.12" + jobs: build: runs-on: ubuntu-latest steps: - name: Checkout 🛎️ uses: actions/checkout@v4 + - name: Setup Python 🐍 + uses: actions/setup-python@v5 + with: + python-version: ${{ env.PYTHON_VERSION }} - name: Install uv uses: astral-sh/setup-uv@v5 with: @@ -33,7 +41,7 @@ jobs: - build environment: name: pypi - url: https://pypi.org/p/heartkit + url: https://pypi.org/p/${{ env.PACKAGE_NAME }} permissions: id-token: write steps: diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..e79daae9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,7 @@ +# AGENTS + +Repo-specific notes for automation and maintenance: +- Python target is 3.12; use `uv sync` for installs and `uv run pytest tests/` for tests. +- Docs use MkDocs Material; preview with `mkdocs serve` and keep headings plain Markdown (no span wrappers). +- Prefer `rg` for searches and avoid touching binary assets unless requested. +- Commit messages follow Conventional Commits (e.g., `feat: ...`, `fix: ...`, `chore: ...`). diff --git a/README.md b/README.md index 91bd3809..66316403 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,26 @@ -

- HeartKit -

+# heartKIT ---- - -**Documentation**: https://ambiqai.github.io/heartkit +> An AI Development Kit for real-time heart-monitoring on ultra-low power SoCs -**Source Code**: https://github.com/AmbiqAI/heartkit +[![CI](https://github.com/AmbiqAI/heartkit/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/AmbiqAI/heartkit/actions/workflows/ci.yaml) +[![Docs](https://github.com/AmbiqAI/heartkit/actions/workflows/docs.yaml/badge.svg?branch=main)](https://github.com/AmbiqAI/heartkit/actions/workflows/docs.yaml) +[![Release](https://github.com/AmbiqAI/heartkit/actions/workflows/release.yaml/badge.svg?branch=main)](https://github.com/AmbiqAI/heartkit/actions/workflows/release.yaml) ---- -HeartKit is an AI Development Kit (ADK) that enables developers to easily train and deploy real-time __heart-monitoring__ models onto [Ambiq's family of ultra-low power SoCs](https://ambiq.com/soc/). The kit provides a variety of datasets, efficient model architectures, and heart-related tasks. In addition, HeartKit provides optimization and deployment routines to generate efficient inference models. Finally, the kit includes a number of pre-trained models and task-level demos to showcase the capabilities. +heartKIT is an AI Development Kit (ADK) that enables developers to easily train and deploy real-time __heart-monitoring__ models onto [Ambiq's family of ultra-low power SoCs](https://ambiq.com/soc/). The kit provides a variety of datasets, efficient model architectures, and heart-related tasks. In addition, heartKIT provides optimization and deployment routines to generate efficient inference models. Finally, the kit includes a number of pre-trained models and task-level demos to showcase the capabilities. **Key Features:** * **Real-time**: Inference is performed in real-time on battery-powered, edge devices. * **Efficient**: Leverage Ambiq's ultra low-power SoCs for extreme energy efficiency. * **Extensible**: Easily add new tasks, models, and datasets to the framework. -* **Open Source**: HeartKit is open source and available on GitHub. +* **Open Source**: heartKIT is open source and available on GitHub. -## Requirements +## Requirements -* [Python ^3.11+](https://www.python.org) +* [Python ^3.12+](https://www.python.org) * [uv ^1.6.1+](https://docs.astral.sh/uv/getting-started/installation/) The following are also required to compile/flash the binary for the EVB demo: @@ -34,7 +31,7 @@ The following are also required to compile/flash the binary for the EVB demo: !!! note A [VSCode Dev Container](https://code.visualstudio.com/docs/devcontainers/containers) is also available and defined in [./.devcontainer](https://github.com/AmbiqAI/heartkit/tree/main/.devcontainer). -## Installation +## Installation To get started, first install the local python package `heartkit` along with its dependencies via `PyPi`: @@ -52,15 +49,15 @@ uv sync --- -## Usage +## Usage -__HeartKit__ can be used as either a CLI-based tool or as a Python package to perform advanced development. In both forms, HeartKit exposes a number of modes and tasks outlined below. In addition, by leveraging highly-customizable configurations, HeartKit can be used to create custom workflows for a given application with minimal coding. Refer to the [Quickstart](https://ambiqai.github.io/heartkit/quickstart/) to quickly get up and running in minutes. +__heartKIT__ can be used as either a CLI-based tool or as a Python package to perform advanced development. In both forms, heartKIT exposes a number of modes and tasks outlined below. In addition, by leveraging highly-customizable configurations, heartKIT can be used to create custom workflows for a given application with minimal coding. Refer to the [Quickstart](https://ambiqai.github.io/heartkit/quickstart/) to quickly get up and running in minutes. --- -## Tasks +## Tasks -__HeartKit__ includes a number of built-in **tasks**. Each task provides reference routines for training, evaluating, and exporting the model. The routines can be customized by providing a configuration file or by setting the parameters directly in the code. Additional tasks can be easily added to the __HeartKit__ framework by creating a new task class and registering it to the __task factory__. +__heartKIT__ includes a number of built-in **tasks**. Each task provides reference routines for training, evaluating, and exporting the model. The routines can be customized by providing a configuration file or by setting the parameters directly in the code. Additional tasks can be easily added to the __heartKIT__ framework by creating a new task class and registering it to the __task factory__. - **Denoise**: Remove noise and artifacts from signals - **Segmentation**: Perform ECG/PPG based segmentation @@ -70,9 +67,9 @@ __HeartKit__ includes a number of built-in **tasks**. Each task provides referen --- -## Modes +## Modes -__HeartKit__ provides a number of **modes** that can be invoked for a given task. These modes can be accessed via the CLI or directly from the `task` within the Python package. +__heartKIT__ provides a number of **modes** that can be invoked for a given task. These modes can be accessed via the CLI or directly from the `task` within the Python package. - **Download**: Download specified datasets - **Train**: Train a model for specified task and datasets @@ -82,23 +79,23 @@ __HeartKit__ provides a number of **modes** that can be invoked for a given task --- -## Datasets +## Datasets -__HeartKit__ exposes several open-source datasets for training each of the HeartKit tasks via a __dataset factory__. For certain tasks, we also provide synthetic data provided by [PhysioKit](https://ambiqai.github.io/physiokit) to help improve model generalization. Each dataset has a corresponding Python class to aid in downloading and generating data for the given task. Additional datasets can be easily added to the HeartKit framework by creating a new dataset class and registering it to the dataset factory. +__heartKIT__ exposes several open-source datasets for training each of the heartKIT tasks via a __dataset factory__. For certain tasks, we also provide synthetic data provided by [physioKIT](https://ambiqai.github.io/physiokit) to help improve model generalization. Each dataset has a corresponding Python class to aid in downloading and generating data for the given task. Additional datasets can be easily added to the heartKIT framework by creating a new dataset class and registering it to the dataset factory. * **Icentia11k**: 11-lead ECG data collected from 11,000 subjects captured continously over two weeks. * **LUDB**: 200 ten-second 12-lead ECG records w/ annotated P-wave, QRS, and T-wave boundaries. * **QTDB**: 100+ fifteen-minute two-lead ECG recordings w/ annotated P-wave, QRS, and T-wave boundaries. * **LSAD**: 10-second, 12-lead ECG dataset collected from 45,152 subjects w/ over 100 scp codes. * **PTB-XL**: 10-second, 12-lead ECG dataset collected from 18,885 subjects w/ 72 different diagnostic classes. -* **Synthetic**: A synthetic dataset generator from [PhysioKit](https://ambiqai.github.io/physiokit). +* **Synthetic**: A synthetic dataset generator from [physioKIT](https://ambiqai.github.io/physiokit). * **BYOD**: Bring-Your-Own-Dataset (BYOD) to add additional datasets. --- -## Models +## Models -__HeartKit__ provides a __model factory__ that allows you to easily create and train customized models. The model factory includes a number of modern networks well suited for efficient, real-time edge applications. Each model architecture exposes a number of high-level parameters that can be used to customize the network for a given application. These parameters can be set as part of the configuration accessible via the CLI and Python package. +__heartKIT__ provides a __model factory__ that allows you to easily create and train customized models. The model factory includes a number of modern networks well suited for efficient, real-time edge applications. Each model architecture exposes a number of high-level parameters that can be used to customize the network for a given application. These parameters can be set as part of the configuration accessible via the CLI and Python package. - **[TCN](https://ambiqai.github.io/helia-edge/api/helia_edge/models/tcn)**: A CNN leveraging dilated convolutions (key=`tcn`) - **[U-Net](https://ambiqai.github.io/helia-edge/api/helia_edge/models/unet)**: A CNN with encoder-decoder architecture for segmentation tasks (key=`unet`) @@ -113,14 +110,14 @@ __HeartKit__ provides a __model factory__ that allows you to easily create and t --- -## Model Zoo +## Model Zoo -A number of pre-trained models are available for each task. These models are trained on a variety of datasets and are optimized for deployment on Ambiq's ultra-low power SoCs. In addition to providing links to download the models, __HeartKit__ provides the corresponding configuration files and performance metrics. The configuration files allow you to easily retrain the models or use them as a starting point for a custom model. Furthermore, the performance metrics provide insights into the model's accuracy, precision, recall, and F1 score. For a number of the models, we provide experimental and ablation studies to showcase the impact of various design choices. Check out the [Model Zoo](https://ambiqai.github.io/heartkit/zoo) to learn more about the available models and their corresponding performance metrics. +A number of pre-trained models are available for each task. These models are trained on a variety of datasets and are optimized for deployment on Ambiq's ultra-low power SoCs. In addition to providing links to download the models, __heartKIT__ provides the corresponding configuration files and performance metrics. The configuration files allow you to easily retrain the models or use them as a starting point for a custom model. Furthermore, the performance metrics provide insights into the model's accuracy, precision, recall, and F1 score. For a number of the models, we provide experimental and ablation studies to showcase the impact of various design choices. Check out the [Model Zoo](https://ambiqai.github.io/heartkit/zoo) to learn more about the available models and their corresponding performance metrics. --- -## Guides +## Guides -Checkout the [Guides](https://ambiqai.github.io/heartkit/guides) to see detailed examples and tutorials on how to use HeartKit for a variety of tasks. The guides provide step-by-step instructions on how to train, evaluate, and deploy models for a given task. In addition, the guides provide insights into the design choices and performance metrics for the models. The guides are designed to help you get up and running quickly and to provide a deeper understanding of the models and tasks available in HeartKit. +Checkout the [Guides](https://ambiqai.github.io/heartkit/guides) to see detailed examples and tutorials on how to use heartKIT for a variety of tasks. The guides provide step-by-step instructions on how to train, evaluate, and deploy models for a given task. In addition, the guides provide insights into the design choices and performance metrics for the models. The guides are designed to help you get up and running quickly and to provide a deeper understanding of the models and tasks available in heartKIT. --- diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png index 70383b99..71f63ace 100644 Binary files a/docs/assets/favicon.png and b/docs/assets/favicon.png differ diff --git a/docs/assets/heartkit-icon-color.png b/docs/assets/heartkit-icon-color.png new file mode 100644 index 00000000..71f63ace Binary files /dev/null and b/docs/assets/heartkit-icon-color.png differ diff --git a/docs/assets/heartkit-logo-dark.png b/docs/assets/heartkit-logo-dark.png new file mode 100644 index 00000000..171df238 Binary files /dev/null and b/docs/assets/heartkit-logo-dark.png differ diff --git a/docs/assets/heartkit-logo-light.png b/docs/assets/heartkit-logo-light.png new file mode 100644 index 00000000..c63bf693 Binary files /dev/null and b/docs/assets/heartkit-logo-light.png differ diff --git a/docs/assets/logo-white.png b/docs/assets/logo-white.png index 19a7ad55..4349b9a4 100644 Binary files a/docs/assets/logo-white.png and b/docs/assets/logo-white.png differ diff --git a/docs/assets/logo.png b/docs/assets/logo.png index 70383b99..71f63ace 100644 Binary files a/docs/assets/logo.png and b/docs/assets/logo.png differ diff --git a/docs/assets/tasks/rhythm/rhythm-demo.html b/docs/assets/tasks/rhythm/rhythm-demo.html index 8f5c8b6d..df8b5b88 100644 --- a/docs/assets/tasks/rhythm/rhythm-demo.html +++ b/docs/assets/tasks/rhythm/rhythm-demo.html @@ -1,2 +1,2 @@
-
+
diff --git a/docs/assets/tasks/segmentation/segmentation-demo.html b/docs/assets/tasks/segmentation/segmentation-demo.html index d5f4db76..577fc588 100644 --- a/docs/assets/tasks/segmentation/segmentation-demo.html +++ b/docs/assets/tasks/segmentation/segmentation-demo.html @@ -1,2 +1,2 @@
-
\ No newline at end of file +
diff --git a/docs/css/custom.css b/docs/css/custom.css index 2b3c6a78..bedbd057 100644 --- a/docs/css/custom.css +++ b/docs/css/custom.css @@ -207,3 +207,7 @@ th, td { font-size: 24px; font-weight: 300; } + +.md-typeset h2 { + color: #F52543; +} diff --git a/docs/datasets/byod.md b/docs/datasets/byod.md index 677ad8e3..6bfc62c7 100644 --- a/docs/datasets/byod.md +++ b/docs/datasets/byod.md @@ -1,8 +1,8 @@ # Bring-Your-Own-Dataset (BYOD) -The Bring-Your-Own-Dataset (BYOD) feature allows users to add custom datasets for training and evaluating models. This feature is useful when working with proprietary or custom datasets that are not available in the HeartKit library. +The Bring-Your-Own-Dataset (BYOD) feature allows users to add custom datasets for training and evaluating models. This feature is useful when working with proprietary or custom datasets that are not available in the heartKIT library. -## How it Works +## How it Works 1. **Create a Dataset**: Define a new dataset that inherits `HKDataset` and implements the required abstract methods. diff --git a/docs/datasets/icentia11k.md b/docs/datasets/icentia11k.md index f31df5c9..418b55ed 100644 --- a/docs/datasets/icentia11k.md +++ b/docs/datasets/icentia11k.md @@ -1,12 +1,12 @@ # Icentia11k Dataset -## Overview +## Overview This dataset consists of ECG recordings from 11,000 patients and 2 billion labelled beats. The data was collected by the CardioSTAT, a single-lead heart monitor device from Icentia. The raw signals were recorded with a 16-bit resolution and sampled at 250 Hz with the CardioSTAT in a modified lead 1 position. We provide derived version of the dataset where each patient is stored in separate [HDF5 files](https://www.hdfgroup.org/solutions/hdf5/) on S3. This makes it faster to download as well as makes it possible to leverage TensorFlow `prefetch` and `interleave` to parallelize data loading. More info available on [PhysioNet website](https://physionet.org/content/icentia11k-continuous-ecg/1.0) -## Usage +## Usage !!! Example Python @@ -39,16 +39,16 @@ More info available on [PhysioNet website](https://physionet.org/content/icentia The __Icentia11k dataset__ requires roughly 200 GB of disk space and can take around 2 hours to download. -## Funding +## Funding This work is partially funded by a grant from Icentia, Fonds de Recherche en Santé du Québec, and the Institute of Data Valorization (IVADO). -## Licensing +## Licensing The Icentia11k dataset is available for non-commercial use only. [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://physionet.org/content/icentia11k-continuous-ecg/view-license/1.0/) - -## References +## References * [Deep Learning for ECG Analysis: Benchmarks and Insights from PTB-XL](https://arxiv.org/pdf/2004.13701.pdf) diff --git a/docs/datasets/qtdb.md b/docs/datasets/qtdb.md index 050c9152..f604365a 100644 --- a/docs/datasets/qtdb.md +++ b/docs/datasets/qtdb.md @@ -1,6 +1,6 @@ # QTDB Dataset -## Overview +## Overview Over 100 fifteen-minute two-lead ECG recordings with onset, peak, and end markers for P, QRS, T, and (where present) U waves of from 30 to 50 selected beats in each recording. @@ -33,14 +33,14 @@ Please visit [Physionet](https://doi.org/10.13026/C24K53) for more details. ``` -## Funding +## Funding The QT Database was created as part of a project funded by the National Library of Medicine. -## License +## License The QT Database is available for commercial use. [Open Data Commons Attribution License v1.0](https://physionet.org/content/qtdb/view-license/1.0.0/) -## Supported Tasks +## Supported Tasks * [Segmentation](../tasks/segmentation.md) diff --git a/docs/datasets/synthetic.md b/docs/datasets/synthetic.md index e0b11f6e..26d0ea82 100644 --- a/docs/datasets/synthetic.md +++ b/docs/datasets/synthetic.md @@ -1,20 +1,20 @@ # Synthetic Datasets -### Overview +### Overview -By leveraging [PhysioKit](https://ambiqai.github.io/physiokit/), we are able to generate synthetic data for a variety of physiological signals, including ECG, PPG, and respiration. In addition to the signals, the tool also provides corresponding landmark fiducials and segmentation annotations. While not a replacement for real-world data, synthetic data can be useful in conjunction with real-world data for training and testing the models. +By leveraging [physioKIT](https://ambiqai.github.io/physiokit/), we are able to generate synthetic data for a variety of physiological signals, including ECG, PPG, and respiration. In addition to the signals, the tool also provides corresponding landmark fiducials and segmentation annotations. While not a replacement for real-world data, synthetic data can be useful in conjunction with real-world data for training and testing the models. -## Available Datasets +## Available Datasets ### ECG Synthetic -An ECG synthetic dataset generated using PhysioKit. The dataset enables the generation of 12-lead ECG signals with a variety of heart conditions and noise levels along with segmentations and fiducial points. +An ECG synthetic dataset generated using physioKIT. The dataset enables the generation of 12-lead ECG signals with a variety of heart conditions and noise levels along with segmentations and fiducial points. ### PPG Synthetic -A PPG synthetic dataset generated using PhysioKit. The dataset enables the generation of a 1-lead PPG signal with segmentations and fiducials. +A PPG synthetic dataset generated using physioKIT. The dataset enables the generation of a 1-lead PPG signal with segmentations and fiducials. -## Usage +## Usage !!! Example Python @@ -42,10 +42,10 @@ A PPG synthetic dataset generated using PhysioKit. The dataset enables the gener -## Funding +## Funding NA -## Licensing +## Licensing The tool is available under BSD-3-Clause License. diff --git a/docs/guides/byot.ipynb b/docs/guides/byot.ipynb index 9ec05f58..085a4310 100644 --- a/docs/guides/byot.ipynb +++ b/docs/guides/byot.ipynb @@ -25,7 +25,7 @@ "\n", "__Last Modified:__ 2024/08/15 \n", "\n", - "__Description:__ Create custom task for HeartKit end-to-end\n", + "__Description:__ Create custom task for heartKIT end-to-end\n", "\n", "## Overview \n", "\n", @@ -102,7 +102,7 @@ "\n", "We will create a dataloader class for the dataset __PTB-XL__ since it provides heart beat locations via `blabels`. \n", "\n", - "Given a raw ECG signal, we will compute the heart rate given the beat locations in the frame. The rate will be calculated based on the RR intervals using PhysioKit. The output will be the ecg signal and the heart rate in beats per second.\n" + "Given a raw ECG signal, we will compute the heart rate given the beat locations in the frame. The rate will be calculated based on the RR intervals using physioKIT. The output will be the ecg signal and the heart rate in beats per second.\n" ] }, { @@ -1047,7 +1047,7 @@ ], "metadata": { "kernelspec": { - "display_name": ".venv", + "display_name": "heartkit", "language": "python", "name": "python3" }, @@ -1061,7 +1061,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.12" + "version": "3.13.9" } }, "nbformat": 4, diff --git a/docs/guides/index.md b/docs/guides/index.md index 4cf36c31..1cd847a1 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -1,19 +1,19 @@ # Guides -This section contains guides to help with various aspects of HeartKit. The guides are designed to provide detailed information on how to use HeartKit for different tasks and workflows. +This section contains guides to help with various aspects of heartKIT. The guides are designed to provide detailed information on how to use heartKIT for different tasks and workflows. -## Core Concepts Guides +## Core Concepts Guides - + - **[Bring-Your-Own-Task](byot.ipynb)**: Demonstrate adding a new task end-to-end. -## Notebook Training Examples +## Notebook Training Examples - **[Train Arrhythmia Model](train-arrhythmia-model.ipynb)**: Training a 4-stage arrhythmia model from scratch. - **[Train ECG Denoiser](train-ecg-denoiser.ipynb)**: Training an ECG denoiser from scratch. - **[Train ECG Segmentation](train-ecg-segmentation.ipynb)**: Training an ECG segmentation model from scratch. - **[ECG Foundation Model](ecg-foundation-model.ipynb)**: Create an ECG foundation model. -## Hardware Guides +## Hardware Guides -Several guides are available for running HeartKit models on Ambiq evaluation boards (EVBs) with ECG/PPG sensors connected via the Tileio App. Please check out the [Tileio Demos Page](https://ambiqai.github.io/tileio-docs/demos/) for more information. +Several guides are available for running heartKIT models on Ambiq evaluation boards (EVBs) with ECG/PPG sensors connected via the Tileio App. Please check out the [Tileio Demos Page](https://ambiqai.github.io/tileio-docs/demos/) for more information. diff --git a/docs/guides/rhythm-demo.md b/docs/guides/rhythm-demo.md index 866c312a..a86e1450 100644 --- a/docs/guides/rhythm-demo.md +++ b/docs/guides/rhythm-demo.md @@ -1,4 +1,4 @@ -# HeartKit Rhythm Tutorial +# heartKIT Rhythm Tutorial This tutorial shows running an end-to-end heart rhythm classifier on the Apollo 4 EVB. The basic flow chart is depicted below. diff --git a/docs/guides/train-arrhythmia-model.ipynb b/docs/guides/train-arrhythmia-model.ipynb index f3cc56ce..b88eafd8 100644 --- a/docs/guides/train-arrhythmia-model.ipynb +++ b/docs/guides/train-arrhythmia-model.ipynb @@ -111,7 +111,7 @@ "source": [ "## Configure datasets\n", "\n", - "We are going to train our model using the [Large scale Arrhythmia dataset](https://ambiqai.github.io/heartkit/datasets/lsad/). This dataset uses the slug __lsad__ within HeartKit. We will download the dataset if it is not already available." + "We are going to train our model using the [Large scale Arrhythmia dataset](https://ambiqai.github.io/heartkit/datasets/lsad/). This dataset uses the slug __lsad__ within heartKIT. We will download the dataset if it is not already available." ] }, { @@ -143,7 +143,7 @@ "* Atrial Flutter/Fibrillation: Irregular heart rate (AFIB) \n", "* General Supra-Ventricular Tachycardia: Fast heart rate (GSVT)\n", "\n", - "HeartKit already provides a number of heart rhythms. We will provide a class mapping for the four classes we are interested in. We will also provide class names for display purposes." + "heartKIT already provides a number of heart rhythms. We will provide a class mapping for the four classes we are interested in. We will also provide class names for display purposes." ] }, { @@ -295,7 +295,7 @@ "source": [ "## Load rhythm task \n", "\n", - "HeartKit provides a __TaskFactory__ that includes a number ready-to-use tasks. Each task provides methods for training, evaluating, exporting, and demoing. We will grab the __rhythm__ task and configure it for our use case." + "heartKIT provides a __TaskFactory__ that includes a number ready-to-use tasks. Each task provides methods for training, evaluating, exporting, and demoing. We will grab the __rhythm__ task and configure it for our use case." ] }, { @@ -895,7 +895,7 @@ ], "metadata": { "kernelspec": { - "display_name": ".venv", + "display_name": "heartkit", "language": "python", "name": "python3" }, @@ -909,7 +909,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.12" + "version": "3.13.9" } }, "nbformat": 4, diff --git a/docs/guides/train-ecg-denoiser.ipynb b/docs/guides/train-ecg-denoiser.ipynb index d53e5495..0bba07d9 100644 --- a/docs/guides/train-ecg-denoiser.ipynb +++ b/docs/guides/train-ecg-denoiser.ipynb @@ -47,7 +47,7 @@ "\n", "__Datasets__\n", "\n", - "- **[Synthetic](https://ambiqai.github.io/heartkit/datasets/synthetic/)**: Synthetic ECG signals from PhysioKit\n", + "- **[Synthetic](https://ambiqai.github.io/heartkit/datasets/synthetic/)**: Synthetic ECG signals from physioKIT\n", "- **[PTB-XL](https://ambiqai.github.io/heartkit/datasets/ptbxl/)**: The PTB-XL is a large publicly available electrocardiography dataset. \n", "It contains 21837 clinical 12-lead ECGs from 18885 patients of 10 second length. The ECGs are sampled at 500 Hz and are annotated by up to two cardiologists.\n" ] @@ -196,7 +196,7 @@ "source": [ "## Configure datasets\n", "\n", - "Capturing noise-free ECG signals is challenging due to the presence of various artifacts. Therefore, we use a combination of synthetic and controlled, real-world datasets as our training data. HeartKit exposes an ECG Synthetic dataset generator provided by PhysioKit. \n" + "Capturing noise-free ECG signals is challenging due to the presence of various artifacts. Therefore, we use a combination of synthetic and controlled, real-world datasets as our training data. heartKIT exposes an ECG Synthetic dataset generator provided by physioKIT. \n" ] }, { @@ -308,7 +308,7 @@ "source": [ "## Load denoise task \n", "\n", - "HeartKit provides a __TaskFactory__ that includes a number ready-to-use tasks. Each task provides methods for training, evaluating, exporting, and demoing. We will grab the __denoise__ task and configure it for our use case." + "heartKIT provides a __TaskFactory__ that includes a number ready-to-use tasks. Each task provides methods for training, evaluating, exporting, and demoing. We will grab the __denoise__ task and configure it for our use case." ] }, { @@ -1023,7 +1023,7 @@ ], "metadata": { "kernelspec": { - "display_name": ".venv", + "display_name": "heartkit", "language": "python", "name": "python3" }, @@ -1037,7 +1037,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.5" + "version": "3.13.9" } }, "nbformat": 4, diff --git a/docs/guides/train-ecg-segmentation.ipynb b/docs/guides/train-ecg-segmentation.ipynb index 3a396cdc..f3efbd51 100644 --- a/docs/guides/train-ecg-segmentation.ipynb +++ b/docs/guides/train-ecg-segmentation.ipynb @@ -57,7 +57,7 @@ "\n", "__Datasets__\n", "\n", - "- **[Synthetic](https://ambiqai.github.io/heartkit/datasets/synthetic/)**: Synthetic ECG signals from PhysioKit\n", + "- **[Synthetic](https://ambiqai.github.io/heartkit/datasets/synthetic/)**: Synthetic ECG signals from physioKIT\n", "- **[LUDB](https://ambiqai.github.io/heartkit/datasets/ludb/)**: Lobachevsky University Electrocardiography database consists of 200 10-second 12-lead records. The boundaries and peaks of P, T waves and QRS complexes were manually annotated by cardiologists. Each record is annotated with the corresponding diagnosis.\n", "\n" ] @@ -120,7 +120,7 @@ "source": [ "## Target datasets\n", "\n", - "The only real-world public dataset containing ECG signals with annotated segments is the [LUDB dataset](https://ambiqai.github.io/heartkit/datasets/ludb/). We will use this dataset to train our model. In addition, we will leverage the synthetic dataset provided by PhysioKit to increase amount of data to train on. We will apply several augmentation techniques to the synthetic dataset to increase the diversity of the data. \n", + "The only real-world public dataset containing ECG signals with annotated segments is the [LUDB dataset](https://ambiqai.github.io/heartkit/datasets/ludb/). We will use this dataset to train our model. In addition, we will leverage the synthetic dataset provided by physioKIT to increase amount of data to train on. We will apply several augmentation techniques to the synthetic dataset to increase the diversity of the data. \n", "\n" ] }, @@ -400,7 +400,7 @@ "source": [ "## Load segmentation task \n", "\n", - "HeartKit provides a __TaskFactory__ that includes a number ready-to-use tasks. Each task provides methods for training, evaluating, exporting, and demoing. We will grab the __segmentation__ task and configure it for our use case." + "heartKIT provides a __TaskFactory__ that includes a number ready-to-use tasks. Each task provides methods for training, evaluating, exporting, and demoing. We will grab the __segmentation__ task and configure it for our use case." ] }, { @@ -1114,7 +1114,7 @@ ], "metadata": { "kernelspec": { - "display_name": ".venv", + "display_name": "heartkit", "language": "python", "name": "python3" }, @@ -1128,7 +1128,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.12" + "version": "3.13.9" } }, "nbformat": 4, diff --git a/docs/index.md b/docs/index.md index 0e78b887..ea737044 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,38 +1,33 @@ -# Home +# -

- HeartKit -

+[![](./assets/heartkit-logo-light.png#only-light)](https://ambiqai.github.io/heartkit/) +[![](./assets/heartkit-logo-dark.png#only-dark)](https://ambiqai.github.io/heartkit/) ---- - -**Documentation**: https://ambiqai.github.io/heartkit +*An AI Development Kit for real-time heart-monitoring on ultra-low power SoCs* -**Source Code**: https://github.com/AmbiqAI/heartkit - ---- +## Overview -Introducing HeartKit, an AI Development Kit (ADK) that enables developers to easily train and deploy real-time __heart-monitoring__ models onto [Ambiq's family of ultra-low power SoCs](https://ambiq.com/soc/). The kit provides a variety of datasets, efficient model architectures, and heart-related tasks out of the box. In addition, HeartKit provides optimization and deployment routines to generate efficient inference models. Finally, the kit includes a number of pre-trained models and task-level demos to showcase the capabilities. +Introducing heartKIT, an AI Development Kit (ADK) that enables developers to easily train and deploy real-time __heart-monitoring__ models onto [Ambiq's family of ultra-low power SoCs](https://ambiq.com/soc/). The kit provides a variety of datasets, efficient model architectures, and heart-related tasks out of the box. In addition, heartKIT provides optimization and deployment routines to generate efficient inference models. Finally, the kit includes a number of pre-trained models and task-level demos to showcase the capabilities. **Key Features:** * **Real-time**: Inference is performed in real-time on battery-powered, edge devices. * **Efficient**: Leverage Ambiq's ultra low-power SoCs for extreme energy efficiency. * **Extensible**: Easily add new tasks, models, and datasets to the framework. -* **Open Source**: HeartKit is open source and available on GitHub. +* **Open Source**: heartKIT is open source and available on GitHub. -Please explore the HeartKit Docs, a comprehensive resource designed to help you understand and utilize all the built-in features and capabilities. +Please explore the heartKIT Docs, a comprehensive resource designed to help you understand and utilize all the built-in features and capabilities. -## Getting Started +## Getting Started -- **Install** `HeartKit` with pip/uv and getting up and running in minutes.   [:material-clock-fast: Install HeartKit](./quickstart.md/#install-heartkit){ .md-button } +- **Install** `heartKIT` with pip/uv and getting up and running in minutes.   [:material-clock-fast: Install heartKIT](./quickstart.md/#install-heartkit){ .md-button } - **Train** a model with a custom network   [:fontawesome-solid-brain: Train a Model](modes/train.md){ .md-button } -- **Tasks** `HeartKit` provides tasks like rhythm, segment, and denoising   [:material-magnify-expand: Explore Tasks](tasks/index.md){ .md-button } +- **Tasks** `heartKIT` provides tasks like rhythm, segment, and denoising   [:material-magnify-expand: Explore Tasks](tasks/index.md){ .md-button } - **Datasets** Several built-in datasets can be leveraged   [:material-database-outline: Explore Datasets](./datasets/index.md){ .md-button } - **Model Zoo** Pre-trained models are available for each task   [:material-download: Explore Models](./zoo/index.md){ .md-button } - **Guides** Detailed guides on tasks, models, and datasets   [:material-book-open-page-variant: Explore Guides](./guides/index.md){ .md-button } -## Installation +## Installation To get started, first install the python package `heartkit` along with its dependencies via `Git` or `PyPi`: @@ -66,15 +61,15 @@ To get started, first install the python package `heartkit` along with its depen --- -## Usage +## Usage -__HeartKit__ can be used as either a CLI-based tool or as a Python package to perform advanced development. In both forms, HeartKit exposes a number of modes and tasks outlined below. In addition, by leveraging highly-customizable configurations and extendable factories, HeartKit can be used to create custom workflows for a given application with minimal coding. Refer to the [Quickstart](./quickstart.md) to quickly get up and running in minutes. +__heartKIT__ can be used as either a CLI-based tool or as a Python package to perform advanced development. In both forms, heartKIT exposes a number of modes and tasks outlined below. In addition, by leveraging highly-customizable configurations and extendable factories, heartKIT can be used to create custom workflows for a given application with minimal coding. Refer to the [Quickstart](./quickstart.md) to quickly get up and running in minutes. --- -## [Tasks](./tasks/index.md) +## [Tasks](./tasks/index.md) -__HeartKit__ includes a number of built-in [tasks](./tasks/index.md). Each task provides reference routines for training, evaluating, and exporting the model. The routines can be customized by providing highly flexibile configuration files/objects. Additionally, new tasks can be added to the __HeartKit__ framework by defining a new [Task class](./tasks/byot.md) and registering it to the [__Task Factory__](./tasks/byot.md). +__heartKIT__ includes a number of built-in [tasks](./tasks/index.md). Each task provides reference routines for training, evaluating, and exporting the model. The routines can be customized by providing highly flexibile configuration files/objects. Additionally, new tasks can be added to the __heartKIT__ framework by defining a new [Task class](./tasks/byot.md) and registering it to the [__Task Factory__](./tasks/byot.md). - **[Denoise](./tasks/denoise.md)**: Remove noise and artifacts from signals - **[Segmentation](./tasks/segmentation.md)**: Perform ECG/PPG based segmentation @@ -85,9 +80,9 @@ __HeartKit__ includes a number of built-in [tasks](./tasks/index.md). Each task --- -## [Modes](./modes/index.md) +## [Modes](./modes/index.md) -__HeartKit__ provides a number of [modes](./modes/index.md) that can be invoked for a given task. These modes can be accessed via the CLI or directly from a [Task](./tasks/index.md). Each mode is accompanied by a set of [task parameters](./modes/configuration.md#hktaskparams) that can be customized to fit the user's needs. +__heartKIT__ provides a number of [modes](./modes/index.md) that can be invoked for a given task. These modes can be accessed via the CLI or directly from a [Task](./tasks/index.md). Each mode is accompanied by a set of [task parameters](./modes/configuration.md#hktaskparams) that can be customized to fit the user's needs. - **[Download](./modes/download.md)**: Download specified datasets - **[Train](./modes/train.md)**: Train a model for specified task and datasets @@ -97,23 +92,23 @@ __HeartKit__ provides a number of [modes](./modes/index.md) that can be invoked --- -## [Datasets](./datasets/index.md) +## [Datasets](./datasets/index.md) -The ADK includes several built-in [datasets](./datasets/index.md) for training __heart-monitoring__ related tasks. We also provide synthetic dataset generators for signals such as ECG, PPG, and RSP along with segmentation and fiducials. Each included dataset inherits from [HKDataset](api/heartkit/datasets/dataset.md) that provides consistent interface for downloading and accessing the data. Additional datasets can be added to the HeartKit framework by creating a new dataset class and registering it to the dataset factory, [DatasetFactory](./models/index.md#model-factory). Check out the [Datasets Guide](./datasets/index.md) to learn more about the available datasets along with their corresponding licenses and limitations. +The ADK includes several built-in [datasets](./datasets/index.md) for training __heart-monitoring__ related tasks. We also provide synthetic dataset generators for signals such as ECG, PPG, and RSP along with segmentation and fiducials. Each included dataset inherits from [HKDataset](api/heartkit/datasets/dataset.md) that provides consistent interface for downloading and accessing the data. Additional datasets can be added to the heartKIT framework by creating a new dataset class and registering it to the dataset factory, [DatasetFactory](./models/index.md#model-factory). Check out the [Datasets Guide](./datasets/index.md) to learn more about the available datasets along with their corresponding licenses and limitations. * **[Icentia11k](./datasets/icentia11k.md)**: 11-lead ECG data collected from 11,000 subjects captured continously over two weeks. * **[LUDB](./datasets/ludb.md)**: 200 ten-second 12-lead ECG records w/ annotated P-wave, QRS, and T-wave boundaries. * **[QTDB](./datasets/qtdb.md)**: 100+ fifteen-minute two-lead ECG recordings w/ annotated P-wave, QRS, and T-wave boundaries. * **[LSAD](./datasets/lsad.md)**: 10-second, 12-lead ECG dataset collected from 45,152 subjects w/ over 100 scp codes. * **[PTB-XL](./datasets/ptbxl.md)**: 10-second, 12-lead ECG dataset collected from 18,885 subjects w/ 72 different diagnostic classes. -* **[Synthetic](./datasets/synthetic.md)**: A synthetic dataset generator provided by [PhysioKit](https://ambiqai.github.io/physiokit). +* **[Synthetic](./datasets/synthetic.md)**: A synthetic dataset generator provided by [physioKIT](https://ambiqai.github.io/physiokit). * **[Bring-Your-Own-Dataset (BYOD)](./datasets/byod.md)**: Add and register new datasets to the framework. --- -## [Models](./models/index.md) +## [Models](./models/index.md) -__HeartKit__ provides a variety of model architectures geared towards efficient, real-time edge applications. These models are provided by Ambiq's [helia-edge](https://ambiqai.github.io/helia-edge/) and expose a set of parameters that can be used to fully customize the network for a given application. In addition, HeartKit includes a model factory, [ModelFactory](./models/index.md#model-factory), to register current models as well as allow new custom architectures to be added. Check out the [Models Guide](./models/index.md) to learn more about the available network architectures and model factory. +__heartKIT__ provides a variety of model architectures geared towards efficient, real-time edge applications. These models are provided by Ambiq's [helia-edge](https://ambiqai.github.io/helia-edge/) and expose a set of parameters that can be used to fully customize the network for a given application. In addition, heartKIT includes a model factory, [ModelFactory](./models/index.md#model-factory), to register current models as well as allow new custom architectures to be added. Check out the [Models Guide](./models/index.md) to learn more about the available network architectures and model factory. - **[TCN](https://ambiqai.github.io/helia-edge/api/helia_edge/models/tcn)**: A CNN leveraging dilated convolutions (key=`tcn`) - **[U-Net](https://ambiqai.github.io/helia-edge/api/helia_edge/models/unet)**: A CNN with encoder-decoder architecture for segmentation tasks (key=`unet`) @@ -128,14 +123,14 @@ __HeartKit__ provides a variety of model architectures geared towards efficient, --- -## [Model Zoo](./zoo/index.md) +## [Model Zoo](./zoo/index.md) -The ADK includes a number of pre-trained models and configurationn recipes for the built-in tasks. These models are trained on a variety of datasets and are optimized for deployment on Ambiq's ultra-low power SoCs. In addition to providing links to download the models, __HeartKit__ provides the corresponding configuration files and performance metrics. The configuration files allow you to easily recreate the models or use them as a starting point for custom solutions. Furthermore, the performance metrics provide insights into the trade-offs between model complexity and performance. Check out the [Model Zoo](./zoo/index.md) to learn more about the available models and their corresponding performance metrics. +The ADK includes a number of pre-trained models and configurationn recipes for the built-in tasks. These models are trained on a variety of datasets and are optimized for deployment on Ambiq's ultra-low power SoCs. In addition to providing links to download the models, __heartKIT__ provides the corresponding configuration files and performance metrics. The configuration files allow you to easily recreate the models or use them as a starting point for custom solutions. Furthermore, the performance metrics provide insights into the trade-offs between model complexity and performance. Check out the [Model Zoo](./zoo/index.md) to learn more about the available models and their corresponding performance metrics. --- -## [Guides](./guides/index.md) +## [Guides](./guides/index.md) -Checkout the [Guides](./guides/index.md) to see detailed examples and tutorials on how to use HeartKit for a variety of tasks. The guides provide step-by-step instructions on how to train, evaluate, and deploy models for a given task. In addition, the guides provide insights into the design choices and performance metrics for the models. The guides are designed to help you get up and running quickly and to provide a deeper understanding of the capabilities provided by HeartKit. +Checkout the [Guides](./guides/index.md) to see detailed examples and tutorials on how to use heartKIT for a variety of tasks. The guides provide step-by-step instructions on how to train, evaluate, and deploy models for a given task. In addition, the guides provide insights into the design choices and performance metrics for the models. The guides are designed to help you get up and running quickly and to provide a deeper understanding of the capabilities provided by heartKIT. --- diff --git a/docs/models/byom.md b/docs/models/byom.md index 1d851788..8296f669 100644 --- a/docs/models/byom.md +++ b/docs/models/byom.md @@ -2,7 +2,7 @@ The model factory can be extended to include custom models. This is useful when you have a custom model architecture that you would like to use for training. The custom model can be registered with the model factory by defining a custom model function and registering it with the `ModelFactory`. -## How it Works +## How it Works 1. **Create a Model**: Define a new model function that takes a `keras.Input`, model parameters, and number of classes as arguments and returns a `keras.Model`. @@ -53,7 +53,7 @@ The model factory can be extended to include custom models. This is useful when ``` -## Better Model Params +## Better Model Params Rather than using a dictionary to define the model parameters, you can define a custom dataclass or [Pydantic](https://pydantic-docs.helpmanual.io/) model to enforce type checking and provide better documentation. diff --git a/docs/models/index.md b/docs/models/index.md index 2cce74a0..e0e3ac0f 100644 --- a/docs/models/index.md +++ b/docs/models/index.md @@ -1,10 +1,10 @@ # :material-graph-outline: Models -HeartKit provides a number of model architectures that can be used for training __heart-monitoring tasks__. While a number of off-the-shelf models exist, they are often not efficient nor optimized for real-time, edge applications. To address this, HeartKit provides a model factory that allows you to easily create and train customized models via [helia-edge](https://ambiqai.github.io/helia-edge/). `helia-edge` includes a growing number of state-of-the-art models that can be easily configured and trained using high-level parameters. The models are designed to be efficient and well-suited for real-time, edge applications. Most of the models are based on state-of-the-art architectures that have been modified to allow for more fine-grain customization. In addition, the models support 1D variants to allow for training on time-series data. Please check [helia-edge](https://ambiqai.github.io/helia-edge/) for list of available models and their configurations. +heartKIT provides a number of model architectures that can be used for training __heart-monitoring tasks__. While a number of off-the-shelf models exist, they are often not efficient nor optimized for real-time, edge applications. To address this, heartKIT provides a model factory that allows you to easily create and train customized models via [helia-edge](https://ambiqai.github.io/helia-edge/). `helia-edge` includes a growing number of state-of-the-art models that can be easily configured and trained using high-level parameters. The models are designed to be efficient and well-suited for real-time, edge applications. Most of the models are based on state-of-the-art architectures that have been modified to allow for more fine-grain customization. In addition, the models support 1D variants to allow for training on time-series data. Please check [helia-edge](https://ambiqai.github.io/helia-edge/) for list of available models and their configurations. --- -## Available Models +## Available Models - **[TCN](https://ambiqai.github.io/helia-edge/api/helia_edge/models/tcn)**: A CNN leveraging dilated convolutions (key=`tcn`) - **[U-Net](https://ambiqai.github.io/helia-edge/api/helia_edge/models/unet)**: A CNN with encoder-decoder architecture for segmentation tasks (key=`unet`) @@ -15,13 +15,13 @@ HeartKit provides a number of model architectures that can be used for training - **[Conformer](https://ambiqai.github.io/helia-edge/api/helia_edge/models/conformer)**: A transformer composed of both convolutional and self-attention blocks (key=`conformer`) - **[MetaFormer](https://ambiqai.github.io/helia-edge/api/helia_edge/models/metaformer)**: A transformer composed of both spatial mixing and channel mixing blocks (key=`metaformer`) - **[TSMixer](https://ambiqai.github.io/helia-edge/api/helia_edge/models/tsmixer)**: An All-MLP Architecture for Time Series Classification (key=`tsmixer`) -* **[Bring-Your-Own-Model](./byom.md)**: Add a custom model architecture to HeartKit. +* **[Bring-Your-Own-Model](./byom.md)**: Add a custom model architecture to heartKIT. --- -## Model Factory +## Model Factory -HeartKit includes a model factory, `ModelFactory`, that eases the processes of creating models for training. The factory allows you to create models by specifying the model key and the model parameters. The factory will then create the model using the specified parameters. The factory also allows you to register custom models that can be used for training. By leveraring a factory, a task only needs to provide the architecture key and the parameters, and the factory will take care of the rest. +heartKIT includes a model factory, `ModelFactory`, that eases the processes of creating models for training. The factory allows you to create models by specifying the model key and the model parameters. The factory will then create the model using the specified parameters. The factory also allows you to register custom models that can be used for training. By leveraring a factory, a task only needs to provide the architecture key and the parameters, and the factory will take care of the rest. The model factory provides the following methods: @@ -33,7 +33,7 @@ The model factory provides the following methods: --- -## Usage +## Usage ### Defining a model in configuration file diff --git a/docs/modes/configuration.md b/docs/modes/configuration.md index 5440eb54..598939dd 100644 --- a/docs/modes/configuration.md +++ b/docs/modes/configuration.md @@ -2,7 +2,7 @@ For each mode, common configuration parameters, [HKTaskParams](#hktaskparams), are required to run the task. These parameters are used to define the task, datasets, model, and other settings. Rather than defining separate configuration files for each mode, a single configuration object is used to simplify configuration files and heavy re-use of parameters between modes. -## QuantizationParams +## QuantizationParams Quantization parameters define the quantization-aware training (QAT) and post-training quantization (PTQ) settings. This is used for modes: train, evaluate, export, and demo. @@ -16,7 +16,7 @@ Quantization parameters define the quantization-aware training (QAT) and post-tr | debug | bool | Optional | False | Debug quantization | | fallback | bool | Optional | False | Fallback to float32 | -## NamedParams +## NamedParams Named parameters are used to provide custom parameters for a given object or callable where parameter types are not known ahead of time. For example, a dataset, 'CustomDataset', may require custom parameters such as 'path', 'label', 'sampling_rate', etc. When a task loads the dataset using `name`, the task will then unpack the custom parameters and pass them to the dataset initializer. @@ -48,7 +48,7 @@ params = hk.HKTaskParams( ``` -## HKTaskParams +## HKTaskParams These parameters are supplied to a [Task](../tasks/index.md) when running a given mode such as `train`, `evaluate`, `export`, or `demo`. A single configuration object is used to simplify configuration files and heavy re-use of parameters between modes. diff --git a/docs/modes/demo.md b/docs/modes/demo.md index 82f99a43..b1478a8e 100644 --- a/docs/modes/demo.md +++ b/docs/modes/demo.md @@ -1,8 +1,8 @@ # :material-hexagon-multiple: Task-Level Demo -## Introduction +## Introduction -Each task in HeartKit has a corresponding demo mode that allows you to run a task-level demonstration using the specified backend inference engine (e.g. PC or EVB). This is useful to showcase the model's performance in real-time and to verify its accuracy in a real-world scenario. Similar to other modes, the demo can be invoked either via CLI or within `heartkit` python package. At a high level, the demo mode performs the following actions based on the provided configuration parameters: +Each task in heartKIT has a corresponding demo mode that allows you to run a task-level demonstration using the specified backend inference engine (e.g. PC or EVB). This is useful to showcase the model's performance in real-time and to verify its accuracy in a real-world scenario. Similar to other modes, the demo can be invoked either via CLI or within `heartkit` python package. At a high level, the demo mode performs the following actions based on the provided configuration parameters: 1. Load the configuration data (e.g. `configuration.json`) 1. Load the desired datasets (e.g. `icentia11k`) @@ -50,9 +50,9 @@ F ==> G --- -## Backend Inference Engines +## Backend Inference Engines -HeartKit includes two built-in backend inference engines: PC and EVB. Additional backends can be easily added to the HeartKit framework by creating a new backend class and registering it to the backend factory, `BackendFactory`. +heartKIT includes two built-in backend inference engines: PC and EVB. Additional backends can be easily added to the heartKIT framework by creating a new backend class and registering it to the backend factory, `BackendFactory`. ### PC Backend Inference Engine @@ -75,7 +75,7 @@ The EVB backend is used to run the task-level demo on an Ambiq EVB. This is usef ### Bring-Your-Own-Backend Engine -Similar to datasets, dataloaders, tasks, and models, the demo mode can be customized to use your own backend inference engine. HeartKit includes a backend factory (`BackendFactory`) that is used to create and run the backend engine. +Similar to datasets, dataloaders, tasks, and models, the demo mode can be customized to use your own backend inference engine. heartKIT includes a backend factory (`BackendFactory`) that is used to create and run the backend engine. #### How it Works @@ -138,9 +138,9 @@ Similar to datasets, dataloaders, tasks, and models, the demo mode can be custom --- -## Usage +## Usage -The following is an example of a task-level demo report for the segmentation task. Upon running segmentation, the demo will extract inter-beat-intervals (IBIs) and report various HR and HRV metrics. These metrics are computed using Ambiq's [PhysioKit Python Package](https://ambiqai.github.io/physiokit)- a toolkit to process raw ambulatory bio-signals. +The following is an example of a task-level demo report for the segmentation task. Upon running segmentation, the demo will extract inter-beat-intervals (IBIs) and report various HR and HRV metrics. These metrics are computed using Ambiq's [physioKIT Python Package](https://ambiqai.github.io/physiokit)- a toolkit to process raw ambulatory bio-signals. === "CLI" @@ -159,7 +159,7 @@ The following is an example of a task-level demo report for the segmentation tas --- -## Arguments +## Arguments Please refer to [HKTaskParams](../modes/configuration.md) for the list of arguments that can be used with the `demo` command. diff --git a/docs/modes/download.md b/docs/modes/download.md index 2aa36524..8a32ac54 100644 --- a/docs/modes/download.md +++ b/docs/modes/download.md @@ -1,10 +1,10 @@ # :material-download: Download Datasets -## Introduction +## Introduction -The `download` command is used to download specified datasets. Please refer to [Datasets](../datasets/index.md) for details on the available datasets. Additional datasets can be added by creating a new dataset class and registering it with __HeartKit__ dataset factory, [DatasetFactory](../datasets/index.md#dataset-factory). +The `download` command is used to download specified datasets. Please refer to [Datasets](../datasets/index.md) for details on the available datasets. Additional datasets can be added by creating a new dataset class and registering it with __heartKIT__ dataset factory, [DatasetFactory](../datasets/index.md#dataset-factory). -## Usage +## Usage ### CLI @@ -48,6 +48,6 @@ task.download(params) ``` -## Arguments +## Arguments Please refer to [HKTaskParams](../modes/configuration.md#hktaskparams) for the available configuration options for the `download` command. diff --git a/docs/modes/evaluate.md b/docs/modes/evaluate.md index 698feb7c..63c5d64b 100644 --- a/docs/modes/evaluate.md +++ b/docs/modes/evaluate.md @@ -1,6 +1,6 @@ # :material-ab-testing: Model Evaluation -## Introduction +## Introduction Evaluate mode is used to test the performance of the model on the reserved test set for the specified task. Similar to training, the routine can be customized via CLI configuration file or by setting the parameters directly in the code. The evaluation process involves testing the model's performance on the test data to measure its accuracy, precision, recall, and F1 score. A number of results and metrics will be generated and saved to the `job_dir`. @@ -62,7 +62,7 @@ F ==> G --- -## Usage +## Usage ### CLI @@ -91,6 +91,6 @@ task.evaluate(params) --- -## Arguments +## Arguments Please refer to [HKTaskParams](../modes/configuration.md#hktaskparams) for the list of arguments that can be used with the `evaluate` command. diff --git a/docs/modes/export.md b/docs/modes/export.md index 93457c76..6834ba44 100644 --- a/docs/modes/export.md +++ b/docs/modes/export.md @@ -1,6 +1,6 @@ # :material-export: Model Exporting -## Introduction +## Introduction Export mode is used to convert the trained TensorFlow model into a format that can be used for deployment onto Ambiq's family of SoCs. Currently, the command will convert the TensorFlow model into both TensorFlow Lite (TFL) and TensorFlow Lite for micro-controller (TFLM) variants. The command will also verify the models' outputs match. The activations and weights can be quantized by configuring the `quantization` section in the configuration file or by setting the `quantization` parameter in the code. @@ -57,7 +57,7 @@ F ==> G --- -## Usage +## Usage ### CLI @@ -86,6 +86,6 @@ task.export(params) --- -## Arguments +## Arguments Please refer to [HKTaskParams](../modes/configuration.md#hktaskparams) for the list of arguments that can be used with the `export` command. diff --git a/docs/modes/index.md b/docs/modes/index.md index fd7c43f8..39d655cf 100644 --- a/docs/modes/index.md +++ b/docs/modes/index.md @@ -1,14 +1,14 @@ -# HeartKit Task Modes +# heartKIT Task Modes -## Introduction +## Introduction -Rather than offering a handful of static models, HeartKit provides a complete framework designed to cover the entire design process of creating customized ML models well-suited for low-power, wearable applications. Each mode serves a specific purpose and is engineered to offer you the flexibility and efficiency required for different tasks and use-cases. +Rather than offering a handful of static models, heartKIT provides a complete framework designed to cover the entire design process of creating customized ML models well-suited for low-power, wearable applications. Each mode serves a specific purpose and is engineered to offer you the flexibility and efficiency required for different tasks and use-cases. Each `Task` implementes routines for each of the modes: [download](#download), [train](#train), [evaluate](#evaluate), [export](#export), and [demo](#demo). These modes are designed to streamline the process of training, evaluating, exporting, and running task-level demonstrations on the trained models. --- -## Available Modes +## Available Modes - **[Download](./download.md)**: Download specified datasets - **[Train](./train.md)**: Train a model for specified task and datasets @@ -18,23 +18,23 @@ Each `Task` implementes routines for each of the modes: [download](#download), [ --- -## [Download](./download.md) +## [Download](./download.md) [Download mode](./download.md) is used to download the specified datasets for the task. The routine can be customized via the configuration file or by setting the parameters directly in the code. The download process involves fetching the dataset(s) from the specified source and storing them in the specified directory. -## [Train](./train.md) +## [Train](./train.md) [Train mode](./train.md) is used to train a model for the specified task and dataset. In this mode, the model is trained for a given task using the specified dataset(s), model architecture, and hyperparameters. The training process involves optimizing the model's parameters to maximize its performance on the training data. -## [Evaluate](./evaluate.md) +## [Evaluate](./evaluate.md) [Evaluate mode](./evaluate.md) is used to test the performance of the model on the reserved test set for the specified task. The routine can be customized via the configuration file or by setting the parameters directly in the code. The evaluation process involves testing the model's performance on the test data to measure its accuracy, precision, recall, and F1 score. -## [Export](./export.md) +## [Export](./export.md) [Export mode](./export.md) is used to convert the trained model into a format that can be used for deployment onto Ambiq's family of SoCs. Currently, the command will convert the TensorFlow model into both TensorFlow Lite (TFL) and TensorFlow Lite for micro-controller (TFLM) variants. The command will also verify the models' outputs match. -## [Demo](./demo.md) +## [Demo](./demo.md) [Demo mode](./demo.md) is used to run a task-level demonstration on the trained model using the specified backend inference engine (e.g. PC or EVB). This is useful to showcase the model's performance in real-time and to verify its accuracy in a real-world scenario. diff --git a/docs/modes/train.md b/docs/modes/train.md index 819ffa09..cbe9391e 100644 --- a/docs/modes/train.md +++ b/docs/modes/train.md @@ -1,6 +1,6 @@ # :material-chart-ppf: Model Training -## Introduction +## Introduction Each task provides a mode to train a model on the specified datasets and dataloaders. The training mode can be invoked either via CLI or within `heartkit` python package. At a high level, the training mode performs the following actions based on the provided configuration parameters: @@ -63,7 +63,7 @@ F ==> G --- -## Usage +## Usage ### CLI @@ -93,15 +93,15 @@ task.train(params) --- -## Arguments +## Arguments Please refer to [HKTaskParams](../modes/configuration.md#hktaskparams) for the list of arguments that can be used with the `train` command. --- -## Logging +## Logging -__HeartKit__ provides built-in support for logging to several third-party services including [Weights & Biases](https://wandb.ai/site) (WANDB) and [TensorBoard](https://www.tensorflow.org/tensorboard). +__heartKIT__ provides built-in support for logging to several third-party services including [Weights & Biases](https://wandb.ai/site) (WANDB) and [TensorBoard](https://www.tensorflow.org/tensorboard). ### WANDB diff --git a/docs/quickstart.md b/docs/quickstart.md index edc3df0e..616124f7 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,9 +1,9 @@ # Quickstart -## Install HeartKit +## Install heartKIT -We provide several installation methods including pip, uv, and Docker. Install __HeartKit__ via pip/uv for the latest stable release or by cloning the GitHub repo for the most up-to-date. Additionally, a [VSCode Dev Container](https://code.visualstudio.com/docs/devcontainers/containers) is available and defined in [./.devcontainer](https://github.com/AmbiqAI/heartkit/tree/main/.devcontainer) to run in an isolated Docker environment. +We provide several installation methods including pip, uv, and Docker. Install __heartKIT__ via pip/uv for the latest stable release or by cloning the GitHub repo for the most up-to-date. Additionally, a [VSCode Dev Container](https://code.visualstudio.com/docs/devcontainers/containers) is available and defined in [./.devcontainer](https://github.com/AmbiqAI/heartkit/tree/main/.devcontainer) to run in an isolated Docker environment. !!! install @@ -27,7 +27,7 @@ We provide several installation methods including pip, uv, and Docker. Install _ === "PyPI install" - Install the HeartKit package using pip or uv. + Install the heartKIT package using pip or uv. Visit the Python Package Index (PyPI) for more details on the package: [https://pypi.org/project/heartkit/](https://pypi.org/project/heartkit/) ```bash @@ -55,7 +55,7 @@ We provide several installation methods including pip, uv, and Docker. Install _ ``` -## Requirements +## Requirements * [Python ^3.11+](https://www.python.org) * [uv ^0.7.10+](https://docs.astral.sh/uv/getting-started/installation/) @@ -65,13 +65,13 @@ Check the project's [pyproject.toml](https://github.com/AmbiqAI/heartkit/blob/ma * [Arm GNU Toolchain ^12.2](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads) * [Segger J-Link ^7.92](https://www.segger.com/downloads/jlink/) -Once installed, __HeartKit__ can be used as either a CLI-based tool or as a Python package to perform advanced experimentation. +Once installed, __heartKIT__ can be used as either a CLI-based tool or as a Python package to perform advanced experimentation. --- -## Use HeartKit with CLI +## Use heartKIT with CLI -The HeartKit command line interface (CLI) allows for simple single-line commands to download datasets, train models, evaluate performance, and export models. The CLI requires no customization or Python code. You can simply run all the built-in tasks from the terminal with the __heartkit__ command. Check out the [CLI Guide](./usage/cli.md) to learn more about available options. +The heartKIT command line interface (CLI) allows for simple single-line commands to download datasets, train models, evaluate performance, and export models. The CLI requires no customization or Python code. You can simply run all the built-in tasks from the terminal with the __heartkit__ command. Check out the [CLI Guide](./usage/cli.md) to learn more about available options. !!! example @@ -122,11 +122,11 @@ The HeartKit command line interface (CLI) allows for simple single-line commands heartkit -m demo -t rhythm -c ./configuration.json ``` -## Use HeartKit with Python +## Use heartKIT with Python -The __HeartKit__ Python package allows for more fine-grained control and customization. You can use the package to train, evaluate, and deploy models for a variety of tasks. You can create custom datasets, models, and tasks and register them with corresponding factories and use them like built-in tasks. +The __heartKIT__ Python package allows for more fine-grained control and customization. You can use the package to train, evaluate, and deploy models for a variety of tasks. You can create custom datasets, models, and tasks and register them with corresponding factories and use them like built-in tasks. -For example, you can create a custom task, train it, evaluate its performance on a validation set, and even export a quantized TensorFlow Lite model for deployment. Check out the [Python Guide](./usage/python.md) to learn more about using HeartKit as a Python package. +For example, you can create a custom task, train it, evaluate its performance on a validation set, and even export a quantized TensorFlow Lite model for deployment. Check out the [Python Guide](./usage/python.md) to learn more about using heartKIT as a Python package. !!! Example diff --git a/docs/tasks/beat.md b/docs/tasks/beat.md index 6148a6f0..ffc50d58 100644 --- a/docs/tasks/beat.md +++ b/docs/tasks/beat.md @@ -1,6 +1,6 @@ # Beat Classification Task -## Overview +## Overview In beat classification, we classify individual beats as either normal or abnormal. Abnormal beats can be further classified as being either premature or escape beats as well as originating from the atria, junction, or ventricles. The objective of beat classification is to detect and classify these abnormal heart beats directly from ECG signals. @@ -10,7 +10,7 @@ In beat classification, we classify individual beats as either normal or abnorma --- -## Characteristics +## Characteristics | | Atrial | Junctional | Ventricular | | --- | --- | --- | --- | @@ -19,7 +19,7 @@ In beat classification, we classify individual beats as either normal or abnorma --- -## Dataloaders +## Dataloaders Dataloaders are available for the following datasets: @@ -28,7 +28,7 @@ Dataloaders are available for the following datasets: --- -## Pre-trained Models +## Pre-trained Models The following table provides the latest performance and accuracy results for pre-trained beat models. Additional result details can be found in [Model Zoo → Beat](../zoo/beat.md). @@ -37,7 +37,7 @@ The following table provides the latest performance and accuracy results for pre --- -## Target Classes +## Target Classes Below outlines the classes available for beat classification. When training a model, the number of classes, mapping, and names must be provided. diff --git a/docs/tasks/byot.md b/docs/tasks/byot.md index 1b49d687..78249c43 100644 --- a/docs/tasks/byot.md +++ b/docs/tasks/byot.md @@ -4,7 +4,7 @@ The Bring-Your-Own-Task (BYOT) feature allows users to create custom tasks for t For an in-depth guide check out the [BYOT Notebook Guide](../guides/byot.ipynb). -## How it Works +## How it Works 1. **Create a Task**: Define a new task that inherits from the [HKTask](/heartkit/api/heartkit/tasks/task) base class and implements the required methods: `train`, `evaluate`, `export`, and `demo`. diff --git a/docs/tasks/denoise.md b/docs/tasks/denoise.md index 409b4396..f29e5082 100644 --- a/docs/tasks/denoise.md +++ b/docs/tasks/denoise.md @@ -1,6 +1,6 @@ # Signal Denoising Task -## Overview +## Overview The objective of denoising is to remove noise and artifacts from physiological signals while preserving the underlying signal information. The dominant noise sources include baseline wander (BW), muscle noise (EMG), electrode movement artifacts (EM), and powerline interference (PLI). For physiological signals such as ECG and PPG, removing the artifacts is difficult due to the non-stationary nature of the noise and overlapping frequency bands with the signal. While traditional signal processing techniques such as filtering and wavelet denoising have been used to remove noise, deep learning models have shown great promise in enhanced denoising. @@ -10,7 +10,7 @@ The objective of denoising is to remove noise and artifacts from physiological s --- -## Noise Characteristics +## Noise Characteristics The following table summarizes the characteristics of common noise sources in ECG signals: @@ -31,7 +31,7 @@ The following table summarizes the characteristics of common noise sources in PP --- -## Dataloaders +## Dataloaders Dataloaders are available for the following datasets: @@ -42,7 +42,7 @@ Dataloaders are available for the following datasets: --- -## Pre-trained Models +## Pre-trained Models The following table provides the latest performance and accuracy results of denoising models. Additional result details can be found in [Model Zoo → Denoise](../zoo/index.md). @@ -51,7 +51,7 @@ The following table provides the latest performance and accuracy results of deno --- -## References +## References * [DeScoD-ECG: Deep Score-Based Diffusion Model for ECG Baseline Wander and Noise Removal](https://arxiv.org/pdf/2208.00542.pdf) * [DEEPFILTER: AN ECG BASELINE WANDER REMOVAL FILTER USING DEEP LEARNING TECHNIQUES](https://arxiv.org/pdf/2101.03423.pdf) diff --git a/docs/tasks/index.md b/docs/tasks/index.md index a899c9a2..01a4426a 100644 --- a/docs/tasks/index.md +++ b/docs/tasks/index.md @@ -1,8 +1,8 @@ # :simple-task: Tasks -## Introduction +## Introduction -HeartKit provides several built-in __heart-monitoring__ tasks. Each task is designed to address a unique aspect such as ECG denoising, segmentation, and rhythm/beat classification. The tasks are designed to be modular and can be used independently or in combination to address specific use cases. In addition to the built-in tasks, custom tasks can be created by extending the [HKTask](/heartkit/api/heartkit/tasks/task) base class and registering it with the task factory. +heartKIT provides several built-in __heart-monitoring__ tasks. Each task is designed to address a unique aspect such as ECG denoising, segmentation, and rhythm/beat classification. The tasks are designed to be modular and can be used independently or in combination to address specific use cases. In addition to the built-in tasks, custom tasks can be created by extending the [HKTask](/heartkit/api/heartkit/tasks/task) base class and registering it with the task factory.
![Task Diagram](../assets/tasks/heartkit-task-diagram.svg){ width="600" } @@ -10,35 +10,35 @@ HeartKit provides several built-in __heart-monitoring__ tasks. Each task is desi --- -## Available Tasks +## Available Tasks -### [Signal Denoise](./denoise.md) +### [Signal Denoise](./denoise.md) [Signal denoise](./denoise.md) is the process of removing noise from a physiological signal such as ECG. This task is useful for improving the quality of the signal and for further downstream tasks such as segmentation in which noise can interfere with the delineation of individual waves. -### [Signal Segmentation](./segmentation.md) +### [Signal Segmentation](./segmentation.md) [Signal segmentation](./segmentation.md) is the process of delineating a signal into its constituent parts. In the context of ECG, segmentation refers to delineating the ECG signal into individual waves (e.g. P-wave, QRS, T-wave). This task is useful for extracting features (e.g. HRV) from the ECG signal and for further analysis such as rhythm classification. -### [Rhythm Classification](./rhythm.md) +### [Rhythm Classification](./rhythm.md) [Rhythm classification](./rhythm.md) is the process of identifying abnormal heart rhythms, also known as arrhythmias, such as atrial fibrillation (AFIB) and atrial flutter (AFL) from ECG signals. Cardiovascular diseases such as AFIB are a leading cause of morbidity and mortality worldwide. Being able to remotely identify heart arrhtyhmias is important for early detection and intervention. -### [Beat Classification](./beat.md) +### [Beat Classification](./beat.md) [Beat classification](./beat.md) is the process of identifying and classifying individual heart beats such as normal, premature, and escape beats from ECG signals. By identifying abnormal heart beats, it is possible to detect and monitor various heart conditions. - -### [Bring-Your-Own-Task (BYOT)](./byot.md) +### [Bring-Your-Own-Task (BYOT)](./byot.md) [Bring-Your-Own-Task (BYOT)](./byot.md) is a feature that allows users to create custom tasks by extending the [HKTask](/heartkit/api/heartkit/tasks/task) base class and registering it with the `TaskFactory`. This feature is useful for addressing specific use cases that are not covered by the built-in tasks. --- -## Task Factory +## Task Factory The task factory, `TaskFactory`, provides a convenient way to access the built-in tasks. The factory is a thread-safe singleton class that provides a single point of access to the tasks via the tasks' slug names. The benefit of using the factory is it allows registering custom tasks that can then be used just like built-in tasks. diff --git a/docs/tasks/rhythm.md b/docs/tasks/rhythm.md index 8d0a4e80..91bbd111 100644 --- a/docs/tasks/rhythm.md +++ b/docs/tasks/rhythm.md @@ -1,6 +1,6 @@ # Rhythm Classification Task -## Overview +## Overview The objective of rhythm classification is to detect and classify abnormal heart rhythms, also known as arrhythmias, directly from ECG signals. @@ -10,7 +10,7 @@ The objective of rhythm classification is to detect and classify abnormal heart --- -## Characteristics +## Characteristics There are a variety of heart rhythms that can be detected using ECG signals. In this task, we predominantly focus on detecting arrhythmias such as atrial fibrillation (AFIB) and atrial flutter (AFL). The following table summarizes characteristics of a few rhythms: @@ -65,7 +65,7 @@ There are a variety of heart rhythms that can be detected using ECG signals. In --- -## Dataloaders +## Dataloaders Dataloaders are available for the following datasets: @@ -75,7 +75,7 @@ Dataloaders are available for the following datasets: --- -## Pre-trained Models +## Pre-trained Models The following table provides the latest performance and accuracy results for rhythm models. Additional result details can be found in [Model Zoo → Rhythm](../zoo/index.md). @@ -84,7 +84,7 @@ The following table provides the latest performance and accuracy results for rhy --- -## Target Classes +## Target Classes Below outlines the classes available for rhythm classification. When training a model, the number of classes, mapping, and names must be provided. @@ -109,7 +109,7 @@ Below outlines the classes available for rhythm classification. When training a --- -## References +## References * [ECG Heartbeat classification using deep transfer learning with Convolutional Neural Network and STFT technique](https://arxiv.org/abs/2206.14200) * [Classification of ECG based on Hybrid Features using CNNs for Wearable Applications](https://arxiv.org/pdf/2206.07648.pdf) diff --git a/docs/tasks/segmentation.md b/docs/tasks/segmentation.md index 12b6fff5..c8d6c4e9 100644 --- a/docs/tasks/segmentation.md +++ b/docs/tasks/segmentation.md @@ -1,6 +1,6 @@ # Signal Segmentation Task -## Overview +## Overview The objective of segmentation is to delineate key segments of the signal. In the context of ECG signals, this involves identifying the different components of the cardiac cycle, including the P-wave, QRS complex, and T-wave. These segments are used to compute a number of clinically relevant metrics, including heart rate, PR interval, QRS duration, QT interval, and QTc interval. For PPG, the task involves segmenting the systolic and diastolic phases of the cardiac cycle. Segmentation models are useful for detecting arrhythmias, heart rate variability, and other cardiac abnormalities. @@ -11,7 +11,7 @@ The objective of segmentation is to delineate key segments of the signal. In the --- -## ECG Characteristics +## ECG Characteristics
@@ -35,7 +35,7 @@ The objective of segmentation is to delineate key segments of the signal. In the --- -## PPG Characteristics +## PPG Characteristics * __Systolic Phase__: Reflects the contraction of the heart * __Diastolic Phase__: Reflects the relaxation of the heart @@ -43,7 +43,7 @@ The objective of segmentation is to delineate key segments of the signal. In the --- -## Dataloaders +## Dataloaders Dataloaders are available for the following datasets: @@ -54,7 +54,7 @@ Dataloaders are available for the following datasets: --- -## Pre-Trained Models +## Pre-Trained Models The following table provides the latest performance and accuracy results for segmentation models. Additional result details can be found in [Model Zoo → Segmentation](../zoo/index.md). @@ -62,7 +62,7 @@ The following table provides the latest performance and accuracy results for seg --- -## Target Classes +## Target Classes Below outlines the classes available for segmentation. When training a model, the number of classes, mapping, and names must be provided. This allows for the most flexibility in the segmentation task. diff --git a/docs/usage/cli.md b/docs/usage/cli.md index e88618d9..ff00d36d 100644 --- a/docs/usage/cli.md +++ b/docs/usage/cli.md @@ -1,11 +1,11 @@ -# :octicons-terminal-24: HeartKit CLI +# :octicons-terminal-24: heartKIT CLI
```console $ heartkit --help -HeartKit CLI Options: +heartKIT CLI Options: --task [segmentation, rhythm, beat, denoise] --mode [download, train, evaluate, export, demo] --config ["./path/to/config.json", or '{"raw: "json"}'] @@ -13,7 +13,7 @@ HeartKit CLI Options:
-The HeartKit command line interface (CLI) makes it easy to run a variety of single-line commands without the need for writing any code. You can run all built-in tasks and modes from the terminal with the `heartkit` command. This is also useful to reproduce [Model Zoo](../zoo/index.md) results. +The heartKIT command line interface (CLI) makes it easy to run a variety of single-line commands without the need for writing any code. You can run all built-in tasks and modes from the terminal with the `heartkit` command. This is also useful to reproduce [Model Zoo](../zoo/index.md) results. !!! example @@ -88,7 +88,7 @@ The [download](../modes/download.md) command is used to download all datasets sp ## [Train](../modes/train.md) -The [train](../modes/train.md) command is used to train a HeartKit model for the specified `task` and `dataset`. Each task provides a reference routine for training the model. The routine can be customized via the configuration file. Please refer to [HKTaskParams](../modes/configuration.md#hktaskparams) to see supported options. +The [train](../modes/train.md) command is used to train a heartKIT model for the specified `task` and `dataset`. Each task provides a reference routine for training the model. The routine can be customized via the configuration file. Please refer to [HKTaskParams](../modes/configuration.md#hktaskparams) to see supported options. !!! Example "CLI" diff --git a/docs/usage/python.md b/docs/usage/python.md index 4cb7dc02..d52d6da0 100644 --- a/docs/usage/python.md +++ b/docs/usage/python.md @@ -1,10 +1,10 @@ # :simple-python: Python Usage -__HeartKit__ python package allows for more fine-grained control and customization. You can use the package to train, evaluate, and deploy models for both built-in taks and custom tasks. In addition, custom datasets and model architectures can be created and registered with corresponding factories. +__heartKIT__ python package allows for more fine-grained control and customization. You can use the package to train, evaluate, and deploy models for both built-in taks and custom tasks. In addition, custom datasets and model architectures can be created and registered with corresponding factories. -## Overview +## Overview -The main components of HeartKit include the following: +The main components of heartKIT include the following: ### [Tasks](../tasks/index.md) @@ -28,7 +28,7 @@ ds = hk.DatasetFactory.get('ecg-synthetic')(num_pts=100) ### [Models](../models/index.md) -Lastly, HeartKit leverages [helia-edge's](https://ambiqai.github.io/helia-edge/) customizable model architectures. To enable creating custom network topologies from configuration files, HeartKit provides a `ModelFactory` that allows you to create models by specifying the model key and the model parameters. Each item in the factory is a callable that takes a `keras.Input`, model parameters, and number of classes as arguments and returns a `keras.Model`. +Lastly, heartKIT leverages [helia-edge's](https://ambiqai.github.io/helia-edge/) customizable model architectures. To enable creating custom network topologies from configuration files, heartKIT provides a `ModelFactory` that allows you to create models by specifying the model key and the model parameters. Each item in the factory is a callable that takes a `keras.Input`, model parameters, and number of classes as arguments and returns a `keras.Model`. ``` import keras @@ -46,7 +46,7 @@ model = hk.ModelFactory.get('tcn')( ``` -## Usage +## Usage ### Running a built-in task w/ existing datasets diff --git a/docs/zoo/arr-2-eff-sm.md b/docs/zoo/arr-2-eff-sm.md index b3f8f70e..af68feaa 100644 --- a/docs/zoo/arr-2-eff-sm.md +++ b/docs/zoo/arr-2-eff-sm.md @@ -1,7 +1,7 @@ # 2-Class Arrhythmia Classification (ARR-2-EFF-SM) -## Overview +## Overview The following table provides the latest pre-trained model for 2-class arrhythmia classification. Below we also provide additional details including training configuration, performance metrics, and downloads. @@ -9,14 +9,14 @@ The following table provides the latest pre-trained model for 2-class arrhythmia --- -## Input +## Input - **Sensor**: ECG - **Location**: Wrist - **Sampling Rate**: 100 Hz - **Frame Size**: 5 seconds -## Class Mapping +## Class Mapping The model is trained on raw ECG data and is able to discern normal sinus rhythm (NSR) from atrial fibrillation (AFIB) and atrial flutter (AFL). The class mapping is as follows: @@ -27,7 +27,7 @@ The model is trained on raw ECG data and is able to discern normal sinus rhythm | 7-AFIB, 8-AFL | 1 | AFIB | -## Datasets +## Datasets The model is trained on the following datasets: @@ -36,7 +36,7 @@ The model is trained on the following datasets: --- -## Model Performance +## Model Performance The confusion matrix on the test set for the model is depicted below. @@ -46,7 +46,7 @@ The confusion matrix on the test set for the model is depicted below. --- -## Downloads +## Downloads | Asset | Description | | -------------------------------------------------------------------- | ----------------------------- | diff --git a/docs/zoo/arr-4-eff-sm.md b/docs/zoo/arr-4-eff-sm.md index 700ed320..9e64ad10 100644 --- a/docs/zoo/arr-4-eff-sm.md +++ b/docs/zoo/arr-4-eff-sm.md @@ -1,6 +1,6 @@ # 4-Class Arrhythmia Classification (ARR-4-EFF-SM) -## Overview +## Overview The following table provides the latest pre-trained model for 4-class arrhythmia classification. Below we also provide additional details including training configuration, performance metrics, and downloads. @@ -8,7 +8,7 @@ The following table provides the latest pre-trained model for 4-class arrhythmia --- -## Input +## Input The model is trained on 5-second, raw ECG frames sampled at 100 Hz. @@ -19,7 +19,7 @@ The model is trained on 5-second, raw ECG frames sampled at 100 Hz. --- -## Class Mapping +## Class Mapping The model is trained on raw ECG data and is able to discern normal sinus rhythm (SR) from sinus bradycardia (SBRAD), atrial fibrillation (AFIB), atrial flutter (AFL), supraventricular tachycardia (STACH), and general supraventricular tachycardia (GSVT). The class mapping is as follows: @@ -32,7 +32,7 @@ The model is trained on raw ECG data and is able to discern normal sinus rhythm --- -## Datasets +## Datasets The model is trained on the following datasets: @@ -40,7 +40,7 @@ The model is trained on the following datasets: --- -## Model Performance +## Model Performance The confusion matrix for the model is depicted below. @@ -51,7 +51,7 @@ The confusion matrix for the model is depicted below. --- -## Downloads +## Downloads | Asset | Description | diff --git a/docs/zoo/beat-2-eff-sm.md b/docs/zoo/beat-2-eff-sm.md index 1513f461..9f464660 100644 --- a/docs/zoo/beat-2-eff-sm.md +++ b/docs/zoo/beat-2-eff-sm.md @@ -1,6 +1,6 @@ # 2-Class Beat Classification (BEAT-2-EFF-SM) -## Overview +## Overview The following table provides the latest pre-trained model for 2-class beat classification task. Below we also provide additional details including training configuration, performance metrics, and downloads. @@ -8,7 +8,7 @@ The following table provides the latest pre-trained model for 2-class beat class --- -## Input +## Input The model is trained on 5-second, raw ECG frames sampled at 100 Hz. @@ -19,7 +19,7 @@ The model is trained on 5-second, raw ECG frames sampled at 100 Hz. --- -## Class Mapping +## Class Mapping The model is able to classify normal sinus rhythm (NSR) and premature atrial/ventricular contractions (PAC/PVC). The class mapping is as follows: @@ -31,7 +31,7 @@ The class mapping is as follows: --- -## Datasets +## Datasets The model is trained on the following datasets: @@ -39,7 +39,7 @@ The model is trained on the following datasets: --- -## Model Performance +## Model Performance The confusion matrix for model is depicted below. @@ -48,7 +48,7 @@ The confusion matrix for model is depicted below.
-## Downloads +## Downloads | Asset | Description | | -------------------------------------------------------------------- | ----------------------------- | diff --git a/docs/zoo/beat-3-eff-sm.md b/docs/zoo/beat-3-eff-sm.md index 1409ec26..9901b9b4 100644 --- a/docs/zoo/beat-3-eff-sm.md +++ b/docs/zoo/beat-3-eff-sm.md @@ -1,6 +1,6 @@ # 3-Clas Beat Classification (BEAT-3-EFF-SM) -## Overview +## Overview The following table provides the latest pre-trained model for 3-class beat classification. Below we also provide additional details including training configuration, performance metrics, and downloads. @@ -8,7 +8,7 @@ The following table provides the latest pre-trained model for 3-class beat class --- -## Input +## Input The model is trained on 5-second, raw ECG frames sampled at 100 Hz. @@ -19,7 +19,7 @@ The model is trained on 5-second, raw ECG frames sampled at 100 Hz. --- -## Class Mapping +## Class Mapping The model is able to distinguish between normal sinus rhythm (NSR), premature/ectopic atrial contractions (PAC), and premature/ectopic ventricular contractions (PVC). The class mapping is as follows: @@ -31,7 +31,7 @@ The model is able to distinguish between normal sinus rhythm (NSR), premature/ec --- -## Dataset +## Dataset The model is trained on the following datasets: @@ -39,7 +39,7 @@ The model is trained on the following datasets: --- -## Model Performance +## Model Performance The confusion matrix for the model is depicted below. @@ -50,7 +50,7 @@ The confusion matrix for the model is depicted below. --- -## Downloads +## Downloads | Asset | Description | | -------------------------------------------------------------------- | ----------------------------- | diff --git a/docs/zoo/den-ppg-tcn-sm.md b/docs/zoo/den-ppg-tcn-sm.md index 4f68a71b..debacf9f 100644 --- a/docs/zoo/den-ppg-tcn-sm.md +++ b/docs/zoo/den-ppg-tcn-sm.md @@ -1,6 +1,6 @@ # PPG-Based Denoising (DEN-PPG-TCN-SM) -## Overview +## Overview The following table provides the latest pre-trained model for PPG-based denoising. Below we also provide additional details including training configuration, performance metrics, and downloads. @@ -8,7 +8,7 @@ The following table provides the latest pre-trained model for PPG-based denoisin --- -## Input +## Input The model is trained on 5-second, raw PPG frames sampled at 100 Hz. @@ -19,7 +19,7 @@ The model is trained on 5-second, raw PPG frames sampled at 100 Hz. --- -## Datasets +## Datasets The model is trained on synthetic PPG data. @@ -27,7 +27,7 @@ The model is trained on synthetic PPG data. --- -## Model Performance +## Model Performance The following table provides the performance metrics for the PPG denoising model. @@ -39,7 +39,7 @@ The following table provides the performance metrics for the PPG denoising model --- -## Downloads +## Downloads | Asset | Description | diff --git a/docs/zoo/den-tcn-lg.md b/docs/zoo/den-tcn-lg.md index 7e6b430d..fba71a37 100644 --- a/docs/zoo/den-tcn-lg.md +++ b/docs/zoo/den-tcn-lg.md @@ -1,6 +1,6 @@ # ECG_based Denoising (DEN-TCN-LG) -## Overview +## Overview The following table provides the latest pre-trained model for ECG-based denoising. Below we also provide additional details including training configuration, performance metrics, and downloads. @@ -8,7 +8,7 @@ The following table provides the latest pre-trained model for ECG-based denoisin --- -## Input +## Input The model is trained on 5-second, raw ECG frames sampled at 100 Hz. @@ -19,7 +19,7 @@ The model is trained on 5-second, raw ECG frames sampled at 100 Hz. --- -## Datasets +## Datasets The model is trained on the following datasets: @@ -28,7 +28,7 @@ The model is trained on the following datasets: --- -## Model Performance +## Model Performance The following table provides the performance metrics for the ECG-based denoising model. @@ -40,7 +40,7 @@ The following table provides the performance metrics for the ECG-based denoising --- -## Downloads +## Downloads | Asset | Description | diff --git a/docs/zoo/den-tcn-sm.md b/docs/zoo/den-tcn-sm.md index 40b0bbc9..3cc9290c 100644 --- a/docs/zoo/den-tcn-sm.md +++ b/docs/zoo/den-tcn-sm.md @@ -1,6 +1,6 @@ # ECG-Based Denoising (DEN-TCN-SM) -## Overview +## Overview The following table provides the latest pre-trained model for ECG-based denoising. Below we also provide additional details including training configuration, performance metrics, and downloads. @@ -9,7 +9,7 @@ The following table provides the latest pre-trained model for ECG-based denoisin --- -## Input +## Input The model is trained on 5-second, raw ECG frames sampled at 100 Hz. @@ -18,7 +18,7 @@ The model is trained on 5-second, raw ECG frames sampled at 100 Hz. - **Sampling Rate**: 100 Hz - **Frame Size**: 5 seconds -### Datasets +### Datasets The model is trained on the following datasets: @@ -27,7 +27,7 @@ The model is trained on the following datasets: --- -## Model Performance +## Model Performance The following table provides the performance metrics for the ECG-based denoising model. @@ -39,7 +39,7 @@ The following table provides the performance metrics for the ECG-based denoising --- -## Downloads +## Downloads | Asset | Description | diff --git a/docs/zoo/index.md b/docs/zoo/index.md index d7f00eb0..bc4cff5f 100644 --- a/docs/zoo/index.md +++ b/docs/zoo/index.md @@ -2,7 +2,7 @@ A number of pre-trained models are available for download to use in your own project. These models are trained on the datasets listed below and are available in Keras and TensorFlow Lite flatbuffer formats. -## [Signal Denoising Task](../tasks/denoise.md) +## [Signal Denoising Task](../tasks/denoise.md) The following table provides the latest performance and accuracy results for denoising models. @@ -13,7 +13,7 @@ The following table provides the latest performance and accuracy results for den | __DEN-PPG-TCN-SM__ | Synthetic | 100Hz | 2.5s | TCN | 3.5K | 1.1M | 92.1% COS | -## [Signal Segmentation Task](../tasks/segmentation.md) +## [Signal Segmentation Task](../tasks/segmentation.md) The following table provides the latest performance and accuracy results for ECG segmentation models. @@ -25,7 +25,7 @@ The following table provides the latest performance and accuracy results for ECG | __SEG-PPG-2-TCN-SM__ | Synthetic | 100Hz | 2.5s | 2 | TCN | 4K | 1.43M | 98.6% F1 | -## [Rhythm Classification Task](../tasks/rhythm.md) +## [Rhythm Classification Task](../tasks/rhythm.md) The following table provides the latest performance and accuracy results for rhythm classification models. @@ -35,7 +35,7 @@ The following table provides the latest performance and accuracy results for rhy | __ARR-4-EFF-SM__ | LSAD | 100Hz | 5s | 4 | EfficientNetV2 | 27K | 1.6M | 95.9% F1 | -## [Beat Classification Task](../tasks/beat.md) +## [Beat Classification Task](../tasks/beat.md) The following table provides the latest performance and accuracy results for beat classification models. @@ -45,7 +45,7 @@ The following table provides the latest performance and accuracy results for bea | __BC-3-EFF-SM__ | Icentia11k | 100Hz | 5s | 3 | EfficientNetV2 | 41K | 2.1M | 92.0% F1 | -## Reproducing Results +## Reproducing Results Each pre-trained model has a corresponding `configuration.json` file that can be used to reproduce the model and results. diff --git a/docs/zoo/seg-2-tcn-sm.md b/docs/zoo/seg-2-tcn-sm.md index 2c278305..57bf5db8 100644 --- a/docs/zoo/seg-2-tcn-sm.md +++ b/docs/zoo/seg-2-tcn-sm.md @@ -1,6 +1,6 @@ # 2-Stage ECG Segmentation (SEG-2-TCN-SM) -## Overview +## Overview The following table provides the latest pre-trained model for 2-stage ECG segmentation. Below we also provide additional details including training configuration, performance metrics, and downloads. @@ -8,7 +8,7 @@ The following table provides the latest pre-trained model for 2-stage ECG segmen --- -## Input +## Input The model is trained on 2.5-second, raw ECG frames sampled at 100 Hz. @@ -19,7 +19,7 @@ The model is trained on 2.5-second, raw ECG frames sampled at 100 Hz. --- -## Class Mapping +## Class Mapping The model is able to segment ECG signals into two classes: QRS complexes and none. The class mapping is as follows: @@ -30,7 +30,7 @@ The model is able to segment ECG signals into two classes: QRS complexes and non --- -## Datasets +## Datasets The model is trained on the following datasets: @@ -39,7 +39,7 @@ The model is trained on the following datasets: --- -## Model Performance +## Model Performance The confusion matrix for the model is depicted below. @@ -49,7 +49,7 @@ The confusion matrix for the model is depicted below. --- -## Downloads +## Downloads | Asset | Description | | -------------------------------------------------------------------- | ----------------------------- | diff --git a/docs/zoo/seg-4-tcn-lg.md b/docs/zoo/seg-4-tcn-lg.md index a93e272a..1fced5b7 100644 --- a/docs/zoo/seg-4-tcn-lg.md +++ b/docs/zoo/seg-4-tcn-lg.md @@ -1,6 +1,6 @@ # 4-Stage ECG Segmentation (SEG-4-TCN-LG) -## Overview +## Overview The following table provides the latest pre-trained model for 4-class ECG segmentation. Below we also provide additional details including training configuration, performance metrics, and downloads. @@ -8,7 +8,7 @@ The following table provides the latest pre-trained model for 4-class ECG segmen --- -### Input +### Input The model is trained on 2.5-second, raw ECG frames sampled at 100 Hz. @@ -19,7 +19,7 @@ The model is trained on 2.5-second, raw ECG frames sampled at 100 Hz. --- -### Class Mapping +### Class Mapping The model is able to segment ECG signals into four classes: P-wave, QRS complex, T-wave, and none. The class mapping is as follows: @@ -32,7 +32,7 @@ The model is able to segment ECG signals into four classes: P-wave, QRS complex, --- -### Datasets +### Datasets The model is trained on the following datasets: @@ -41,7 +41,7 @@ The model is trained on the following datasets: --- -## Model Performance +## Model Performance The confusion matrix for the segmentation model is depicted below. @@ -51,7 +51,7 @@ The confusion matrix for the segmentation model is depicted below. --- -## Downloads +## Downloads | Asset | Description | | -------------------------------------------------------------------- | ----------------------------- | diff --git a/docs/zoo/seg-4-tcn-sm.md b/docs/zoo/seg-4-tcn-sm.md index a366768f..9f336afa 100644 --- a/docs/zoo/seg-4-tcn-sm.md +++ b/docs/zoo/seg-4-tcn-sm.md @@ -1,6 +1,6 @@ # 4-Stage ECG Segmentation (SEG-4-TCN-SM) -## Overview +## Overview The following table provides the latest pre-trained model for 4-class ECG segmentation. Below we also provide additional details including training configuration, performance metrics, and downloads. @@ -8,7 +8,7 @@ The following table provides the latest pre-trained model for 4-class ECG segmen --- -## Input +## Input - **Sensor**: ECG - **Location**: Wrist @@ -17,7 +17,7 @@ The following table provides the latest pre-trained model for 4-class ECG segmen --- -## Class Mapping +## Class Mapping Identify each of the P-wave, QRS complex, and T-wave. @@ -30,7 +30,7 @@ Identify each of the P-wave, QRS complex, and T-wave. --- -## Datasets +## Datasets The model is trained on the following datasets: @@ -39,7 +39,7 @@ The model is trained on the following datasets: --- -## Model Performance +## Model Performance The confusion matrix for the segmentation model is depicted below. @@ -49,7 +49,7 @@ The confusion matrix for the segmentation model is depicted below. --- -## Downloads +## Downloads | Asset | Description | | -------------------------------------------------------------------- | ----------------------------- | diff --git a/docs/zoo/seg-ppg-2-tcn-sm.md b/docs/zoo/seg-ppg-2-tcn-sm.md index aa7c8eeb..f64b63c1 100644 --- a/docs/zoo/seg-ppg-2-tcn-sm.md +++ b/docs/zoo/seg-ppg-2-tcn-sm.md @@ -1,6 +1,6 @@ # 2-Stage PPG Segmentation (SEG-PPG-2-TCN-SM) -## Overview +## Overview The following table provides the latest pre-trained model for 2-stage PPG segmentation. Below we also provide additional details including training configuration, performance metrics, and downloads. @@ -8,7 +8,7 @@ The following table provides the latest pre-trained model for 2-stage PPG segmen --- -## Input +## Input The model is trained on 2.5-second, raw ECG frames sampled at 100 Hz. @@ -19,7 +19,7 @@ The model is trained on 2.5-second, raw ECG frames sampled at 100 Hz. --- -## Class Mapping +## Class Mapping The model is able to segment PPG Signals into systolic and diastolic phases. The class mapping is as follows: @@ -30,7 +30,7 @@ The model is able to segment PPG Signals into systolic and diastolic phases. The --- -## Datasets +## Datasets The model is trained on the following datasets: @@ -38,7 +38,7 @@ The model is trained on the following datasets: --- -## Model Performance +## Model Performance The confusion matrix for the model is depicted below. @@ -48,7 +48,7 @@ The confusion matrix for the model is depicted below. --- -## Downloads +## Downloads | Asset | Description | | -------------------------------------------------------------------- | ----------------------------- | diff --git a/heartkit/__init__.py b/heartkit/__init__.py index 99c4ca98..1257c212 100644 --- a/heartkit/__init__.py +++ b/heartkit/__init__.py @@ -1,9 +1,9 @@ """ -# HeartKit API +# heartKIT API -HeartKit is an AI Development Kit (ADK) that enables developers to easily train and deploy real-time __heart-monitoring__ models onto [Ambiq's family of ultra-low power SoCs](https://ambiq.com/soc/). +heartKIT is an AI Development Kit (ADK) that enables developers to easily train and deploy real-time __heart-monitoring__ models onto [Ambiq's family of ultra-low power SoCs](https://ambiq.com/soc/). The kit provides a variety of datasets, efficient model architectures, and heart-related tasks. -In addition, HeartKit provides optimization and deployment routines to generate efficient inference models. +In addition, heartKIT provides optimization and deployment routines to generate efficient inference models. Finally, the kit includes a number of pre-trained models and task-level demos to showcase the capabilities. """ diff --git a/heartkit/cli.py b/heartkit/cli.py index 539a627c..14a53640 100644 --- a/heartkit/cli.py +++ b/heartkit/cli.py @@ -1,12 +1,12 @@ """ -# :octicons-terminal-24: HeartKit CLI API +# :octicons-terminal-24: heartKIT CLI API -The HeartKit CLI provides a command-line interface to interact with the HeartKit library. +The heartKIT CLI provides a command-line interface to interact with the heartKIT library. ```bash $ heartkit --help -HeartKit CLI Options: +heartKIT CLI Options: --task [segmentation, rhythm, beat, denoise] --mode [download, feature, train, evaluate, export, demo] --config ["./path/to/config.json", or '{"raw: "json"}'] @@ -54,7 +54,7 @@ def run( task: str = ArgField("-t", description="Task", default="rhythm"), config: str = ArgField("-c", description="File path or JSON content", default="{}"), ): - """HeartKit CLI entry point. + """heartKIT CLI entry point. Args: mode (HKMode, optional): Mode. Defaults to HKMode.train. diff --git a/heartkit/datasets/__init__.py b/heartkit/datasets/__init__.py index 83d5d9a8..6f054cd5 100644 --- a/heartkit/datasets/__init__.py +++ b/heartkit/datasets/__init__.py @@ -1,7 +1,7 @@ """ # :material-database: Datasets API -HeartKit provides a number of datasets that can be used for training and evaluation of __heart-monitoring tasks__. +heartKIT provides a number of datasets that can be used for training and evaluation of __heart-monitoring tasks__. ## Available Datasets @@ -10,8 +10,8 @@ * **[LUDB](./ludb)**: Lobachevsky University Electrocardiography database consists of 200 10-second 12-lead records. The boundaries and peaks of P, T waves and QRS complexes were manually annotated by cardiologists. Each record is annotated with the corresponding diagnosis. * **[PTB-XL](./ptbxl)**: The PTB-XL is a large publicly available electrocardiography dataset. It contains 21837 clinical 12-lead ECGs from 18885 patients of 10 second length. The ECGs are sampled at 500 Hz and are annotated by up to two cardiologists. * **[QTDB](./qtdb)**: Over 100 fifteen-minute two-lead ECG recordings with onset, peak, and end markers for P, QRS, T, and (where present) U waves of from 30 to 50 selected beats in each recording. -* **[ECG Synthetic](./ppg_synthetic)**: An ECG synthetic dataset generated using PhysioKit. The dataset enables the generation of 12-lead ECG signals with a variety of heart conditions and noise levels along with segmentations and fiducial points. -* **[PPG Synthetic](./ecg_synthetic)**: A PPG synthetic dataset generated using PhysioKit. The dataset enables the generation of a 1-lead PPG signal with segmentations and fiducials. +* **[ECG Synthetic](./ppg_synthetic)**: An ECG synthetic dataset generated using physioKIT. The dataset enables the generation of 12-lead ECG signals with a variety of heart conditions and noise levels along with segmentations and fiducial points. +* **[PPG Synthetic](./ecg_synthetic)**: A PPG synthetic dataset generated using physioKIT. The dataset enables the generation of a 1-lead PPG signal with segmentations and fiducials. ## Dataset Factory diff --git a/heartkit/datasets/ecg_synthetic.py b/heartkit/datasets/ecg_synthetic.py index b385584b..286dac91 100644 --- a/heartkit/datasets/ecg_synthetic.py +++ b/heartkit/datasets/ecg_synthetic.py @@ -58,7 +58,7 @@ def __init__( path: str = Path(tempfile.gettempdir()) / "ecg-synthetic", **kwargs, ) -> None: - """ECG synthetic dataset creates 12-lead ECG signals using PhysioKit. + """ECG synthetic dataset creates 12-lead ECG signals using physioKIT. Args: num_pts (int, optional): Number of patients. Defaults to 250. diff --git a/heartkit/datasets/ppg_synthetic.py b/heartkit/datasets/ppg_synthetic.py index b2299f5d..eefca149 100644 --- a/heartkit/datasets/ppg_synthetic.py +++ b/heartkit/datasets/ppg_synthetic.py @@ -37,7 +37,7 @@ def __init__( path: str = Path(tempfile.gettempdir()) / "ppg-synthetic", **kwargs, ) -> None: - """PPG synthetic dataset creates 1-lead PPG signal using PhysioKit. + """PPG synthetic dataset creates 1-lead PPG signal using physioKIT. Args: num_pts (int, optional): Number of patients. Defaults to 250. diff --git a/heartkit/defines.py b/heartkit/defines.py index 2b17705f..20561bb1 100644 --- a/heartkit/defines.py +++ b/heartkit/defines.py @@ -45,7 +45,7 @@ class NamedParams(BaseModel, extra="allow"): class HKMode(StrEnum): - """HeartKit task mode""" + """heartKIT task mode""" download = "download" train = "train" diff --git a/heartkit/models/__init__.py b/heartkit/models/__init__.py index cdf03c9b..58b734fc 100644 --- a/heartkit/models/__init__.py +++ b/heartkit/models/__init__.py @@ -1,9 +1,9 @@ """ # :material-graph: Models API -HeartKit provides a number of model architectures that can be used for training __heart-monitoring tasks__. +heartKIT provides a number of model architectures that can be used for training __heart-monitoring tasks__. While a number of off-the-shelf models exist, they are often not efficient nor optimized for real-time, edge applications. -To address this, HeartKit provides a model factory that allows you to easily create and train customized models via [helia-edge](https://ambiqai.github.io/helia-edge/). +To address this, heartKIT provides a model factory that allows you to easily create and train customized models via [helia-edge](https://ambiqai.github.io/helia-edge/). `helia-edge` includes a growing number of state-of-the-art models that can be easily configured and trained using high-level parameters. The models are designed to be efficient and well-suited for real-time, edge applications. Most of the models are based on state-of-the-art architectures that have been modified to allow for more fine-grain customization. diff --git a/heartkit/tasks/__init__.py b/heartkit/tasks/__init__.py index c023da2f..d45c960f 100644 --- a/heartkit/tasks/__init__.py +++ b/heartkit/tasks/__init__.py @@ -1,7 +1,7 @@ """ # :simple-task: Tasks API -HeartKit provides several built-in __heart-monitoring__ tasks. +heartKIT provides several built-in __heart-monitoring__ tasks. Each task is designed to address a unique aspect such as ECG denoising, segmentation, and rhythm/beat classification. The tasks are designed to be modular and can be used independently or in combination to address specific use cases. diff --git a/heartkit/tasks/beat/__init__.py b/heartkit/tasks/beat/__init__.py index 41780109..112cfa37 100644 --- a/heartkit/tasks/beat/__init__.py +++ b/heartkit/tasks/beat/__init__.py @@ -20,7 +20,7 @@ class BeatTask(HKTask): - """HeartKit Beat Task""" + """heartKIT Beat Task""" @staticmethod def description() -> str: diff --git a/heartkit/tasks/beat/demo.py b/heartkit/tasks/beat/demo.py index 1705cccf..565934d1 100644 --- a/heartkit/tasks/beat/demo.py +++ b/heartkit/tasks/beat/demo.py @@ -301,7 +301,7 @@ def demo(params: HKTaskParams): paper_bgcolor=bg_color, margin=dict(l=10, r=10, t=80, b=80), legend=dict(groupclick="toggleitem"), - title="HeartKit: Beat Demo", + title="heartKIT: Beat Demo", ) fig.write_html(params.job_dir / "demo.html", include_plotlyjs="cdn", full_html=True) diff --git a/heartkit/tasks/denoise/__init__.py b/heartkit/tasks/denoise/__init__.py index 31dcacd5..ae787f7d 100644 --- a/heartkit/tasks/denoise/__init__.py +++ b/heartkit/tasks/denoise/__init__.py @@ -21,7 +21,7 @@ class DenoiseTask(HKTask): - """HeartKit Denoise Task""" + """heartKIT Denoise Task""" @staticmethod def train(params: HKTaskParams): diff --git a/heartkit/tasks/denoise/demo.py b/heartkit/tasks/denoise/demo.py index f8ca10ab..79fcc720 100644 --- a/heartkit/tasks/denoise/demo.py +++ b/heartkit/tasks/denoise/demo.py @@ -184,7 +184,7 @@ def demo(params: HKTaskParams): plot_bgcolor=plot_theme.bg_color, paper_bgcolor=plot_theme.bg_color, margin=dict(l=10, r=10, t=80, b=60), - title="HeartKit: Denoising Demo", + title="heartKIT: Denoising Demo", ) fig.write_html(params.job_dir / "demo.html", include_plotlyjs="cdn", full_html=False) diff --git a/heartkit/tasks/diagnostic/__init__.py b/heartkit/tasks/diagnostic/__init__.py index 4b95af5a..1064d5e4 100644 --- a/heartkit/tasks/diagnostic/__init__.py +++ b/heartkit/tasks/diagnostic/__init__.py @@ -18,7 +18,7 @@ class DiagnosticTask(HKTask): - """HeartKit Diagnostic Task""" + """heartKIT Diagnostic Task""" @staticmethod def train(params: HKTaskParams): diff --git a/heartkit/tasks/diagnostic/defines.py b/heartkit/tasks/diagnostic/defines.py index ba52c62f..892dabb2 100644 --- a/heartkit/tasks/diagnostic/defines.py +++ b/heartkit/tasks/diagnostic/defines.py @@ -2,7 +2,7 @@ class HKDiagnostic(IntEnum): - """HeartKit Diagnostic classes""" + """heartKIT Diagnostic classes""" NORM = 0 STTC = 1 diff --git a/heartkit/tasks/diagnostic/demo.py b/heartkit/tasks/diagnostic/demo.py index e20f965a..4419aa8e 100644 --- a/heartkit/tasks/diagnostic/demo.py +++ b/heartkit/tasks/diagnostic/demo.py @@ -131,7 +131,7 @@ def demo(params: HKTaskParams): paper_bgcolor=bg_color, margin=dict(l=10, r=10, t=80, b=80), legend=dict(groupclick="toggleitem"), - title="HeartKit: Diagnostic Demo", + title="heartKIT: Diagnostic Demo", ) fig.write_html(params.job_dir / "demo.html", include_plotlyjs="cdn", full_html=True) diff --git a/heartkit/tasks/foundation/__init__.py b/heartkit/tasks/foundation/__init__.py index 91858299..a6fa4569 100644 --- a/heartkit/tasks/foundation/__init__.py +++ b/heartkit/tasks/foundation/__init__.py @@ -2,7 +2,7 @@ # Foundation Task API The objective of this task is to create a foundation model that can be used to build downstream models for other tasks. -In HeartKit, the foundation model is trained using SimCLR- using two augmented leads as input. +In heartKIT, the foundation model is trained using SimCLR- using two augmented leads as input. Classes: FoundationTask: Foundation task @@ -20,7 +20,7 @@ class FoundationTask(HKTask): - """HeartKit Foundation Task""" + """heartKIT Foundation Task""" @staticmethod def train(params: HKTaskParams): diff --git a/heartkit/tasks/foundation/demo.py b/heartkit/tasks/foundation/demo.py index 1f7373e3..7f62b2b2 100644 --- a/heartkit/tasks/foundation/demo.py +++ b/heartkit/tasks/foundation/demo.py @@ -141,7 +141,7 @@ def cossim(x, y): paper_bgcolor=plot_theme.bg_color, margin=dict(l=10, r=10, t=80, b=80), legend=dict(groupclick="toggleitem"), - title="HeartKit: Foundation Demo", + title="heartKIT: Foundation Demo", ) fig.write_html(params.job_dir / "demo.html", include_plotlyjs="cdn", full_html=True) logger.debug(f"Report saved to {params.job_dir / 'demo.html'}") diff --git a/heartkit/tasks/rhythm/__init__.py b/heartkit/tasks/rhythm/__init__.py index 44eadc7a..351fc6b1 100644 --- a/heartkit/tasks/rhythm/__init__.py +++ b/heartkit/tasks/rhythm/__init__.py @@ -18,7 +18,7 @@ class RhythmTask(HKTask): - """HeartKit Rhythm Task""" + """heartKIT Rhythm Task""" @staticmethod def description() -> str: diff --git a/heartkit/tasks/rhythm/demo.py b/heartkit/tasks/rhythm/demo.py index eb14aa1b..2d703595 100644 --- a/heartkit/tasks/rhythm/demo.py +++ b/heartkit/tasks/rhythm/demo.py @@ -133,7 +133,7 @@ def demo(params: HKTaskParams): paper_bgcolor=plot_theme.bg_color, margin=dict(l=10, r=10, t=80, b=80), legend=dict(groupclick="toggleitem"), - title="HeartKit: Rhythm Demo", + title="heartKIT: Rhythm Demo", ) fig.write_html(params.job_dir / "demo.html", include_plotlyjs="cdn", full_html=False) logger.debug(f"Report saved to {params.job_dir / 'demo.html'}") @@ -151,7 +151,7 @@ def demo(params: HKTaskParams): label = f"{class_names[pred]} ({prob:0.0%})" color = plot_theme.colors[pred % len(plot_theme.colors)] ax.axvspan(ts[start], ts[stop], color=color, alpha=0.25, label=label) - ax.set_title("HeartKit: Rhythm Demo") + ax.set_title("heartKIT: Rhythm Demo") ax.set_xlabel("Time (sec)") ax.set_ylabel("ECG") ax.legend(loc="upper right", bbox_to_anchor=(1, 1), frameon=False) diff --git a/heartkit/tasks/segmentation/__init__.py b/heartkit/tasks/segmentation/__init__.py index c35c112d..94bcf334 100644 --- a/heartkit/tasks/segmentation/__init__.py +++ b/heartkit/tasks/segmentation/__init__.py @@ -22,7 +22,7 @@ class SegmentationTask(HKTask): - """HeartKit Segmentation Task""" + """heartKIT Segmentation Task""" @staticmethod def train(params: HKTaskParams): diff --git a/heartkit/tasks/segmentation/demo.py b/heartkit/tasks/segmentation/demo.py index de03e645..3f88cf72 100644 --- a/heartkit/tasks/segmentation/demo.py +++ b/heartkit/tasks/segmentation/demo.py @@ -270,7 +270,7 @@ def demo(params: HKTaskParams): plot_bgcolor=plot_theme.bg_color, paper_bgcolor=plot_theme.bg_color, margin=dict(l=10, r=10, t=80, b=80), - title="HeartKit: Segmentation Demo", + title="heartKIT: Segmentation Demo", ) fig.write_html(params.job_dir / "demo.html", include_plotlyjs="cdn", full_html=False) diff --git a/heartkit/tasks/task.py b/heartkit/tasks/task.py index 94959c57..4bd3e2c4 100644 --- a/heartkit/tasks/task.py +++ b/heartkit/tasks/task.py @@ -8,7 +8,7 @@ class HKTask(abc.ABC): - """HeartKit Task base class. All tasks should inherit from this class.""" + """heartKIT Task base class. All tasks should inherit from this class.""" @staticmethod def description() -> str: diff --git a/heartkit/tasks/translate/__init__.py b/heartkit/tasks/translate/__init__.py index 99714fce..5291bb73 100644 --- a/heartkit/tasks/translate/__init__.py +++ b/heartkit/tasks/translate/__init__.py @@ -19,7 +19,7 @@ class TranslateTask(HKTask): - """HeartKit Translate Task""" + """heartKIT Translate Task""" @staticmethod def train(params: HKTaskParams): diff --git a/heartkit/tasks/translate/demo.py b/heartkit/tasks/translate/demo.py index e92315db..c9d52628 100644 --- a/heartkit/tasks/translate/demo.py +++ b/heartkit/tasks/translate/demo.py @@ -186,7 +186,7 @@ def demo(params: HKTaskParams): plot_bgcolor=bg_color, paper_bgcolor=bg_color, margin=dict(l=10, r=10, t=80, b=60), - title="HeartKit: Translate Demo", + title="heartKIT: Translate Demo", ) fig.write_html(params.job_dir / "demo.html", include_plotlyjs="cdn", full_html=False) diff --git a/heartkit/utils/__init__.py b/heartkit/utils/__init__.py index 24fd2d90..058cba34 100644 --- a/heartkit/utils/__init__.py +++ b/heartkit/utils/__init__.py @@ -1,5 +1,5 @@ """ -# :material-tools: HeartKit Utilities API +# :material-tools: heartKIT Utilities API """ diff --git a/mkdocs.yml b/mkdocs.yml index 71943ced..d7090599 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,7 @@ -site_name: HeartKit +site_name: heartKIT site_dir: "site" site_url: "https://ambiqai.github.io/heartkit" -site_description: HeartKit, AI Development Kit for AI heart monitoring on the edge +site_description: heartKIT, AI Development Kit for AI heart monitoring on the edge repo_name: AmbiqAI/hearkit repo_url: https://github.com/AmbiqAI/heartkit copyright: Copyright © 2023 Ambiq @@ -114,21 +114,21 @@ theme: code: Roboto Mono palette: - media: "(prefers-color-scheme)" - primary: blue + primary: red accent: indigo toggle: icon: material/brightness-auto name: Use system theme - media: "(prefers-color-scheme: light)" scheme: default - primary: blue + primary: red accent: indigo toggle: icon: material/brightness-7 name: Switch to light theme - media: "(prefers-color-scheme: dark)" scheme: slate - primary: blue + primary: red accent: indigo toggle: icon: material/brightness-4 diff --git a/notebooks/byot.ipynb b/notebooks/byot.ipynb index 9ec05f58..085a4310 100644 --- a/notebooks/byot.ipynb +++ b/notebooks/byot.ipynb @@ -25,7 +25,7 @@ "\n", "__Last Modified:__ 2024/08/15 \n", "\n", - "__Description:__ Create custom task for HeartKit end-to-end\n", + "__Description:__ Create custom task for heartKIT end-to-end\n", "\n", "## Overview \n", "\n", @@ -102,7 +102,7 @@ "\n", "We will create a dataloader class for the dataset __PTB-XL__ since it provides heart beat locations via `blabels`. \n", "\n", - "Given a raw ECG signal, we will compute the heart rate given the beat locations in the frame. The rate will be calculated based on the RR intervals using PhysioKit. The output will be the ecg signal and the heart rate in beats per second.\n" + "Given a raw ECG signal, we will compute the heart rate given the beat locations in the frame. The rate will be calculated based on the RR intervals using physioKIT. The output will be the ecg signal and the heart rate in beats per second.\n" ] }, { @@ -1047,7 +1047,7 @@ ], "metadata": { "kernelspec": { - "display_name": ".venv", + "display_name": "heartkit", "language": "python", "name": "python3" }, @@ -1061,7 +1061,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.12" + "version": "3.13.9" } }, "nbformat": 4, diff --git a/notebooks/train-arrhythmia-model.ipynb b/notebooks/train-arrhythmia-model.ipynb index f3cc56ce..b88eafd8 100644 --- a/notebooks/train-arrhythmia-model.ipynb +++ b/notebooks/train-arrhythmia-model.ipynb @@ -111,7 +111,7 @@ "source": [ "## Configure datasets\n", "\n", - "We are going to train our model using the [Large scale Arrhythmia dataset](https://ambiqai.github.io/heartkit/datasets/lsad/). This dataset uses the slug __lsad__ within HeartKit. We will download the dataset if it is not already available." + "We are going to train our model using the [Large scale Arrhythmia dataset](https://ambiqai.github.io/heartkit/datasets/lsad/). This dataset uses the slug __lsad__ within heartKIT. We will download the dataset if it is not already available." ] }, { @@ -143,7 +143,7 @@ "* Atrial Flutter/Fibrillation: Irregular heart rate (AFIB) \n", "* General Supra-Ventricular Tachycardia: Fast heart rate (GSVT)\n", "\n", - "HeartKit already provides a number of heart rhythms. We will provide a class mapping for the four classes we are interested in. We will also provide class names for display purposes." + "heartKIT already provides a number of heart rhythms. We will provide a class mapping for the four classes we are interested in. We will also provide class names for display purposes." ] }, { @@ -295,7 +295,7 @@ "source": [ "## Load rhythm task \n", "\n", - "HeartKit provides a __TaskFactory__ that includes a number ready-to-use tasks. Each task provides methods for training, evaluating, exporting, and demoing. We will grab the __rhythm__ task and configure it for our use case." + "heartKIT provides a __TaskFactory__ that includes a number ready-to-use tasks. Each task provides methods for training, evaluating, exporting, and demoing. We will grab the __rhythm__ task and configure it for our use case." ] }, { @@ -895,7 +895,7 @@ ], "metadata": { "kernelspec": { - "display_name": ".venv", + "display_name": "heartkit", "language": "python", "name": "python3" }, @@ -909,7 +909,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.12" + "version": "3.13.9" } }, "nbformat": 4, diff --git a/notebooks/train-ecg-denoiser.ipynb b/notebooks/train-ecg-denoiser.ipynb index d53e5495..0bba07d9 100644 --- a/notebooks/train-ecg-denoiser.ipynb +++ b/notebooks/train-ecg-denoiser.ipynb @@ -47,7 +47,7 @@ "\n", "__Datasets__\n", "\n", - "- **[Synthetic](https://ambiqai.github.io/heartkit/datasets/synthetic/)**: Synthetic ECG signals from PhysioKit\n", + "- **[Synthetic](https://ambiqai.github.io/heartkit/datasets/synthetic/)**: Synthetic ECG signals from physioKIT\n", "- **[PTB-XL](https://ambiqai.github.io/heartkit/datasets/ptbxl/)**: The PTB-XL is a large publicly available electrocardiography dataset. \n", "It contains 21837 clinical 12-lead ECGs from 18885 patients of 10 second length. The ECGs are sampled at 500 Hz and are annotated by up to two cardiologists.\n" ] @@ -196,7 +196,7 @@ "source": [ "## Configure datasets\n", "\n", - "Capturing noise-free ECG signals is challenging due to the presence of various artifacts. Therefore, we use a combination of synthetic and controlled, real-world datasets as our training data. HeartKit exposes an ECG Synthetic dataset generator provided by PhysioKit. \n" + "Capturing noise-free ECG signals is challenging due to the presence of various artifacts. Therefore, we use a combination of synthetic and controlled, real-world datasets as our training data. heartKIT exposes an ECG Synthetic dataset generator provided by physioKIT. \n" ] }, { @@ -308,7 +308,7 @@ "source": [ "## Load denoise task \n", "\n", - "HeartKit provides a __TaskFactory__ that includes a number ready-to-use tasks. Each task provides methods for training, evaluating, exporting, and demoing. We will grab the __denoise__ task and configure it for our use case." + "heartKIT provides a __TaskFactory__ that includes a number ready-to-use tasks. Each task provides methods for training, evaluating, exporting, and demoing. We will grab the __denoise__ task and configure it for our use case." ] }, { @@ -1023,7 +1023,7 @@ ], "metadata": { "kernelspec": { - "display_name": ".venv", + "display_name": "heartkit", "language": "python", "name": "python3" }, @@ -1037,7 +1037,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.5" + "version": "3.13.9" } }, "nbformat": 4, diff --git a/notebooks/train-ecg-segmentation.ipynb b/notebooks/train-ecg-segmentation.ipynb index 3a396cdc..f3efbd51 100644 --- a/notebooks/train-ecg-segmentation.ipynb +++ b/notebooks/train-ecg-segmentation.ipynb @@ -57,7 +57,7 @@ "\n", "__Datasets__\n", "\n", - "- **[Synthetic](https://ambiqai.github.io/heartkit/datasets/synthetic/)**: Synthetic ECG signals from PhysioKit\n", + "- **[Synthetic](https://ambiqai.github.io/heartkit/datasets/synthetic/)**: Synthetic ECG signals from physioKIT\n", "- **[LUDB](https://ambiqai.github.io/heartkit/datasets/ludb/)**: Lobachevsky University Electrocardiography database consists of 200 10-second 12-lead records. The boundaries and peaks of P, T waves and QRS complexes were manually annotated by cardiologists. Each record is annotated with the corresponding diagnosis.\n", "\n" ] @@ -120,7 +120,7 @@ "source": [ "## Target datasets\n", "\n", - "The only real-world public dataset containing ECG signals with annotated segments is the [LUDB dataset](https://ambiqai.github.io/heartkit/datasets/ludb/). We will use this dataset to train our model. In addition, we will leverage the synthetic dataset provided by PhysioKit to increase amount of data to train on. We will apply several augmentation techniques to the synthetic dataset to increase the diversity of the data. \n", + "The only real-world public dataset containing ECG signals with annotated segments is the [LUDB dataset](https://ambiqai.github.io/heartkit/datasets/ludb/). We will use this dataset to train our model. In addition, we will leverage the synthetic dataset provided by physioKIT to increase amount of data to train on. We will apply several augmentation techniques to the synthetic dataset to increase the diversity of the data. \n", "\n" ] }, @@ -400,7 +400,7 @@ "source": [ "## Load segmentation task \n", "\n", - "HeartKit provides a __TaskFactory__ that includes a number ready-to-use tasks. Each task provides methods for training, evaluating, exporting, and demoing. We will grab the __segmentation__ task and configure it for our use case." + "heartKIT provides a __TaskFactory__ that includes a number ready-to-use tasks. Each task provides methods for training, evaluating, exporting, and demoing. We will grab the __segmentation__ task and configure it for our use case." ] }, { @@ -1114,7 +1114,7 @@ ], "metadata": { "kernelspec": { - "display_name": ".venv", + "display_name": "heartkit", "language": "python", "name": "python3" }, @@ -1128,7 +1128,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.12" + "version": "3.13.9" } }, "nbformat": 4, diff --git a/uv.lock b/uv.lock index f1d4d178..95c15b1b 100644 --- a/uv.lock +++ b/uv.lock @@ -1064,7 +1064,7 @@ wheels = [ [[package]] name = "heartkit" -version = "1.6.0" +version = "1.7.0" source = { editable = "." } dependencies = [ { name = "argdantic", extra = ["all"] },