mickynna/causalspec-demo

CausalSpec: Causal Effect Estimation of Sleep Conditions on Cardiovascular Disease Risk

A clinical decision support tool that estimates individualized causal effects of sleep conditions on cardiovascular disease (CVD) risk using polysomnography (PSG) recordings and clinical confounders.

Overview

CausalSpec combines continuous wavelet transform (CWT) spectrograms with an identifiable variational autoencoder (iVAE) and DragonNet architecture to estimate conditional average treatment effects (CATE) from overnight sleep recordings. The model was trained on 5,791 subjects from the Sleep Heart Health Study (SHHS) with 15-year cardiovascular follow-up.

Sleep Conditions Assessed

How It Works

1. 1.Upload a PSG recording in EDF format (6 channels: EEG C3/C4, EMG, ECG, SaO2, Airflow)
2. 2.Enter patient clinical information (10 confounders: age, sex, race, BMI, blood pressure, smoking status, diabetes history, hypertension, cholesterol)
3. 3.Run inference — the app extracts CWT spectrograms, encodes them via iVAE conditioned on clinical confounders, and estimates the causal effect of each sleep condition on CVD risk
4. 4.View results — calibrated CATE estimates with risk gauges, population histograms, and clinical recommendations

Model Architecture

PSG (6-ch EDF) --> CWT Spectrograms (Morlet, 64 scales, 0.5-45 Hz)
                        |
                        v
              Causal Encoder (iVAE)  <-- 10 Clinical Confounders
                        |
                        v
                  Latent Space (z_c, z_t, z_y)
                        |
                        v
                DragonNet CATE Head --> Raw CATE
                        |
                        v
              IPW Recalibration --> Calibrated CATE (percentage points)

Repository Structure

causalspec-demo/
  app.py                 # Streamlit application
  requirements.txt       # Python dependencies
  checkpoints/           # Trained model weights (.pt)
  models/                # Model architecture definitions
    causalspec.py        #   Main CausalSpec model
    causal_encoder.py    #   iVAE encoder
    cate_estimator.py    #   DragonNet CATE head
  data/
    dataset.py           #   CWT scalogram extraction
  results/               # Calibrated CATE distributions (population reference)
  utils/
    edf_to_scalogram.py  #   EDF preprocessing pipeline

Local Setup

git clone https://github.com/mickynnamdi/causalspec-demo.git
cd causalspec-demo
pip install -r requirements.txt
streamlit run app.py

Requirements

• —Python 3.9+
• —PyTorch (CPU sufficient for inference)
• —Streamlit
• —PyWavelets, pyedflib, scipy, plotly

Citation

If you use CausalSpec in your research, please cite:

@article{causalspec2026,
  title={CausalSpec: Causal Effect Estimation of Sleep Conditions on Cardiovascular Disease Risk from Polysomnography},
  journal={npj Digital Medicine},
  year={2026}
}

Disclaimer

For research purposes only. This tool is not a substitute for clinical judgment. All estimates are derived from observational data and should be interpreted alongside standard clinical assessment.

License

MIT