Yawnalyzer

Documentation from the repository README

Yawnalyzer™ is an open-source Python and Quarto pipeline for cleaning Apple Watch data collected with SensorKit and ResearchKit. It generates preprocessing reports and derives sleep and gait metrics from mobile-health study exports.

The workflow provides scripts for batch cleaning, Quarto quality-control and visualization reports, and joining summary outputs, with configurable paths for local datasets. It is intended for researchers and data analysts working with Apple Watch, digital phenotyping, sleep, gait, and longitudinal sensor data.

• To use this with your own data, first download and extract this repository (or clone it)
• Install required packages using either of the following methods in your virtual environment
  • pip install -r requirement.txt
  • (when in the folder in pyoproject.toml file) uv sync
• Install Quarto CLI
• Use the PathKeeper_template.py file to create a personalized PathKeeper.py file.

• The full documentation is available at the Esinberg Family Depression Center's Health Research Resource Library: https://michmed.org/efdc-kb

• Quarto CLI Download: https://quarto.org/docs/get-started/

This project is a collaboration between the Braley Lab at at the University of Michigan Multiple Sclerosis and Sleep Medicine Divisions, the University of Michigan HomeLab, and the Eisenberg Family Depression Center.

For questions about this study or the science behind the code, please contact Dr. Tiffany Braley, MD, MS, at [email protected].

For technical questions, please contact the project maintainers at: [email protected].

• Tiffany Braley, MD, MS, Holtom-Garrett Family Professor of Neurology, Brailey Lab, University of Michigan Medical School.
• Brandon Labbree (@blabbree), Research Lab Manager, University of Michigan HomeLab
• Gabriel Mongefranco (@gabrielmongefranco), Mobile Data Architect, Mobile Technologies Core, Eisenberg Family Depression Center
• Eisenberg Family Depression Center (@DepressionCenter)

• Apple HealthKit
• Arcascope custom research data collection application
• For a listing of libraries used, please see the source code headers

Yawnalyzer™ is a trademark of the Regents of the University of Michigan. Copyright © 2025-2026 The Regents of the University of Michigan.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/gpl-3.0-standalone.html.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You should have received a copy of the license included in the section entitled "GNU Free Documentation License". If not, see https://www.gnu.org/licenses/fdl-1.3-standalone.html

If you find this repository, code or paper useful for your research, please cite it.

Copyright © 2025-2026 The Regents of the University of Michigan