1.3.0

Triadic‑Biosignal‑Monitor v1.3.0

Reproducibility, Stability, and Configuration Alignment Release

This release delivers a focused hardening pass across the operator core, pipelines, configuration system, and packaging. The goal is to ensure full reproducibility, eliminate silent drift between YAML and runtime behavior, and improve robustness across EEG‑only, ECG‑only, coupled, and streaming modes. No breaking API changes were introduced.

---

Core Operator & Feature Improvements

1. Canonical PLV Implementation

• Removed the duplicate 40‑line phase_locking_value function in core/features.py.
• All PLV computations now use the canonical implementation from core/phase.py.
• Existing imports (from core.features import phase_locking_value) continue to work via re‑export.

2. Normalized Operator Method Strings

• Added method = method.lower() in both compute_delta_I and compute_delta_C.
• YAML values such as "PLV", "Coherence", "Permutation_Entropy" now resolve correctly.

3. Entropy Parameter Consistency

• Removed silent overrides that forced order=4 and normalize=False.
• compute_delta_I now respects its documented defaults (order=3, delay=1, normalize=True) unless overridden by config.
• Updated entropy tests to use lower noise (1%) for stable detection under normalized entropy.

---

Sliding Window & RR Extraction Robustness

4. Windowing Edge‑Case Guards

• Added validation for overlap: raises ValueError unless 0 ≤ overlap < 1.
• Added short‑signal guard: if len(signal) < window_samples, pipelines emit a warning and return empty outputs.

5. RR Interval Safety Checks

• CoupledPipeline: now returns a clean no‑decision when baseline or current RR < 5 intervals (instead of silently degrading to EEG‑only).
• ECGOnlyPipeline: added baseline RR length check.
• StreamingPipeline: both _process_ecg_only and _process_coupled now require baseline and current RR ≥ 5; warnings include RR counts for debugging.

---

Configuration System Overhaul

6. New core/config_adapter.py

• Introduces adapt_config(raw_config) to flatten nested YAML structures into the flat dict expected by pipelines.
• Normalizes delta_C_method and delta_I_method to lowercase.
• Backwards‑compatible with legacy flat configs.

7. Pipeline Integration

• All pipelines (eeg_only, ecg_only, coupled) now receive:
  • entropy_kwargs
  • delta_I_method
  • delta_C_method
• Hardcoded operator selections removed; YAML now fully controls runtime behavior.

8. New Test Suite for Config Behavior

• Added tests/test_config_adapter.py with 11 tests covering:
  • PLV/plv case‑insensitivity
  • Entropy order/delay flowing correctly from YAML
  • Window size/overlap affecting actual windowing

---

NumPy 2.0 Compatibility

9. np.trapz → np.trapezoid

• Updated in core/features.py and core/metrics.py.
• Resolves 11 previously failing tests under NumPy 2.0.

---

Packaging, Versioning & Documentation

10. Unified Version Source

• Added triadic_biosignal_monitor/__init__.py with __version__ = "1.3.0".
• setup.py now reads the version via regex, ensuring a single source of truth.

11. Dependency Alignment

Added missing runtime dependencies with consistent version pinning:

• neurokit2>=0.2.0,<1.0.0
• PyWavelets>=1.4.0
• antropy>=0.1.6
• nolds>=0.5.2
• h5py>=3.8.0
• ipywidgets>=8.0.0

Aligned existing constraints with README requirements (numpy>=1.24, scipy>=1.10, mne>=1.3, etc.).

12. README Cleanup

• Fixed clone URL and all lowercase repo references.
• Removed broken documentation links.
• Consolidated duplicate dependency lists; now points to requirements.txt.

---

Security

• CodeQL scan reports 0 alerts.
• No vulnerabilities introduced or detected.

Triadic Biosignal Monitor v1.2.0

Overview

Version 1.2.0 delivers a comprehensive stability, correctness, and compatibility upgrade across the Triadic‑Biosignal‑Monitor codebase. This release resolves all identified critical bugs, improves numerical robustness, fixes alert‑timing logic, and ensures full compatibility with modern NumPy versions. All changes are minimal, targeted, and fully backward‑compatible.

---

Bugs Found and Fixed

Critical Issues (5 Fixed)

Deprecated NumPy API

File: core/features.py:392

• Issue: Used np.math.factorial(), removed in NumPy 1.24+
• Fix: Replaced with Python’s built‑in math.factorial()
• Impact: Restores compatibility with NumPy 1.24+ and modern Python environments

---

Division‑by‑Zero in Spectral Centroid

File: core/features.py:126

• Issue: Crashed on flatline or silent signals due to zero‑sum PSD
• Fix: Added guard to return 0.0 when PSD sum is zero
• Impact: Gracefully handles edge cases without runtime failures

---

Numerical Stability Issue

File: core/preprocessing.py:248

• Issue: Epsilon value (1e‑10) too small for reliable floating‑point comparisons
• Fix: Increased epsilon to 1e‑6
• Impact: More robust quality checks and fewer false instabilities

---

Variable Mutation Bug

File: core/gate.py:346

• Issue: Local reassignment inside a zip loop didn’t propagate correctly
• Fix: Introduced separate end_idx variable
• Impact: Alert timestamps now compute correctly and deterministically

---

Missing Validation for Permutation Entropy

File: core/features.py:368

• Issue: No validation for signals too short to compute permutation entropy
• Fix: Added explicit length check with informative warning
• Impact: Prevents silent failures and improves developer feedback

