Circadian

Welcome to circadian, a computational package for the simulation and analysis of circadian rhythms

Install

circadian can be installed via pip:

sh pip install circadian

Overview

The circadian package implements key mathematical models in the field such as:

• Forger99 - Forger et al. (1999)
• Hannay19 and Hannay19TP - Hannay et al. (2019)
• Jewett99 - Kronauer et al. (1999)

See all the available models at circadian/models.py

Additionally, circadian provides a set of tools for simulating and analzying circadian rhythms:

• Define light schedules using the Light class and feed directly into the models
• Calculate phase response curves using the PRCFinder class
• Generate actograms and phase plots with the circadian.plots module

Finally, the package streamlines the process of reading, processing, and analyzing wereable data via the circadian.readers module.

Check out the documentation for a full overview of the package and its features.

Example

The code below shows how to simulate the circadian rhythm of a shift worker for four different models and visualize the results in an actogram plot

``` python import numpy as np import matplotlib.pyplot as plt import matplotlib.lines as lines from circadian.plots import Actogram from circadian.lights import LightSchedule from circadian.models import Forger99, Jewett99, Hannay19, Hannay19TP

daysnight = 3 daysday = 2 slamshift = LightSchedule.ShiftWork(lux=300.0, dayson=daysnight, daysoff=days_day)

totaldays = 30 time = np.arange(0, 24*totaldays, 0.10) lightvalues = slamshift(time)

fmodel = Forger99() kjmodel = Jewett99() spmmodel = Hannay19() tpmmodel = Hannay19TP()

equilibrationreps = 2 initialconditionsforger = fmodel.equilibrate(time, lightvalues, equilibrationreps) initialconditionskj = kjmodel.equilibrate(time, lightvalues, equilibrationreps) initialconditionsspm = spmmodel.equilibrate(time, lightvalues, equilibrationreps) initialconditionstpm = tpmmodel.equilibrate(time, lightvalues, equilibration_reps) ```

The models are integrated using an explicit Runge-Kutta 4 (RK4) scheme

python trajectory_f = f_model(time, initial_conditions_forger, light_values) trajectory_kj = kj_model(time, initial_conditions_kj, light_values) trajectory_spm = spm_model(time, initial_conditions_spm, light_values) trajectory_tpm = tpm_model(time, initial_conditions_tpm, light_values)

The Dim Light Melatonin Onset (DLMO), an experimental measurement of circadian phase, is calculated for each model by

python dlmo_f = f_model.dlmos() dlmo_kj = kj_model.dlmos() dlmo_spm = spm_model.dlmos() dlmo_tpm = tpm_model.dlmos()

Lastly, the results of the simulation–DLMOs included– are visualized in an Actogram plot from the circadian.plots module

``` python acto = Actogram(time, lightvals=lightvalues, opacity=1.0, smooth=False) acto.plotphasemarker(dlmof, color='blue') acto.plotphasemarker(dlmospm, color='darkgreen') acto.plotphasemarker(dlmotpm, color='red') acto.plotphasemarker(dlmokj, color='purple')

legend

blueline = lines.Line2D([], [], color='blue', label='Forger99') greenline = lines.Line2D([], [], color='darkgreen', label='Hannay19') redline = lines.Line2D([], [], color='red', label='Hannay19TP') purpleline = lines.Line2D([], [], color='purple', label='Jewett99')

plt.legend(handles=[blueline, purpleline, greenline, redline], loc='upper center', bboxtoanchor=(0.5, 1.12), ncol=4) plt.title("Actogram for a Simulated Shift Worker", pad=35) plt.tight_layout() plt.show() ```

Contributing

We welcome contributions to circadian via issues, pull requests, or comments! Please see our contributing guidelines for more information.

Citation

If you find circadian useful, please cite as:

bibtex @software{franco_tavella_2023_8206871, author = {Franco Tavella and Kevin Hannay and Olivia Walch}, title = {{Arcascope/circadian: Refactoring of readers and metrics modules}}, month = aug, year = 2023, publisher = {Zenodo}, version = {v1.0.2}, doi = {10.5281/zenodo.8206871}, url = {https://doi.org/10.5281/zenodo.8206871} }

Head to https://doi.org/10.5281/zenodo.8206871 for more information on the latest release.