feat: add readme and download script

2026-08-13 09:31:52 +02:00
parent 040cb357f4
commit eb5158ece3
3 changed files with 80 additions and 0 deletions
@@ -0,0 +1,60 @@
+# sleep-detection
+
+A small ML pipeline that turns wrist accelerometer + heart rate data into per-epoch sleep stage predictions (hypnogram building blocks).
+
+Built to support [InfiniTime PR #2304](https://github.com/InfiniTimeOrg/InfiniTime/pull/2304), which adds sleep tracking to InfiniTime (PineTime firmware) but stops at raw data logging.
+This repo explores whether a small offline-trained classifier can turn that raw data into sleep stages and eventually an on-device hypnogram.
+
+## Repo layout
+
+- `src/sleep_detection/` — data loading, epoching/features, model, training loop
+- `scripts/` — supporting/experimentation scripts
+- `plots/` — output plots
+
+## Datasets
+
+Not included in this repo — download separately:
+
+- [PhysioNet: Motion and heart rate from a wrist-worn wearable and labeled sleep from polysomnography](https://physionet.org/content/sleep-accel/1.0.0/) (Walch et al., 2019) — primary dataset used so far.
+- [PhysioNet: A Multi-Night Instantaneous Heart Rate and Accelerometry Dataset with EEG Sleep Stage Labels](https://physionet.org/content/bidsleep-dataset/1.0.0/) — larger, newer, same sensor modalities.
+- [PhysioNet: MMASH](https://physionet.org/content/mmash/1.0.0/) — 24h continuous HR + accelerometer + sleep quality, healthy adults.
+
+## Getting started
+
+This is just a regular python project. I recommend you work in an editable virtual environment during development.
+
+```sh
+cd sleep-detection
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -e .
+```
+
+The [uv](https://github.com/astral-sh/uv) project manager should also work just fine if you prefer to use that.
+
+### Datasets
+
+Not included in this repo, but a convenience download script exists. Note that this will take a while because the
+physionet servers are deliberately quite slow.
+
+```sh
+./download.sh
+```
+
+## Usage
+
+As an example training a model on the `sleep-accel` dataset subject `1066528`:
+
+```sh
+sleep-detection \
+   -a physionet.org/files/sleep-accel/1.0.0/motion/1066528_acceleration.txt \
+   -H physionet.org/files/sleep-accel/1.0.0/heart_rate/1066528_heartrate.txt \
+   -l physionet.org/files/sleep-accel/1.0.0/labels/1066528_labeled_sleep.txt \
+   --output model.pt
+```
+
+## Help Wanted
+
+I am not sure if the way I am feeding / dividing the training data up is done appropriately and if the model is too
+simple for this kind of dataset. I would love some help from someone who have experience and proper insight into how to
+train models using pytorch. Feel free to message me, submit an issue, fork the project etc.