circStudio 1.0.0

A Python toolkit for smoothing, modeling, and analyzing actigraphy time series.

circStudio

circStudio is a Python package for preprocessing, modeling, and analyzing actigraphy time series. It enables users to read activity, light and temperature recordings collected by a wide range of actigraphy devices, and provides conversion modules for commonly used systems (e.g., ActTrust, Actiwatch).

In adition to signal processing and common actigraphy-derived metrics, circStudio incorporates mathematical models of circadian rhythms and algorithms for automatic sleep detection. This enables users not only to characterize rest-activity patterns, but also to simulate circadian phase dynamics, predicting sleep timing, and link actigraphy-derived signals to underlying physiological processes.

Core functionalities

Cleaning and preprocessing raw actigraphy data

• Format-agnostic and flexible Raw class for importing actigraphy recordings

• Dedicated conversion modules for commonly used actigraphy file formats

• Automatic truncation of invalid or incomplete sequences at the beginning and/or end of recordings

• Detection of non-wear periods with optional imputation strategies for missing data

Common actigraphy-derived metrics

Compute standard activity- and light-derived metrics, including:

• Interdaily Stability (IS)

• Intradaily Variability (IV)

• Rest–activity rhythm metrics

• Time Above Threshold (TAT)

• Mean Light Timing (MLiT)

Mathematical models of circadian rhythms

A defining feature of circStudio is the inclusion of several mathematical models of of circadian rhythms. Implemented models include:

• Forger model

• Jewett model

• Hannay Single-Population (HannaySP)

• Hannay Two-Population (HannayTP)

• Hilaire 2007 model

• Skeldon 2023 model

• Breslow 2013 model (melatonin dynamics)

These models enable users to:

• Predict circadian phase (Dim Light Melatonin Onset, DLMO) given a light schedule

• Model melatonin dynamics

• Infer sleep timing and circadian misalignment

• Integrate physiology-driven modeling with actigraphy-derived data

Design philosophy

circStudio unifies two complementary approaches to circadian research: data-driven actigraphy analysis and mechanistic circadian modeling.

The package integrates preprocessing, rhythm quantification, and sleep detection capabilities from pyActigraphy with mathematical models of circadian dynamics provided by the circadian package.

By bridging actigraphy signal processing, rhythm metrics, and physiology-based modeling, circStudio enables researchers to move seamlessly from raw actigraphy recordings to predictions of circadian phase, sleep timing, and circadian misalignment.

Citation

Citation of the original papers:

Hammad G, Reyt M, Beliy N, Baillet M, Deantoni M, Lesoinne A, et al. (2021) pyActigraphy: Open-source python package for actigraphy data visualization and analysis. PLoS Comput Biol 17(10): e1009514. https://doi.org/10.1371/journal.pcbi.1009514

Hammad, G., Wulff, K., Skene, D. J., Münch, M., & Spitschan, M. (2024). Open-Source Python Module for the Analysis of Personalized Light Exposure Data from Wearable Light Loggers and Dosimeters. LEUKOS, 20(4), 380–389. https://doi.org/10.1080/15502724.2023.2296863

Tavella, F., Hannay, K., & Walch, O. (2023). Arcascope/circadian: Refactoring of readers and metrics modules, Zenodo, v1.0.2. https://doi.org/10.5281/zenodo.8206871

License

This project keeps the same license as pyActigraphy, the GNU GPL-3.0 License.

Acknowledgments

Sincere thanks to the following teams:

• The developers of the original pyActigraphy package, whose work laid the foundation for this project (https://github.com/ghammad/pyActigraphy).

• The authors of the circadian package, whose original implementation of light-informed models was crucial for our implementation (https://github.com/Arcascope/circadian).