Introducing circStudio, a Python package for preprocessing, analyzing and modeling actigraphy data

The paper introduces circStudio, a unified Python package that integrates preprocessing, metric calculation, and mathematical modeling of actigraphy data to streamline the analysis of circadian rhythms and facilitate reproducible research in sleep science and digital health.

The Gist

Imagine you are trying to understand the rhythm of a person's life—when they sleep, when they are active, and how their internal "body clock" is ticking. Scientists use a special wristband called an actigraph to record this data 24/7. It's like a tiny, unobtrusive spy that watches how much you move and how much light you see.

However, until now, trying to make sense of this data has been like trying to cook a gourmet meal using tools scattered across three different kitchens. You might have one tool to clean the vegetables (preprocessing), another to chop them (calculating metrics), and a third to bake the cake (mathematical modeling). If you wanted to do all three, you had to constantly switch kitchens, translate your ingredients, and write your own recipes. It was messy, slow, and prone to errors.

Enter circStudio: The "All-in-One Kitchen" for Body Clocks.

This new Python software package is like a super-chef's workstation that brings everything under one roof. Here is how it works, using simple analogies:

1. The Universal Adapter (The "Universal Charger")

Different wristbands (ActiGraph, ActTrust, etc.) speak different "languages" and save data in different file formats. It's like having phones with different charging ports.

• What circStudio does: It comes with a set of "adapters" (called adaptors). You plug in your specific file, and circStudio instantly translates it into a standard format that everyone understands. You don't need to know the secret language of the device; circStudio does the translation for you.

2. The Data Janitor (Preprocessing)

Raw data from these wristbands is often messy. It might have gaps (when the watch fell off), weird spikes (when you bumped it), or extra noise at the start and end.

• What circStudio does: Think of this as a smart janitor. It can:
  • Cut the trash: Remove the messy start and end of the recording.
  • Patch the holes: If data is missing for an hour, it guesses what likely happened based on your pattern from other days (like filling in a missing puzzle piece).
  • Smooth the bumps: It can smooth out extreme spikes so the data looks like a gentle wave rather than a jagged mountain range.

3. The Metric Calculator (The "Scoreboard")

Once the data is clean, scientists want to know specific things: "How consistent is this person's sleep?" or "How strong is their daily rhythm?"

• What circStudio does: It has a built-in scoreboard that instantly calculates these scores.
  • Sleep Regularity Index (SRI): How much does your sleep schedule change from day to day? (Are you a robot or a chaotic artist?)
  • Relative Amplitude (RA): How big is the difference between your most active hours and your least active hours? (A big difference means a strong rhythm; a small difference means a weak one.)

4. The Crystal Ball (Mathematical Modeling)

This is the most magical part. Scientists want to predict how a person's internal body clock would react to different light schedules.

• What circStudio does: It uses complex math (differential equations) to simulate the body's internal engine.
  • Imagine the body clock as a grandfather clock. If you shine a flashlight (light) at it, the clock's gears shift.
  • circStudio can take your light data and run a simulation to predict exactly when your body will produce melatonin (the sleep hormone) or when you will feel sleepy. It can even predict "sleep pressure"—how tired you feel as the day goes on.
  • It includes several different "engine models" (like the Forger model or the Hannay model), giving researchers different ways to look at the same problem.

Real-World Example: The Submarine Study

The authors tested this on a group of people living on a submarine. In a submarine, there is no sun, and people work in shifts, which messes up their body clocks.

• The Question: "Does having a messy sleep schedule (low SRI) make the body clock weaker (low RA)?"
• The Result: Using circStudio, they quickly processed the data and found a clear link: yes, people with irregular sleep had weaker body rhythms. Without this tool, this analysis would have taken weeks of manual coding; with it, it was a smooth, automated workflow.

Why Should You Care?

Before circStudio, researchers had to be expert programmers just to analyze sleep data. Now, it's like having a Swiss Army Knife for circadian biology.

• For Scientists: It saves time and reduces errors, allowing them to focus on the science rather than the coding.
• For the Future: It helps build better sleep apps, improves shift-work schedules for nurses and pilots, and helps us understand how light pollution affects our health.

In short, circStudio takes the chaotic, messy data of our daily lives and turns it into a clear, readable story about how our bodies tick.

Technical Summary

Based on the provided preprint, here is a detailed technical summary of the circStudio paper.

1. Problem Statement

Actigraphy is a widely used, non-invasive method for monitoring behavioral rhythms (locomotor activity, light exposure, temperature) in real-world conditions. However, the current software landscape for analyzing this data presents significant challenges:

