SleePyPhases: A Workflow Framework for Sleep Data Harmonization, Analysis and Machine Learning - Ehrlich, Franz; Bäcker, Sara; Schmidt, Martin; Malberg, Hagen; Sedlmayr, Martin; Goldammer, Miriam (medRxiv, 2026)
Data-driven sleep research relies on polysomnography data from various public repositories and vendor systems. Yet the lack of standardized access methods creates substantial barriers to multi-dataset research, method reuse, and reproducibility. We present SleePyPhases, an open-source Python framework providing unified access to multiple sleep data repositories. It offers integrated data harmonization, configuration-based preprocessing, and the development of machine learning pipelines. The framework unifies channel naming, annotation semantics, and data formats across several public repositories (including SHHS, MESA, MrOS, PhysioNet, and SleepEDF) and commercial vendor formats (Philips Alice and Somnomedics Domino). We validated the framework by reproducing five published sleep analysis studies covering diverse datasets, sleep scoring tasks (sleep staging, arousal, leg movement, respiratory event detection), preprocessing methods (signal preprocessing and spectrograms), machine learning methods (supervised and unsupervised learning), and model architectures (convolutional, recurrent, and transformer networks). Four reproductions achieved near-identical results, confirming data fidelity and methodological flexibility. SleePyPhases is open-source and provides a foundation for reproducible sleep research, enabling researchers to focus on scientific questions rather than data infrastructure.Competing Interest StatementThe authors have declared no competing interest.Funding StatementYesAuthor DeclarationsI confirm all relevant ethical guidelines have been followed, and any necessary IRB and/or ethics committee approvals have been obtained.YesThe details of the IRB/oversight body that provided approval or exemption for the research described are given below:This study did not require Institutional Review Board approval because it involved secondary analysis of publicly available, de-identified data.I confirm that all necessary patient/participant consent has been obtained and the appropriate institutional forms have been archived, and that any patient/participant/sample identifiers included were not known to anyone (e.g., hospital staff, patients or participants themselves) outside the research group so cannot be used to identify individuals.YesI understand that all clinical trials and any other prospective interventional studies must be registered with an ICMJE-approved registry, such as ClinicalTrials.gov. I confirm that any such study reported in the manuscript has been registered and the trial registration ID is provided (note: if posting a prospective study registered retrospectively, please provide a statement in the trial ID field explaining why the study was not registered in advance).YesI have followed all appropriate research reporting guidelines, such as any relevant EQUATOR Network research reporting checklist(s) and other pertinent material, if applicable.YesAll source code is made available under the MIT License on GitLab: - **SleePyPhases Framework**: (https://gitlab.com/sleep-is-all-you-need/SleePyPhases) - Main framework implementation - **Sleep Harmonizer**: (https://gitlab.com/sleep-is-all-you-need/sleep-harmonizer) - PSG data harmonization plugin - **Reproduction Studies**: (https://gitlab.com/sleep-is-all-you-need/reproduce) - All reproduction experiments as sub-projects - **pyPhases Core**: (https://gitlab.com/sleep-is-all-you-need/pyphases) - Core pyPhases framework and all related projects including pyPhasesRecordLoader and dataset-specific record loaders (SHHS, MESA, MrOS, etc.) The SHHS, MESA and MrOS datasets for validating the framework are available from the National Sleep Research Resource website (https://sleepdata.org/datasets), while the PhysioNet 2018 and Sleep-EDF datasets are available from Physionet (https://physionet.org/). https://physionet.org/ https://sleepdata.org/datasets https://gitlab.com/sleep-is-all-you-need/SleePyPhases https://gitlab.com/sleep-is-all-you-need/sleep-harmonizer https://gitlab.com/sleep-is-all-you-need/reproduce https://gitlab.com/sleep-is-all-you-need/pyphases