cpap

name	cpap
description	Analyze CPAP sleep therapy data from the user's ResMed AirSense 11. Read daily summaries (AHI, leak, pressure, compliance) and per-session waveforms from EDF files in the private cpap-data Forgejo git repo. Use when user asks about sleep quality, CPAP data, AHI, therapy compliance, or sleep analysis.

CPAP Data Analysis

Analyze ResMed AirSense 11 AutoSet CPAP data synced daily from an ez Share WiFi SD card into the private Forgejo repo cpap-data/cpap-data.

Data access

Clone https://git.allegedly.works/cpap-data/cpap-data.git (the secret's repo_url key) with the read-only cpap-data-reader credentials from the cpap-data-git-read Kubernetes secret (keys: username, password, repo_url):

• Claude Code web: read the reflected copy in claude-sandbox through the connected Kubernetes MCP path: kubectl -n claude-sandbox get secret cpap-data-git-read.
• Laptops (admin kubeconfig): kubectl -n cpap-sync get secret cpap-data-git-read.

USERNAME=$(kubectl -n claude-sandbox get secret cpap-data-git-read -o jsonpath='{.data.username}' | base64 -d)
PASSWORD=$(kubectl -n claude-sandbox get secret cpap-data-git-read -o jsonpath='{.data.password}' | base64 -d)

# Credentials via env config, not argv/URL (no leak into process listings):
export GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraHeader
export GIT_CONFIG_VALUE_0="Authorization: Basic $(printf '%s:%s' "$USERNAME" "$PASSWORD" | base64 -w0)"

# Full archive is multi-GB; for just the daily summary, partial-clone + checkout one file:
git clone --filter=blob:none --no-checkout https://git.allegedly.works/cpap-data/cpap-data.git /tmp/cpap-data
git -C /tmp/cpap-data checkout main -- STR.EDF

Checking out DATALOG/<date>/ directories the same way fetches only those nights' blobs.

Directory structure on the card

/                        Root of the SD card
├── STR.EDF              Daily summary (one record per day, 78 signals)
├── Identification.json  Device serial, model, firmware
├── SETTINGS/            Device configuration snapshots
└── DATALOG/
    └── YYYYMMDD/        One directory per calendar date
        ├── *_CSL.edf    Session log (mask on/off events)
        ├── *_EVE.edf    Respiratory events (apneas, hypopneas, flow limitations)
        ├── *_BRP.edf    Breath-by-breath metrics (pressure, flow, leak per breath)
        ├── *_PLD.edf    High-resolution waveforms (~25 Hz: pressure, leak, flow)
        └── *_SA2.edf    SpO2 + pulse rate (if oximeter connected)

Note: filenames on the card use 8.3 short names (e.g., 202604~1.EDF). The long names above come from the card's XML API <name> field.

EDF format overview

EDF (European Data Format) is a simple binary format:

1. Main header (256 bytes): version, patient, recording info, start date/time, number of data records, record duration, number of signals.
2. Signal headers (256 bytes per signal): label, units, physical/digital min/max, samples per record.
3. Data records: interleaved int16 samples for each signal.

Physical value from digital: phys_min + (digital - dig_min) * (phys_max - phys_min) / (dig_max - dig_min)

STR.EDF signals (daily summary)

The Date signal stores days since Unix epoch (1970-01-01). Key signals:

Signal	Unit	Description
Date	days from epoch	Calendar date
Duration	minutes	Total therapy time
AHI	events/hr	Apnea-Hypopnea Index (total)
HI	events/hr	Hypopnea Index
OAI	events/hr	Obstructive Apnea Index
CAI	events/hr	Central Apnea Index
MaskPress.50 / .95	cmH2O	Mask pressure median / 95th percentile
Leak.50 / .95	L/s	Leak rate (multiply by 60 for L/min)
RespRate.50	bpm	Respiratory rate median
TidVol.50	L	Tidal volume median
SpO2.50	%	Blood oxygen median (-1 = no oximeter)
CSR	minutes	Cheyne-Stokes respiration duration
MaskOn / MaskOff	minutes	Mask on/off times (up to 20 per day)

Clinical thresholds

Metric	Normal	Mild	Moderate	Severe
AHI	<5	5-15	15-30	>30
Compliance	≥4h on ≥70% nights	—	—	<4h or <70%
Leak 95th	<24 L/min	24-36	>36	—

Python libraries

stdlib parsing (no dependencies)

For STR.EDF parsing, stdlib struct + xml.etree.ElementTree is sufficient. See examples/parse_str_edf.py for a complete implementation.

pyedflib (recommended for waveforms)

pip install pyedflib  # depends on numpy only

from pyedflib import highlevel

signals, signal_headers, header = highlevel.read_edf("DATALOG/20260418/file.edf")
for i, sh in enumerate(signal_headers):
    print(f"{sh['label']}: {len(signals[i])} samples @ {sh['sample_frequency']} Hz")

Other tools

• OSCAR (Open Source CPAP Analysis Reporter): Desktop GUI for ResMed data analysis. The gold standard for CPAP data visualization. https://www.sleepfiles.com/OSCAR/
• oscar-etl (pip install oscar-etl): Python ETL for ResMed EDF files. Extracts 7 signals (pressure, leak, respiratory rate, tidal volume, minute ventilation, snore, flow limitation). Auto-segments by mask-on periods.
• edf-importer (https://github.com/tedpearson/edf-importer): Imports ResMed AirSense 11 EDF files to InfluxDB/VictoriaMetrics for Grafana dashboards.
• edfio (pip install edfio): Modern pure-Python EDF reader, alternative to pyedflib.

Recipes

Parse STR.EDF daily summary

See examples/parse_str_edf.py. This is a standalone stdlib-only script that reads STR.EDF and outputs a nightly summary table with AHI, usage, pressure, leaks, respiratory rate, and compliance stats.

Usage:

# Grab STR.EDF from the partial clone (see "Data access") and analyze last 14 days
git -C /tmp/cpap-data checkout main -- STR.EDF
python3 examples/parse_str_edf.py /tmp/cpap-data/STR.EDF --days 14

Read DATALOG waveforms with pyedflib

See examples/read_waveforms.py. Reads a DATALOG session's BRP/PLD/EVE files and prints signal summaries (min, max, mean, duration).

Scaffolding for tests

All recipes assume:

• Python 3.11+
• pyedflib available (for waveform recipes only; STR.EDF parsing is stdlib-only)
• EDF files accessible locally (checked out from the cpap-data repo or passed as arguments)

Test fixtures use the public EDF test file from https://www.teuniz.net/edf_bdf_testfiles/test_generator_2_edfplus.zip (2.7 MB, 12 signals, 600 records at 1s duration). This validates format parsing without requiring real CPAP data.