• Fragmentation: Essential workflows—preprocessing, metric calculation (e.g., sleep regularity), and mathematical modeling of circadian rhythms—are often distributed across separate, incompatible software packages.
• Interoperability Issues: Moving between tools (e.g., from pyActigraphy for preprocessing to circadian for modeling) requires substantial additional programming effort and data conversion.
• Proprietary Limitations: Many actigraphy devices rely on closed-source, vendor-specific software that restricts analytical flexibility and hinders reproducibility.
• Modeling Constraints: Existing Python packages for circadian modeling (like circadian) often struggle with noisy light schedules or realistic exposure patterns, failing to compute state variables accurately.

2. Methodology and Architecture

circStudio is introduced as a unified Python package designed to bridge these gaps. It is built upon the pyActigraphy codebase but features a redesigned architecture to improve flexibility and modularity.

• Core Architecture:

  • io Module: Handles file input/output, preprocessing, and data cleaning. It utilizes adaptor classes to convert various proprietary file formats (e.g., ActTrust, AWD) into a standardized internal format.
  • analysis Module: Contains standalone functions for data analysis, metric computation, and mathematical modeling.
  • Decoupling: Unlike pyActigraphy, where metrics are often tied to specific classes, circStudio separates the Raw class (responsible for signal preprocessing) from analysis functions. This allows users to apply circStudio metrics to custom time series (e.g., peripheral temperature) or custom preprocessing pipelines.

• Key Functionalities:

  • Preprocessing: Includes masking invalid data (start/end of recording, inactivity periods), imputation of missing values (using mean values from corresponding times across days), binarization, and smoothing (e.g., Scott's method).
  • Metric Calculation: Computes standard actigraphy variables such as Interdaily Stability (IS), Sleep Regularity Index (SRI), Relative Amplitude (RA), and M10 (activity during the 10 most active hours).
  • Mathematical Modeling: Integrates circadian models from the Arcascope circadian package. Supported models include:
    • Forger, Jewett, HannaySP, HannayTP: Based on Van der Pol oscillators.
    • Hilaire07: Incorporates non-photic input and sleep schedules (inferred via Roenneberg or Crespo algorithms).
    • Breslow13: Simulates melatonin trajectories across physiological compartments (pineal, plasma, exogenous).
    • Skeldon23: A hybrid model predicting sleep pressure with feedback between continuous state variables and discrete sleep/wake switching.
  • Advanced Analysis: Includes Cosinor analysis, Singular Spectrum Analysis (SSA), Detrended Fluctuation Analysis (DFA), and Functional Linear Modeling.

3. Key Contributions

• Unified Workflow: Provides a single framework to move from raw wearable data to physiologically interpretable circadian outputs, eliminating the need to switch between multiple packages.
• Enhanced Modeling Robustness: By integrating Arcascope models with robust preprocessing tools, circStudio enables the simulation of circadian dynamics under realistic, noisy light exposure conditions that previously caused failures in other tools.
• Flexibility and Extensibility: The separation of the Raw class from analysis functions allows researchers to implement custom preprocessing and apply standard metrics to diverse biological time series.
• Open-Source Ecosystem: Built on Python, it supports multiple file formats via adaptors and offers extensive documentation, tutorials, and a GitHub repository for community contributions.

4. Results and Validation

The authors validated the package through a practical case study involving submarine mission data:

• Objective: To investigate the relationship between sleep regularity and circadian rhythm robustness in a military submarine environment.
• Process: The team iterated through raw actigraphy files, preprocessed the data, and computed SRI, Relative Amplitude (RA), and L5 (average activity during the 5 least active hours).
• Findings:
  • A moderate positive correlation was found between SRI and RA ($\rho = 0.422, p = 0.025$).
  • A negative correlation was observed between SRI and L5 ($\rho = -0.514, p = 0.025$).
• Interpretation: These results support the hypothesis that reduced sleep regularity is associated with diminished circadian amplitude, likely mediated by increased nocturnal activity. This demonstrates the package's ability to rapidly generate hypothesis-driven insights from complex real-world datasets.

5. Significance and Future Directions

• Scientific Impact: circStudio lowers the barrier to entry for researchers in chronobiology, sleep science, and digital health by providing research-grade, reproducible tools in a single, accessible package.
• Reproducibility: By standardizing preprocessing and modeling steps, it addresses the issue of non-reproducible results caused by reliance on proprietary, closed-source software.
• Future Roadmap:
  • Implementation of automatic algorithms to detect and remove non-wear periods.
  • Potential backporting of new functionalities to the original pyActigraphy package.
  • Development of a broader toolkit for general biological time series analysis.
  • Creation of a Graphical User Interface (GUI) to further enhance accessibility for non-programmers.

In summary, circStudio represents a significant step forward in the computational analysis of circadian rhythms, successfully unifying data preprocessing, metric extraction, and complex mathematical modeling into a cohesive, open-source Python ecosystem.