psgscoring 0.2.94

Open-source Python library for AASM 2.6-compliant automated polysomnography scoring

psgscoring

Open-source Python library for AASM 2.6-compliant automated polysomnography scoring.

psgscoring extracts the core respiratory scoring algorithms from YASAFlaskified into a standalone, pip-installable library for the research community.

Validation (v0.2.94)

External validation on two public datasets:

PSG-IPA (PhysioNet, 5 recordings, 60 scorer sessions from 12 RPSGT/ESRS)

Metric	Result	Target
AHI bias	+1.6/h	<±5/h ✓
MAE	2.5/h	—
Pearson r	0.990	≥0.85 ✓
Severity concordance	75%	≥70% ✓
Event-level F1 (SN3)	0.890	—

For 3/5 recordings, the algorithm's deviation from the scorer mean was smaller than the inter-scorer variability.

iSLEEPS (39 ischemic stroke patients, SOMNOmedics)

Severity	Bias	MAE
Normal/Mild (n=13)	−0.1/h	3.3/h
Moderate/Severe (n=26)	−16.6/h	16.6/h

Excellent for standard populations; systematic under-scoring in stroke patients (central apnea predominance).

Features

• AASM 2.6 respiratory scoring: apnea/hypopnea detection with dual-sensor support
• 12 systematic bias corrections: 6 over-counting + 6 under-counting
• Breath-amplitude stability filter: rejects false-positive hypopneas during normal breathing
• AHI confidence interval: strict/standard/sensitive profiles with robustness grade (A/B/C)
• Hypoxic burden (v0.2.94): total SpO₂ desaturation area per event, normalised per hour (Azarbarzin et al., AJRCCM 2019)
• Post-processing (v0.2.94): CSR-aware central reclassification, mixed apnea decomposition, central instability index
• ECG-derived effort classification: spectral + TECG for central apnea detection
• Configurable scoring profiles: strict (research), standard (AASM 2.6), sensitive (UARS)
• PLM, SpO₂, RERA/RDI, signal quality assessment

Installation

pip install psgscoring

Quick start

from psgscoring import run_pneumo_analysis
import mne

raw = mne.io.read_raw_edf("recording.edf", preload=True)
hypno = ["W", "N1", "N2", "N3", "R", ...]  # 30-s epochs

results = run_pneumo_analysis(raw, hypno, scoring_profile="standard")

# AHI with confidence interval
iv = results["ahi_interval"]
print(f"AHI: {iv['standard']['ahi']} [{iv['strict']['ahi']}–{iv['sensitive']['ahi']}]")
print(f"Grade: {iv['robustness_grade']}")

# Hypoxic burden (v0.2.94)
hb = results["hypoxic_burden"]
print(f"Hypoxic burden: {hb['hypoxic_burden']} {hb['unit']}")

# Post-processing results (v0.2.94)
pp = results["postprocess"]
print(f"CSR reclassified: {pp['n_csr_reclassified']}")
print(f"Mixed decomposed: {pp['n_mixed_decomposed']}")

What's new in v0.2.94

• Ensemble-averaged hypoxic burden: baseline_method="ensemble" reproduces the original Azarbarzin et al. (2019) method with subject-specific search windows derived from ensemble-averaged SpO₂ curves. Default "percentile" is unchanged.
• Hypoxic burden: per-event SpO₂ desaturation area, normalised %·min/h
  • Clinical thresholds: <20 low, 20–73 moderate, >73 high CV risk
• CSR-aware reclassification: flagged obstructive/mixed events in CSR troughs → central
• Mixed apnea decomposition: central portion ≥10s → reclassified as central
• Central instability index: profile-dependent O/C uncertainty (0–1 scale)
• iSLEEPS validation: 39 stroke patients, MAE 3.3/h at normal/mild
• Event-level validation: F1=0.890, Δt=2.3s on severe-OSA recording

Documentation

📖 Online Supplement (Wiki) 📖 Technical Handbook

Live platform

slaapkliniek.be — upload EDF, receive complete PSG report.

Citation

Rombaut B, Rombaut B, Rombaut C, Vallat R. psgscoring: An Open-Source Python Library for AASM 2.6-Compliant Automated Polysomnography Scoring. 2026. https://github.com/bartromb/psgscoring

This library builds on YASA:

Vallat R, Walker MP. An open-source, high-performance tool for automated sleep staging. eLife. 2021;10:e70092.

License

BSD-3-Clause. See LICENSE.

Disclaimer: Research use only. Not CE-marked or FDA-cleared. See DISCLAIMER.md.