Task-Level Demo

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:

1. Load the configuration data (e.g. configuration.json)
2. Load the desired datasets (e.g. icentia11k)
3. Load the trained model (e.g. model.keras)
4. Initialize inference engine backend (e.g. pc or evb)
5. Generate input data (e.g. x, y)
6. Perform inference on backend (e.g. model.predict)
7. Generate report (e.g. report.html)

graph LR
A("`Load
configuration
__HKTaskParams__
`")
B("`Load
datasets
__DatasetFactory__
`")
C("`Load trained
__model__
`")
D("`Initialize
inference engine
__BackendFactory__
`")
E("`Generate
input stimulus
`")
F("`Perform
__inference(s)__
`")
G("`Generate
__report__
`")
A ==> B
B ==> C
C ==> D
subgraph CF["Inference Engine"]
    D ==> E
    E ==> F
end
F ==> G

---

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.

PC Backend Inference Engine

The PC backend is used to run the task-level demo on the local machine via Keras. This is useful for quick testing and debugging of the model.

1. Create / modify configuration file (e.g. configuration.json)
2. Ensure "pc" is selected as the backend in configuration file.
3. Run demo heartkit --mode demo --task segmentation --config ./configuration.json
4. HTML report will be saved to ${job_dir}/report.html

EVB Backend Inference Engine

The EVB backend is used to run the task-level demo on an Ambiq EVB. This is useful to showcase the model's performance in real-time and to verify its accuracy on deployed hardware.

1. Create / modify configuration file (e.g. configuration.json)
2. Ensure "evb" is selected as the backend in configuration file.
3. Plug EVB into PC via two USB-C cables.
4. Run demo heartkit --mode demo --task beat --config ./configuration.json
5. HTML report will be saved to ${job_dir}/report.html

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.

How it Works

1. Create a Backend: Define a new backend class that inherits from the HKInferenceBackend base class and implements the required abstract methods.

   import heartkit as hk
   
   class CustomBackend(hk.HKInferenceBackend):
       """Custom backend inference engine"""
   
       def __init__(self, params: hk.HKTaskParams) -> None:
           self.params = params
   
       def open(self):
           """Open backend"""
           pass
   
       def close(self):
           """Close backend"""
           pass
   
       def set_inputs(self, inputs: npt.NDArray):
           """Set inputs"""
           pass
   
       def perform_inference(self):
           """Perform inference"""
           pass
   
       def get_outputs(self) -> npt.NDArray:
           """Get outputs"""
           pass
   

2. Register the Backend: Register the new backend with the BackendFactory by calling the register method. This method takes the backend name and the backend class as arguments.

   import heartkit as hk
   
   # Register the custom backend
   hk.BackendFactory.register("custom", CustomBackend)
   

3. Use the Backend: The new backend can now be used by setting the backend flag in the demo configuration settings.

   import heartkit as hk
   
   # Define demo parameters
   params = hk.HKTaskParams(...)
   params.backend = "custom"
   
   # Load the desired task
   task = hk.TaskFactory.get("rhythm")
   
   # Run the task-level demo using the custom backend
   task.demo(params=params)
   

---

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- a toolkit to process raw ambulatory bio-signals.

CLIPython

heartkit -m export -t segmentation -c ./configuration.json

from pathlib import Path
import heartkit as hk

task = hk.TaskFactory.get("segmentation")
task.export(hk.HKTaskParams(
    job_dir=Path("./results/segmentation-class-2"),
    datasets=[hk.NamedParams(
        name="icentia11k",
        params=dict(
            path=Path("./datasets/icentia11k")
        )
    )],
    num_classes=2,
    class_map={
        0: 0,
        1: 1,
        2: 1
    },
    class_names=[
        "NONE", "AFIB/AFL"
    ],
    sampling_rate=100,
    frame_size=256,
    backend="pc",
    model_file=Path("./results/segmentation-class-2/model.keras"),
))

---

Arguments

Please refer to HKTaskParams for the list of arguments that can be used with the demo command.

---