This repository contains the official implementation of Spectral-Temporal Physiological Consistency (STPC), a novel deep learning regularizer designed to produce trustworthy, physiologically plausible results when denoising and analyzing biomedical time-series signals like ECGs and EEGs.
The core principle is that for AI to be trusted in clinical settings, it must respect the underlying physics of the signals it analyzes. Traditional methods that only minimize amplitude error (like L1 or MSE loss) often produce oversmoothed or unrealistic outputs. STPC solves this by training models to simultaneously preserve three key properties:
- Amplitude Consistency: The signal's voltage levels are correct.
- Temporal-Gradient Consistency: Sharp, high-velocity events (like a QRS spike or seizure onset) are preserved, preventing dangerous blurring.
- Spectral-Magnitude Consistency: The signal's frequency "fingerprint" is maintained, ensuring it has a realistic harmonic profile.
The STPC framework enables robust signal reconstruction and unlocks powerful downstream applications, from improving diagnostic accuracy to learning meaningful neural representations from unlabeled data.
By first cleaning a noisy ECG with an STPC-trained denoiser, we dramatically improve the accuracy of a downstream arrhythmia classifier. The F1-score for detecting critical Ventricular beats increased by 35%, and for Supraventricular beats by 85%.
| Classifier on Raw Noisy Signal | Classifier on STPC-Denoised Signal |
|---|---|
 |
 |
STPC is a general principle, not just an ECG-specific trick. When applied to a noisy EEG signal during a seizure, it flawlessly preserves the sharp, diagnostically critical spike morphology, while a standard L1 model fails.
This is the most powerful application. By training an STPC-regularized model on a self-supervised task (masked signal reconstruction), the model spontaneously learns to differentiate between healthy and pathological brain states without ever seeing a single label. The learned embeddings form distinct clusters, proving the model has discovered a meaningful, high-level "vocabulary" of the brain.
| Spatially Incoherent (L1 Only) vs. Plausible (STPC) | Learned Embeddings Separate Seizure vs. Non-Seizure |
|---|---|
 |
 |
git clone hhttps://github.com/Mohan-CAS-and-hackathons/stpc-eeg.git
cd stpc-eegWe recommend using a virtual environment (e.g., venv or conda).
# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate
# Install all required packages
pip install -r requirements.txtOur experiments use public datasets from PhysioNet. We provide scripts and instructions in the notebooks and tutorials for downloading the necessary files (MIT-BIH Arrhythmia Database, MIT-BIH Noise Stress Test Database, CHB-MIT Scalp EEG Database).
The refactored codebase uses a unified experiment runner for all training and validation tasks. (Note: This is the target structure. Configuration files will be added soon).
To train a model for a specific experiment, use experiments/run_training.py.
Example: Train the self-supervised EEG model
python -m experiments.run_training --experiment eeg_self_supervised --config configs/eeg_self_supervised.yamlTo validate a trained model and generate result plots, use experiments/run_validation.py.
Example: Generate the UMAP plot from the self-supervised model
python -m experiments.run_validation --experiment eeg_self_supervised --model_path models/eeg_denoiser_self_supervised.pthCode
├── assets/ # Images and GIFs for documentation
├── data/ # Placeholder for downloaded datasets
├── models/ # Placeholder for trained model weights (.pth)
├── notebooks/ # Original experimental and exploratory notebooks
├── results/ # Output from validation scripts (plots, matrices)
├── src/
│ ├── stpc/ # Core STPC library (models, losses, data handlers)
│ └── experiments/ # High-level runnable scripts (run_training.py, etc.)
├── tutorials/ # Step-by-step guides for learning the framework
├── app.py # Interactive Streamlit demo application
├── CONTRIBUTING.md # Guidelines for contributors
├── LICENSE # Project license (MIT)
└── README.md # You are here!
This project is officially archived and documented on the Open Science Framework (OSF) and Zenodo.
- OSF Project Page: https://osf.io/kznd9/
We welcome contributions of all kinds! Please see our CONTRIBUTING.md file for detailed guidelines on how to report bugs, propose new features or experiments, and submit pull requests.
This project is licensed under the MIT License - see the LICENSE file for details.