circStudio documentation

circStudio is a Python package designed to combine mathematical models of circadian rhythms with the analysis of actigraphy data. Actigraphy data are collected using a small actigraph unit (actimetry sensor), which is worn over a given period of time, yielding time series of locomotor activity, light exposure and skin temperature.

The development of circStudio was motivated by limitations in the supported Python versions of pyActigraphy (tested for python >= 3.7 and python <= 3.9) and by the need for a clearer separation between data processing routines and functions for computing actigraphy-derived metrics. In addition, although a Python package implementing several mathematical models of circadian rhythms already exists (circadian), it supports input data only from a limited number of actimetry sensor brands. Conversely, pyActigraphy supports data ingestion from a broad range o actimetry sensors, but does not offer direct support for circadian rhythm modeling.

circStudio was therefore developed to bridge this gap by combining the data-handling and analysis of pyActigraphy with established mathematical models of circadian rhythms originally implemented in circadian. Furthermore, the numerical solver used to integrate the underlying systems of differential equations was reimplemented to improve address improve numerical stability and robustness when applied to actigraphy data collected in real-world settings.

circStudio originated as part of a Master’s thesis project by Daniel Marques, under the supervision of Nuno Morais and Cátia Reis, and has since evolved into an open-source toolkit for the analysis of actigraphy time series.

Contents:

• Quick setup
  • Requirements
  • Installation
  • (Optional) Installation in an Isolated Environment
  • Verify installation
  • Sample usage
  • Next steps
• Opening and processing actigraphy data
  • Reading actigraphy files using the Raw class directly
  • Reading actigraphy files using adaptor subclasses
  • Retrieving information from Raw instances
  • Next Steps
• Preprocessing actigraphy data
  • 1. Discarding invalid sequences at start and end of the recording
  • 2. Discarding invalid sequences during the recording
  • 2.1. Create inactivity mask for periods of inactivity longer than a given threshold
  • 2.2. Impute missing values from invalid regions of the signal
  • 2.2. Build a custom mask
  • 2.3. Binarizing the signal
  • 2.4. Reset all filters
  • Next steps
• Calculating common activity and light metrics
  • Activity
  • Light
  • Sleep
• Next steps
• Mathematical models of circadian rhythms using light intensity data
  • 1. Create a model instance
  • 2. Obtain initial conditions
  • 3. Visualize results and extract biological quantities
  • 4. Inferring sleep patterns from light trajectories using the Skeldon23 model
  • 5. Entrainment Signal Regularity Index (ESRI)
  • 6. Model Comparison Utility
  • Next steps
• Single-component cosinor
  • Next steps
• Singular Spectrum Analysis (SSA)
  • Import required libraries
  • Theoretical background
• (Multi-fractal)Detrended fluctuation analysis
  • Theoretical background
  • Next steps
• Functional Linear Modelling (FLM)
  • Overview
  • Basis function expansion
  • Gaussian kernel smoothing
• API Reference
• Data I/O
  • Raw
  • BaseLog
  • Mask
• Rest-Activity Metrics
  • IS()
  • ISp()
  • IV()
  • IVp()
  • TAT()
  • TATp()
  • VAT()
  • adat()
  • adatp()
  • daily_profile()
  • daily_profile_auc()
  • get_extremum()
  • get_time_barycentre()
  • kAR()
  • kRA()
  • l5()
  • l5p()
  • light_exposure()
  • lmx()
  • m10()
  • m10p()
  • mlit()
  • mlitp()
  • pAR()
  • pRA()
  • ra()
  • rap()
  • spectral_centroid()
  • summary_stats()
  • temporal_centroid()
• Cosinor Analysis
  • Cosinor
• Mathematical Models
  • Breslow13
  • ESRI
  • Forger
  • HannaySP
  • HannayTP
  • Hilaire07
  • Jewett
  • Model
  • ModelComparer
  • Skeldon23
  • main()
• Sleep Scoring and Diary
  • AoffT()
  • AonT()
  • CSM()
  • Cole_Kripke()
  • Crespo()
  • Crespo_AoT()
  • Oakley()
  • Roenneberg()
  • Roenneberg_AoT()
  • Sadeh()
  • Scripps()
  • SleepMidPoint()
  • SleepProfile()
  • SleepRegularityIndex()
  • SoD()
  • active_bouts()
  • active_durations()
  • fSoD()
  • main_sleep_bouts()
  • sleep_bouts()
  • sleep_durations()
  • waso()
  • SleepDiary