Metadata-Version: 2.4
Name: psgscoring
Version: 0.2.91
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#readme
Project-URL: Issues, https://github.com/bartromb/psgscoring/issues
Keywords: polysomnography,PSG,sleep,AASM,apnea,hypopnea,AHI,respiratory,scoring,sleep-staging,YASA
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)
[![Tests](https://img.shields.io/badge/tests-47%20passed-brightgreen.svg)](https://github.com/bartromb/psgscoring/blob/main/psgscoring/tests/)
[![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(47%20scorers)-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.8)

External validation on the [PSG-IPA dataset](https://physionet.org/content/psg-ipa/) (PhysioNet, 5 recordings, 47 independent scorer sessions):

| PSG | Scorers | Median AHI | psgscoring AHI | ΔAHI | Severity |
|-----|---------|-----------|----------------|------|----------|
| SN1 | 11 | 6.0 | 8.1 | +2.1 | Mild ✓ |
| SN2 | 4 | 4.4 | 9.3 | +4.9 | Mild / Normal |
| SN3 | 12 | 54.0 | 53.8 | −0.2 | Severe ✓ |
| SN4 | 12 | 3.5 | 4.3 | +0.8 | Normal ✓ |
| SN5 | 12 | 9.9 | 11.4 | +1.5 | Mild ✓ |
| **Mean** | | | | **1.9** | **4/5 concordant** |

Details: [Online Supplement (Wiki)](https://github.com/bartromb/psgscoring/wiki)

## Features

- **AASM 2.6 respiratory scoring**: apnea/hypopnea detection with dual-sensor support
- **12 systematic bias corrections**: 6 over-counting + 6 under-counting ([details](https://github.com/bartromb/psgscoring/wiki))
- **Breath-amplitude stability filter** (v0.2.8): rejects false-positive hypopneas during normal breathing
- **AHI confidence interval**: strict/standard/sensitive profiles with robustness grade (A/B/C)
- **Configurable scoring profiles**: strict (research), standard (AASM 2.6), sensitive (UARS)
- **ECG-derived effort classification**: spectral + TECG for central apnea detection
- **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
print(f"AHI: {results['respiratory']['summary']['ahi_total']}")

# AHI confidence interval (v0.2.8)
iv = results["ahi_interval"]
print(f"Interval: [{iv['interval'][0]} – {iv['interval'][1]}] Grade: {iv['robustness_grade']}")
```

## What's new in v0.2.8

- **Removed flow smoothing** from standard profile (root cause: +54 false hypopneas)
- **Stability filter**: rejects hypopneas during stable breathing (CV < 0.45)
- **AHI confidence interval**: 3-profile analysis with robustness A/B/C
- **PSG-IPA validation**: mean |ΔAHI| = 1.9/h, severity concordance 4/5

## Documentation

📖 [Online Supplement (Wiki)](https://github.com/bartromb/psgscoring/wiki) — signal processing, corrections, validation  
📖 [Technical Handbook (PDF)](https://github.com/bartromb/psgscoring/blob/main/docs/handbook.pdf) — 26-page guide

## Live platform

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

## 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).
