psgscoring 0.2.4

Open-source AASM 2.6-compliant respiratory scoring for polysomnography

psgscoring

Open-source AASM 2.6-compliant respiratory scoring for polysomnography.

psgscoring is a standalone Python library that implements the full AASM 2.6 respiratory scoring algorithm for polysomnographic (PSG) recordings. It is the scoring engine behind YASAFlaskified and is designed to work with YASA and MNE-Python.

Features

• Apnea detection: ≥90% flow reduction on oronasal thermistor, ≥10 s
• Hypopnea detection: ≥30% flow reduction on nasal pressure, ≥10 s, with ≥3% desaturation or arousal
• Apnea type classification: 7-rule obstructive/central/mixed classification with Hilbert phase-angle analysis
• ECG-derived effort (v0.2.4): Transformed ECG (TECG) method (Berry et al., JCSM 2019) + spectral classifier for improved central vs. obstructive differentiation
• Six over-counting corrections: post-apnea baseline inflation, SpO₂ cross-contamination, Cheyne-Stokes flagging, borderline classification, artefact-flank exclusion, local baseline validation
• Six under-counting corrections: peak-based hypopnea detection, SpO₂ de-blocking, extended nadir window, flow smoothing, position auto-mapping, configurable scoring profiles
• SpO₂ analysis: ODI at 3% and 4% thresholds, baseline (P90), T90
• PLM scoring: AASM 2.6 + WASM criteria
• RERA and RDI: flow limitation (flattening index) and FRI-RERA detection

Installation

pip install psgscoring

With optional dependencies (LightGBM confidence calibration):

pip install psgscoring[full]

Quick start

import mne
from psgscoring import run_pneumo_analysis

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

results = run_pneumo_analysis(raw, hypno)

ahi = results["respiratory"]["summary"]["ahi_total"]
print(f"AHI: {ahi}")

Scoring profiles

Three configurable profiles balance sensitivity vs. specificity:

Profile	Use case	Hypopnea threshold
strict	Minimise false positives	40% flow reduction
standard	AASM 2.6 default	30% flow reduction
sensitive	Maximise detection	25% flow reduction

References

• Berry RB et al. The AASM Manual for the Scoring of Sleep and Associated Events, Version 2.6. AASM, 2020.
• Berry RB et al. Use of a Transformed ECG Signal to Detect Respiratory Effort During Apnea. J Clin Sleep Med. 2019;15(11):1653–1660.
• Vallat R, Walker MP. An open-source, high-performance tool for automated sleep staging. eLife. 2021;10:e70092.

Disclaimer

psgscoring is research software, not a cleared medical device. All computed indices are research-grade estimates that must be reviewed by a qualified clinician. See DISCLAIMER.md.

License

BSD-3-Clause. See LICENSE.

Citation

If you use psgscoring in your research, please cite:

Rombaut B, Rombaut B, Rombaut C, Vallat R. YASAFlaskified: an open-source platform for automated PSG analysis with systematic over-counting and under-counting corrections. In preparation, 2026.