---

Verification Results

• Tests: 101/101 passing (100% success)
• Warnings: Reduced from 5 → 3 (all deprecation warnings eliminated)
• Security: CodeQL scan reports zero vulnerabilities
• Manual Testing: All fixes validated with edge‑case inputs

---

Files Modified

• core/features.py — 3 fixes (+20 lines)
• core/gate.py — 1 fix (+10 lines)
• core/preprocessing.py — 1 fix (+3 lines)

Total changes: 33 insertions, 7 deletions across 3 files

---

Impact

• Compatibility: Fully supports NumPy 1.24+
• Reliability: Eliminates division‑by‑zero crashes
• Correctness: Fixes alert‑timing logic and mutation issues
• Robustness: Improved handling of silent signals and short inputs

All critical bugs were resolved with minimal, surgical changes, significantly improving stability and correctness across the biosignal‑processing pipeline.

Triadic-Biosignal-Monitor v1.1

Summary

This release refines coherence, phase, and alerting logic to improve robustness under deterministic and low-variance signal conditions, while strengthening ECG feature extraction and physiological validity.

Key updates focus on making narrowband and quasi-deterministic biosignals behave correctly across global and windowed analyses, improving numerical stability, and enhancing downstream alert confidence.

Highlights

• ΔI & Coherence Aggregation

  • Updated ΔI computation and default coherence aggregation to better reflect deterministic and narrowband signal dynamics.
  • Improved sensitivity to structured signal changes without inflating noise-driven coherence.

• Phase & Synchrony Stability

  • Stabilized phase derivative outputs in low-variance and near-constant signal regimes.
  • Made Phase Locking Value (PLV) reliably usable in both global and windowed modes.

• Alerting & ECG Improvements

  • Adjusted alert confidence scoring for better alignment with physiological relevance.
  • Improved ECG RR interval extraction using enhanced peak detection and physiologic filtering to reduce spurious intervals.

Testing

• ✅ Ran full test suite:

  pytest tests/

• All tests passed successfully.

Notes

This release prioritizes numerical stability, physiological realism, and interpretability—laying a stronger foundation for downstream analytics and real-time monitoring use cases.

v1.0.0 — Initial Stable Release

Operator-Based Heart–Brain Isostasis Monitoring Framework

This release constitutes the first stable, reproducible software implementation of the operator-based framework described in:

“Operator-Based Heart–Brain Isostasis Monitoring via Triadic Spiral-Time Embeddings:
A Conservative, Falsifiable Framework for Early-Warning Detection in Coupled EEG/ECG Dynamics.”

The software provides a deterministic, interpretable pipeline for biosignal phase analysis and instability detection in coupled EEG and ECG/HRV time series.

---

Summary

Version 1.0.0 establishes the reference implementation for:

• triadic phase embeddings ψ(t) = (t, ϕ(t), χ(t)),
• computation of fixed instability components ΔS, ΔI, and ΔC,
• aggregation into a unified instability functional ΔΦ(t),
• modality ablations (EEG-only, ECG-only, and coupled),
• reproducible validation workflows.

All operators and thresholds are explicit, deterministic, and suitable for preregistered validation studies.

---

Core Features

Signal Representation

• Hilbert-based analytic signal phase extraction for EEG and ECG/HRV time series.
• Robust phase unwrapping and derivative computation for χ(t) as a regime-change marker.

Feature Computation

• Spectral and morphological deviation (ΔS).
• Information-theoretic deviation (ΔI).
• Cross-modal coupling and coherence deviation (ΔC).

Instability Functional

• Fixed-weight aggregation:
  ΔΦ(t) = α|ΔS(t)| + β|ΔI(t)| + γ|ΔC(t)|.
• Deterministic threshold gating with no adaptive or self-modifying parameters.

Pipelines and Ablations

• EEG-only analysis pipeline.
• ECG/HRV-only analysis pipeline.
• Fully coupled EEG–ECG pipeline.
• Structured ablation comparisons for isolating modality contributions.

Validation and Demonstration

• Synthetic regime-change detection tests.
• Reproducibility notebooks for phase extraction, feature computation, ablation analysis, and end-to-end pipeline execution.
• Metric support for lead-time estimation and false-alarm rate evaluation.

---

Reproducibility

This release emphasizes full reproducibility through:

• deterministic operators,
• fixed parameterization,
• configuration-driven execution,
• executable Jupyter notebooks aligned with the manuscript structure,
• transparent feature definitions and thresholds.

No black-box models or adaptive classifiers are used.

---

Scope and Safety Statement

This software is intended exclusively for:

• signal analysis,
• methodological validation,
• and decision-support research.

It does not implement:

• therapeutic control,
• neuromodulation or pacing,
• autonomous clinical intervention,
• or adaptive stimulation logic.

Any translation into clinical or device-level systems requires independent engineering validation, prospective clinical trials, and regulatory approval under applicable frameworks (e.g., FDA SaMD, IEC 62304, ISO 14971, EU MDR).

---

Compatibility

• Python ≥ 3.9
• NumPy, SciPy, Matplotlib, and Jupyter
• No proprietary or closed-source dependencies

---

Citation

If you use this software or methodology, please cite the associated paper and the repository as specified in CITATION.cff.

---

Status

This version represents the baseline reference release for all future development, benchmarking, and comparative studies.

Subsequent versions will extend:

• dataset support,
• streaming and near-real-time analysis,
• and prospective validation tooling,
  while preserving interpretability and determinism.

---