Metadata-Version: 2.4
Name: psgscoring
Version: 0.2.95
Summary: Open-source Python library for AASM 2.6-compliant automated polysomnography scoring
Author-email: Bart Rombaut <bart.rombaut@azorg.be>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://slaapkliniek.be
Project-URL: Repository, https://github.com/bartromb/psgscoring
Project-URL: Documentation, https://github.com/bartromb/psgscoring/wiki
Project-URL: Issues, https://github.com/bartromb/psgscoring/issues
Keywords: polysomnography,PSG,sleep,AASM,apnea,hypopnea,AHI,respiratory,scoring,sleep-staging,YASA,hypoxic-burden
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Requires-Dist: mne>=1.0
Provides-Extra: full
Requires-Dist: yasa>=0.6; extra == "full"
Requires-Dist: lightgbm>=3.0; extra == "full"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: hypothesis>=6.0; extra == "test"
Dynamic: license-file

# psgscoring

[![PyPI](https://img.shields.io/pypi/v/psgscoring.svg)](https://pypi.org/project/psgscoring/)
[![License: BSD-3](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/bartromb/psgscoring/blob/main/LICENSE)
[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.12-blue.svg)](pyproject.toml)
[![Validated](https://img.shields.io/badge/validated-PSG--IPA%20(60%20sessions)-green.svg)](https://github.com/bartromb/psgscoring/wiki)

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

`psgscoring` extracts the core respiratory scoring algorithms from [YASAFlaskified](https://github.com/bartromb/YASAFlaskified) into a standalone, pip-installable library for the research community.

## Validation (v0.2.95)

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.95): total SpO₂ desaturation area per event, normalised per hour (Azarbarzin et al., AJRCCM 2019)
- **Post-processing** (v0.2.95): 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

```bash
pip install psgscoring
```

## Quick start

```python
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.95)
hb = results["hypoxic_burden"]
print(f"Hypoxic burden: {hb['hypoxic_burden']} {hb['unit']}")

# Post-processing results (v0.2.95)
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.95

- **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)](https://github.com/bartromb/psgscoring/wiki)
📖 [Technical Handbook](https://github.com/bartromb/psgscoring/blob/main/docs/handbook.pdf)

## Live platform

**[slaapkliniek.be](https://slaapkliniek.be)** — upload EDF, receive complete PSG report.

## Citation

> Rombaut B, Rombaut B, Rombaut C. 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](LICENSE).

**Disclaimer**: Research use only. Not CE-marked or FDA-cleared. See [DISCLAIMER.md](DISCLAIMER.md).
