Code for: CDDA: A Continuous Depth-Dynamics Analysis Framework for Sleep Stability and Wake Microsleep Burden
Description
This dataset contains the CDDA framework code for analyzing precomputed 3-s SDV / 30-s ORP sleep-depth trajectories. It includes trajectory alignment, feature extraction, adaptive two-state GMM and HMM decoding, CAP A1–A3 validation, and figure-generation scripts. The frozen ANN-SDV front-end is an external dependency (not included). Input: aligned tables of 3-s SDV or 30-s ORP. Output: dynamics indicators, event features, diagnostics, and cohort summaries. Runtime: Python 3.12 (NumPy, SciPy, scikit-learn, hmmlearn, matplotlib).
Files
Steps to reproduce
Steps to reproduce 1. Environment Use Python 3.12 with a virtual environment. python -m venv .venv .venv\Scripts\activate python -m pip install -r requirements.txt 2. Data and external dependency Raw clinical recordings are not included because of privacy and institutional restrictions. Obtain Sleep-EDF Expanded v1.0.0 and CAP Sleep Database v1.0.0 from PhysioNet under their original data-use terms. Obtain local OSA, normal-control, and narcolepsy data under the approved ethics and data-use conditions. Set the required paths before running: $env:CDDA_OSA_DIR="path\to\OSA" $env:CDDA_NORMAL_DIR="path\to\normal" $env:CDDA_CAP_DIR="path\to\capslpdb\1.0.0" $env:CDDA_SLEEP_EDF_DIR="path\to\sleep-edfx\1.0.0" $env:CDDA_NARCOLEPSY_DIR="path\to\narcolepsy\EDF" $env:CDDA_NARCOLEPSY_ORP_DIR="path\to\narcolepsy\ORP" $env:CDDA_ANN_MODEL_PATH="path\to\ann_sdv_best.pt" The frozen ANN-SDV checkpoint is an external dependency and is not distributed with this package. Users must provide an authorized checkpoint when reproducing SDV extraction from raw EEG. 3. Full pipeline from raw recordings Run commands from the package root: python code\01_parse_annotations.py python code\02_build_subject_table.py python code\03_inventory_signals.py python code\04_align_epochs.py python code\05_extract_sdv_orp.py python code\06_qa_trajectories.py python code\07_dynamics_indicators.py python code\08_event_recovery.py 4. Statistical and validation analyses python code\09_osa_normal_stats.py python code\10_cap_a_phase_validation.py python code\11_narcolepsy_orp_distribution.py python code\12_build_manuscript_tables.py python code\13_cycle_rhythm_analysis.py python code\20_incremental_value.py python code\21_partial_incremental_value.py python code\24_quantitative_validation.py python code\25_sdv_complexity.py python code\26_cap_event_ml.py python code\28_gmm_microsleep.py python code\31_hmm_microsleep.py python code\32_cap_model_baseline_ci.py python code\45_gmm_hmm_model_selection.py python code\46_traditional_temporal_baselines.py python code\47_model_complexity_sensitivity.py python code\48_fdr_multiple_comparisons.py python code\49_confidence_intervals.py python code\50_microsleep_run_length_sensitivity.py 5. If starting from derived trajectories Place aligned SDV trajectories in data\trajectories\eeg and ORP trajectories in data\trajectories\orp, then begin at 06_qa_trajectories.py. Analyses 09-13, 24-32, and 45-50 can then be run without the ANN-SDV checkpoint. 6. Figures Run scripts 33-43 for the manuscript figures. The final revised Figure 3 and Figure 4 are generated with: python code\52_figure_effect_forest_terms.py python code\53_figure_gmm_hmm_timeline_terms.py Outputs are written to results\ and figures\revised. Randomized models use seed 42. GMM and HMM settings are defined in the scripts and summarized in Supplementary Table S1. AUROC values represent cohort- or event-level discrimination in this study, not clinical diagnostic performance.