Skip to content

Quickstart

Install SleepKit

We provide several installation methods including pip, poetry, and Docker. Install SleepKit via pip/poetry for the latest stable release or by cloning the GitHub repo for the most up-to-date. Additionally, a VSCode Dev Container is available and defined in ./.devcontainer to run in an isolated Docker environment.

Install

Clone the repository if you are interested in contributing to the development or wish to experiment with the latest source code. After cloning, navigate into the directory and install the package. In this mode, Poetry is recommended.

# Clone the repository
git clone https://github.com/AmbiqAI/sleepkit.git

# Navigate to the cloned directory
cd sleepkit

# Install the package in editable mode for development
poetry install

When using editable mode via Poetry, be sure to activate the python environment: poetry shell.
On Windows using Powershell, use .venv\Scripts\activate.ps1.

Install the SleepKit package using pip or Poetry. Visit the Python Package Index (PyPI) for more details on the package: https://pypi.org/project/sleepkit/

# Install with pip
pip install sleepkit

Or, if you prefer to use Poetry, you can install the package with the following command:

# Install with poetry
poetry add sleepkit

Alternatively, you can install the latest development version directly from the GitHub repository. Make sure to have the Git command-line tool installed on your system. The @main command installs the main branch and may be modified to another branch, i.e. @canary.

pip install git+https://github.com/AmbiqAI/sleepkit.git@main

Or, using Poetry:

poetry add git+https://github.com/AmbiqAI/sleepkit.git@main

Requirements

Check the project's pyproject.toml file for a list of up-to-date Python dependencies. Note that the installation methods above install all required dependencies. The following are optional dependencies only needed when running demo command using Ambiq's evaluation board (EVB) backend:

Once installed, SleepKit can be used as either a CLI-based tool or as a Python package to perform advanced experimentation.

Use SleepKit with CLI

The SleepKit command line interface (CLI) allows for simple single-line commands without the need for a Python environment. The CLI requires no customization or Python code. You can simply run all tasks from the terminal with the sleepkit command. Check out the CLI Guide to learn more about available options.

Example

sleepkit commands use the following syntax:

sleepkit --mode [MODE] --task [TASK] --config [CONFIG]

Or using short flags:

sleepkit -m [MODE] -t [TASK] -c [CONFIG]

Where:

  • MODE is one of download, feature, train, evaluate, export, or demo
  • TASK is one of detect, stage, apnea, or arousal
  • CONFIG is configuration as JSON content or file path

Download datasets specified in the configuration file.

sleepkit -m download -c ./configuration.json

Extract features from the datasets using the supplied configuration file.

sleepkit -m feature -c ./configuration.json

Train a sleep stage model using the supplied configuration file.

sleepkit -m train -t stage -c ./configuration.json

Evaluate the trained sleep stage model using the supplied configuration file.

sleepkit -m evaluate -t stage  -c ./configuration.json

Run demo on trained sleep stage model using the supplied configuration file.

sleepkit -m demo -t stage -c ./configuration.json

Use SleepKit with Python

The SleepKit 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. The package is designed to be simple and easy to use.

For example, you can create a custom model, train it, evaluate its performance on a validation set, and even export a quantized TensorFlow Lite model for deployment. Check out the Python Guide to learn more about using SleepKit as a Python package.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import sleepkit as sk

params = sk.HKTaskParams(...)  # Expand to see example (1)

task = sk.TaskFactory.get("stage")

task.download(params)  # Download dataset(s)

task.feature(params)  # Generate features

task.train(params)  # Train the model

task.evaluate(params)  # Evaluate the model

task.export(params)  # Export to TFLite
  1. Configuration parameters: 
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
    sk.TaskParams(
    name="sd-2-tcn-sm",
    job_dir="./results/sd-2-tcn-sm",
    verbose=2,

    datasets=[
        hk.NamedParams(
            name="cmidss",
            params={
                "path": "./datasets/cmidss"
            }
        )
    ],

    feature=hk.FeatureParams(
        name="FS-W-A-5",
        sampling_rate=0.2,
        frame_size=12,
        loader="hdf5",
        feat_key="features",
        label_key="detect_labels",
        mask_key="mask",
        feat_cols=None,
        save_path="./datasets/store/fs-w-a-5-60",
        params={}
    ),

    sampling_rate=0.0083333,
    frame_size=240,

    num_classes=2,
    class_map={
        0: 0,
        1: 1,
        2: 1,
        3: 1,
        4: 1,
        5: 1
    },
    class_names=["WAKE", "SLEEP"],

    samples_per_subject=100,
    val_samples_per_subject=100,
    test_samples_per_subject=50,

    val_size=4000,
    test_size=2500,

    val_subjects=0.20,
    batch_size=128,
    buffer_size=10000,
    epochs=200,
    steps_per_epoch=25,
    val_steps_per_epoch=25,
    val_metric="loss",
    lr_rate=1e-3,
    lr_cycles=1,
    label_smoothing=0,

    test_metric="f1",
    test_metric_threshold=0.02,
    tflm_var_name="sk_detect_flatbuffer",
    tflm_file="sk_detect_flatbuffer.h",

    backend="pc",
    display_report=True,

    quantization=hk.QuantizationParams(
        qat=False,
        mode="INT8",
        io_type="int8",
        concrete=True,
        debug=False
    ),

    model_file="model.keras",
    use_logits=False,
    architecture=hk.NamedParams(
        name="tcn",
        params={
            "input_kernel": [1, 5],
            "input_norm": "batch",
            "blocks": [
                {"depth": 1, "branch": 1, "filters": 16, "kernel": [1, 5], "dilation": [1, 1], "dropout": 0.10, "ex_ratio": 1, "se_ratio": 4, "norm": "batch"},
                {"depth": 1, "branch": 1, "filters": 32, "kernel": [1, 5], "dilation": [1, 2], "dropout": 0.10, "ex_ratio": 1, "se_ratio": 4, "norm": "batch"},
                {"depth": 1, "branch": 1, "filters": 48, "kernel": [1, 5], "dilation": [1, 4], "dropout": 0.10, "ex_ratio": 1, "se_ratio": 4, "norm": "batch"},
                {"depth": 1, "branch": 1, "filters": 64, "kernel": [1, 5], "dilation": [1, 8], "dropout": 0.10, "ex_ratio": 1, "se_ratio": 4, "norm": "batch"}
            ],
            "output_kernel": [1, 5],
            "include_top": True,
            "use_logits": True,
            "model_name": "tcn"
        }
    )