https://github.com/vendaface/apple_health_tracker
Turn an Apple Health export into an interactive, self-contained sleep & respiratory dashboard (hypnogram, SpO2, respiratory rate, breathing-disturbance index) for review with a clinician.
https://github.com/vendaface/apple_health_tracker
apple-health dashboard data-visualization echarts health-data healthkit hypnogram pulmonology python quantified-self sleep-tracking
Last synced: about 1 hour ago
JSON representation
Turn an Apple Health export into an interactive, self-contained sleep & respiratory dashboard (hypnogram, SpO2, respiratory rate, breathing-disturbance index) for review with a clinician.
- Host: GitHub
- URL: https://github.com/vendaface/apple_health_tracker
- Owner: vendaface
- License: mit
- Created: 2026-06-20T12:07:08.000Z (12 days ago)
- Default Branch: main
- Last Pushed: 2026-06-20T12:50:20.000Z (12 days ago)
- Last Synced: 2026-06-20T14:34:34.474Z (12 days ago)
- Topics: apple-health, dashboard, data-visualization, echarts, health-data, healthkit, hypnogram, pulmonology, python, quantified-self, sleep-tracking
- Language: HTML
- Size: 616 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# apple_health_tracker
Tooling to turn an **Apple Health export** into a self-contained, interactive
**sleep & respiratory dashboard** — designed for review with a pulmonary specialist.
It pairs sleep-stage data (hypnogram) with the breathing-related metrics in the export
(blood oxygen / SpO₂, respiratory rate, and Apple's sleeping breathing-disturbance index).
> **Privacy:** this repository contains **code only**. No personal health data is
> included. The raw export and the generated dashboard (which embed real readings) are
> git-ignored and never leave your machine.
*Screenshot above is generated from **synthetic** data (`dashboard/sample_data.py`), not real readings.*
## Quick start
1. On your iPhone: **Health app → profile → Export All Health Data**. Unzip it; you'll
get a folder containing `export.xml`.
2. Send the file to your destination of choice (AirDrop to a Mac, email to yourself, probably don't save your personal health data to the cloud). Note: depending upon how many years you've been collecting data, it could be multiple gigabytes in size.
3. Place this repo's `dashboard/` folder next to that `export.xml` (or pass a path).
4. Open a command line environment (Terminal, Command) and build the dashboard:
```bash
cd dashboard
python3 etl.py # streams ../export.xml -> data/*.json (a few minutes)
python3 build.py # inlines ECharts + data -> sleep-dashboard.html
```
5. Double-click the resulting **`dashboard/sleep-dashboard.html`** to open it in a browser. It's one self-contained
file — no server or internet needed — and has a **Print / PDF** button for sharing.
## Dashboard views
- **Single-night detail** — hypnogram (Deep/Core/REM/Awake) with SpO₂ (incl. a 90%
threshold line), respiratory rate and heart rate overlaid on a shared, zoomable timeline.
- **Sleep calendar** — every night shaded by hours slept; click a day to open it.
- **Trends** — nightly sleep, avg SpO₂, respiratory rate and breathing-disturbance index.
- **Stage composition** — stacked stage-minutes per night.
- **Breathing-disturbance focus** — the watchOS 11 apnea-related signal over time.
See [`dashboard/README.md`](dashboard/README.md) for details.
## Try it without an export (synthetic demo)
No Apple Health export handy? Generate a realistic, fully synthetic dashboard:
```bash
cd dashboard
python3 sample_data.py # -> ../docs/sample_*.json
python3 build.py ../docs/sample_summary.json ../docs/sample_detail.json /tmp/demo.html
open /tmp/demo.html
```
This is exactly how the screenshot above was produced — no real data involved.
## How it works
`etl.py` stream-parses the multi-GB `export.xml` with constant memory, groups sleep
records into nights (noon-to-noon), deduplicates overlapping sources (prefers Apple
Watch staged data), bins overnight vitals, and emits compact JSON. `build.py` inlines
[Apache ECharts](https://echarts.apache.org/) and that JSON into a single portable HTML.
## License
[MIT](LICENSE) © 2026 Vendaface. Bundled Apache ECharts (`dashboard/vendor/`) is under
the Apache-2.0 license.