psgscoring 0.2.2__tar.gz → 0.2.4__tar.gz

psgscoring-0.2.4/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-2026, Bart Rombaut, Briek Rombaut, Cedric Rombaut
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

psgscoring-0.2.4/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: psgscoring
+Version: 0.2.4
+Summary: Open-source AASM 2.6-compliant respiratory scoring for polysomnography
+Author: Briek Rombaut, Cedric Rombaut
+Author-email: Bart Rombaut <bart.rombaut@azorg.be>
+License: BSD-3-Clause
+Project-URL: Homepage, https://github.com/bartromb/psgscoring
+Project-URL: Documentation, https://github.com/bartromb/psgscoring#readme
+Project-URL: Repository, https://github.com/bartromb/psgscoring
+Project-URL: Issues, https://github.com/bartromb/psgscoring/issues
+Project-URL: Changelog, https://github.com/bartromb/psgscoring/blob/main/CHANGES.md
+Keywords: sleep,polysomnography,PSG,apnea,hypopnea,AHI,AASM,respiratory,scoring,sleep-staging,YASA,EDF,clinical,neuroscience
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: BSD License
+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.22
+Requires-Dist: scipy>=1.9
+Requires-Dist: mne>=1.3
+Provides-Extra: full
+Requires-Dist: lightgbm>=3.3; extra == "full"
+Requires-Dist: yasa>=0.6.4; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# 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](https://github.com/bartromb/YASAFlaskified) and is designed to work with [YASA](https://github.com/raphaelvallat/yasa) and [MNE-Python](https://mne.tools/).
+
+## 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
+
+```bash
+pip install psgscoring
+```
+
+With optional dependencies (LightGBM confidence calibration):
+
+```bash
+pip install psgscoring[full]
+```
+
+## Quick start
+
+```python
+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](https://github.com/bartromb/psgscoring/blob/main/DISCLAIMER.md).
+
+## License
+
+BSD-3-Clause. See [LICENSE](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.

psgscoring-0.2.4/README.md

@@ -0,0 +1,74 @@
+# 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](https://github.com/bartromb/YASAFlaskified) and is designed to work with [YASA](https://github.com/raphaelvallat/yasa) and [MNE-Python](https://mne.tools/).
+
+## 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
+
+```bash
+pip install psgscoring
+```
+
+With optional dependencies (LightGBM confidence calibration):
+
+```bash
+pip install psgscoring[full]
+```
+
+## Quick start
+
+```python
+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](https://github.com/bartromb/psgscoring/blob/main/DISCLAIMER.md).
+
+## License
+
+BSD-3-Clause. See [LICENSE](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.

{psgscoring-0.2.2 → psgscoring-0.2.4}/psgscoring/__init__.py

@@ -20,6 +20,7 @@ spo2         – SpO2 coupling (Rule 1A) and full SpO2 analysis
 plm          – PLM detection (AASM 2.6)
 ancillary    – position, heart rate, snore, Cheyne-Stokes
 respiratory  – apnea/hypopnea detection, Rule 1B, summary statistics
+ecg_effort   – ECG-derived effort (TECG, spectral classifier) for central/obstructive differentiation
 pipeline     – MNE-facing master function (run_pneumo_analysis)
 """
 
@@ -49,6 +50,7 @@ from .breath import (
     detect_breath_events,
 )
 from .classify import classify_apnea_type
+from .ecg_effort import ecg_effort_assessment, compute_tecg
 from .spo2 import analyze_spo2, detect_desaturations, get_desaturation
 from .plm import analyze_plm
 from .ancillary import (
@@ -65,9 +67,8 @@ from .utils import (
     is_nrem, is_rem, is_sleep,
     safe_r,
 )
-from .signal_quality import assess_signal_quality
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 __all__ = [
     # Master
     "run_pneumo_analysis",
@@ -92,6 +93,9 @@ __all__ = [
     "detect_breath_events",
     # Classify
     "classify_apnea_type",
+    # ECG effort
+    "ecg_effort_assessment",
+    "compute_tecg",
     # SpO2
     "analyze_spo2",
     "detect_desaturations",
@@ -103,8 +107,6 @@ __all__ = [
     "analyze_heart_rate",
     "analyze_snore",
     "detect_cheyne_stokes",
-    # Signal quality (v0.2.2)
-    "assess_signal_quality",
     # Utils
     "detect_channels",
     "channel_map_from_user",

{psgscoring-0.2.2 → psgscoring-0.2.4}/psgscoring/classify.py

@@ -112,6 +112,7 @@ def classify_apnea_type(
     abdomen_raw:  np.ndarray | None,
     effort_baseline: float,
     sf: float,
+    ecg_assessment: dict | None = None,
 ) -> tuple[str, float, dict]:
     """
     Classify an apnea event as ``"obstructive"``, ``"central"``, or
@@ -126,9 +127,19 @@ def classify_apnea_type(
     3. **Mixed pattern** – absent effort first half, present second half
     4. **Effort clearly present** → obstructive
     5. **Truly flat** – no raw movement, low envelope → central
+    5b. **ECG-derived reclassification** (v0.8.23) – TECG + spectral
+        analysis overrides RIP-based obstructive if cardiac artefact only.
     6. **Borderline default** → obstructive (low confidence)
        If LightGBM model available, confidence is calibrated by model.
 
+    Parameters
+    ----------
+    ecg_assessment : dict, optional
+        Output of ``ecg_effort.ecg_effort_assessment()``.
+        If provided and ``reclassify_as_central`` is True, events that
+        would otherwise be classified as obstructive (rules 4, 6) are
+        reclassified as central.
+
     Returns
     -------
     (type_str, confidence_0_to_1, detail_dict)
@@ -239,6 +250,24 @@ def classify_apnea_type(
         )
         return "central", safe_r(_conf(conf, 5), 2), detail
 
+    # ── Rule 5b (v0.8.23): ECG-derived reclassification ──────────────────
+    # If TECG shows no inspiratory bursts AND spectral analysis shows
+    # cardiac dominance, reclassify borderline/effort-present as central.
+    if ecg_assessment is not None and ecg_assessment.get("reclassify_as_central"):
+        detail["ecg_assessment"] = {
+            k: v for k, v in ecg_assessment.items()
+            if k not in ("tecg_detail", "spectral_detail")
+        }
+        # Only reclassify if effort is ambiguous (ratio < clear threshold)
+        if effort_ratio < EFFORT_PRESENT_RATIO * 1.5:
+            conf = 0.75
+            if ecg_assessment.get("ecg_effort_present") is False:
+                conf = 0.85  # both TECG and spectral agree
+            detail["decision_reason"] = (
+                f"ecg_reclassified_central_effort={safe_r(effort_ratio,3)}"
+            )
+            return "central", safe_r(_conf(conf, 5), 2), detail
+
     # ── Rule 6: Borderline default ────────────────────────────────────────
     detail["decision_reason"] = (
         f"borderline_default_var={safe_r(raw_var_ratio,3)}_effort={safe_r(effort_ratio,3)}"

{psgscoring-0.2.2 → psgscoring-0.2.4}/psgscoring/constants.py

@@ -16,6 +16,8 @@ HYPOPNEA_SMOOTH_S      = 3.0    # v0.8.12: smooth flow before thresholding (seco
                                  # Mimics human visual averaging; reduces false negatives
 APNEA_MIN_DUR_S        = 10.0   # seconds
 HYPOPNEA_MIN_DUR_S     = 10.0   # seconds
+APNEA_MAX_DUR_S        = 90.0   # v0.8.22: events >90s are split at partial recovery
+HYPOPNEA_MAX_DUR_S     = 60.0   # v0.8.22: events >60s are split at partial recovery
 DESATURATION_DROP_PCT  = 3.0    # >= 3% SpO2 drop required for Rule 1A
 EFFORT_ABSENT_RATIO    = 0.20   # < 20% of baseline effort -> absent
 EFFORT_PRESENT_RATIO   = 0.40   # > 40% of baseline effort -> present
@@ -45,6 +47,8 @@ SCORING_PROFILES: dict[str, dict] = {
         "HYPOPNEA_SMOOTH_S":    0.0,    # no smoothing
         "CROSS_CONTAM_WINDOW_S": 15.0,
         "USE_PEAK_DETECTION":   False,  # envelope only
+        "HYPOPNEA_MAX_DUR_S":   60.0,   # v0.8.22
+        "APNEA_MAX_DUR_S":      90.0,   # v0.8.22
     },
     "standard": {
         "label":                "Standard (AASM 2.6)",
@@ -54,6 +58,8 @@ SCORING_PROFILES: dict[str, dict] = {
         "HYPOPNEA_SMOOTH_S":    3.0,
         "CROSS_CONTAM_WINDOW_S": 15.0,
         "USE_PEAK_DETECTION":   True,   # peak + envelope
+        "HYPOPNEA_MAX_DUR_S":   60.0,   # v0.8.22
+        "APNEA_MAX_DUR_S":      90.0,   # v0.8.22
     },
     "sensitive": {
         "label":                "Sensitive (RPSGT-like)",
@@ -63,6 +69,8 @@ SCORING_PROFILES: dict[str, dict] = {
         "HYPOPNEA_SMOOTH_S":    5.0,    # more smoothing
         "CROSS_CONTAM_WINDOW_S": 0.0,   # no cross-contam check
         "USE_PEAK_DETECTION":   True,
+        "HYPOPNEA_MAX_DUR_S":   90.0,   # v0.8.22: meer tolerant
+        "APNEA_MAX_DUR_S":      120.0,  # v0.8.22
     },
 }