Skip to content

Home

HeartKit

Documentation: https://ambiqai.github.io/heartkit

Source Code: https://github.com/AmbiqAI/heartkit

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

Please explore the HeartKit Docs, a comprehensive resource designed to help you understand and utilize all the built-in features and capabilities.

Getting Started

Installation

To get started, first install the python package heartkit along with its dependencies via Git or PyPi:


$ pip install heartkit

---> 100%



$ git clone https://github.com/AmbiqAI/heartkit.git
Cloning into 'heartkit'...
Resolving deltas: 100% (3491/3491), done.
$ cd heartkit
$ poetry install

---> 100%

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 to quickly get up and running in minutes.

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 highly flexibile configuration files/objects. Additionally, new tasks can be added to the HeartKit framework by defining a new Task class and registering it to the Task Factory.

  • Denoise: Remove noise and artifacts from signals
  • Segmentation: Perform ECG/PPG based segmentation
  • Rhythm: Heart rhythm classification (AFIB, AFL)
  • Beat: Beat-level classification (NORM, PAC, PVC, NOISE)

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 a Task. Each mode is accompanied by a set of task parameters that can be customized to fit the user's needs.

  • Download: Download specified datasets
  • Train: Train a model for specified task and datasets
  • Evaluate: Evaluate a model for specified task and datasets
  • Export: Export a trained model to TensorFlow Lite and TFLM
  • Demo: Run task-level demo on PC or remotely on Ambiq EVB

Datasets

The ADK includes several built-in datasets 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 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. Check out the Datasets Guide to learn more about the available datasets along with their corresponding licenses and limitations.

  • 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 provided by PhysioKit.
  • Bring-Your-Own-Dataset (BYOD): Add and register new datasets to the framework.

Models

HeartKit provides a variety of model architectures geared towards efficient, real-time edge applications. These models are provided by Ambiq's neuralspot-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, to register current models as well as allow new custom architectures to be added. Check out the Models Guide to learn more about the available network architectures and model factory.

  • TCN: A CNN leveraging dilated convolutions (key=tcn)
  • U-Net: A CNN with encoder-decoder architecture for segmentation tasks (key=unet)
  • U-NeXt: A U-Net variant leveraging MBConv blocks (key=unext)
  • EfficientNetV2: A CNN leveraging MBConv blocks (key=efficientnet)
  • MobileOne: A CNN aimed at sub-1ms inference (key=mobileone)
  • ResNet: A popular CNN often used for vision tasks (key=resnet)
  • Conformer: A transformer composed of both convolutional and self-attention blocks (key=conformer)
  • MetaFormer: A transformer composed of both spatial mixing and channel mixing blocks (key=metaformer)
  • TSMixer: An All-MLP Architecture for Time Series Classification (key=tsmixer)
  • Bring-Your-Own-Model (BYOM): Register new SoTA model architectures w/ custom configurations

Model Zoo

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 to learn more about the available models and their corresponding performance metrics.

Guides

Checkout the 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 capabilities provided by HeartKit.