# Circadian
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
[](https://arcascope.github.io/circadian/)
[](https://twitter.com/arcascope)
[](https://doi.org/10.5281/zenodo.8206871)
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)](https://doi.org/10.1177/074873099129000867)
- `Hannay19` and `Hannay19TP` - [Hannay et
al. (2019)](https://doi.org/10.1177/0748730419878298)
- `Jewett99` - [Kronauer et
al. (1999)](https://doi.org/10.1177/074873049901400608)
See all the available models at
[circadian/models.py](https://github.com/Arcascope/circadian/blob/main/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](https://arcascope.github.io/circadian/)
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
days_night = 3
days_day = 2
slam_shift = LightSchedule.ShiftWork(lux=300.0, days_on=days_night, days_off=days_day)
total_days = 30
time = np.arange(0, 24*total_days, 0.10)
light_values = slam_shift(time)
f_model = Forger99()
kj_model = Jewett99()
spm_model = Hannay19()
tpm_model = Hannay19TP()
equilibration_reps = 2
initial_conditions_forger = f_model.equilibrate(time, light_values, equilibration_reps)
initial_conditions_kj = kj_model.equilibrate(time, light_values, equilibration_reps)
initial_conditions_spm = spm_model.equilibrate(time, light_values, equilibration_reps)
initial_conditions_tpm = tpm_model.equilibrate(time, light_values, 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, light_vals=light_values, opacity=1.0, smooth=False)
acto.plot_phasemarker(dlmo_f, color='blue')
acto.plot_phasemarker(dlmo_spm, color='darkgreen')
acto.plot_phasemarker(dlmo_tpm, color='red')
acto.plot_phasemarker(dlmo_kj, color='purple')
# legend
blue_line = lines.Line2D([], [], color='blue', label='Forger99')
green_line = lines.Line2D([], [], color='darkgreen', label='Hannay19')
red_line = lines.Line2D([], [], color='red', label='Hannay19TP')
purple_line = lines.Line2D([], [], color='purple', label='Jewett99')
plt.legend(handles=[blue_line, purple_line, green_line, red_line],
loc='upper center', bbox_to_anchor=(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](https://arcascope.github.io/circadian/contributing.html) 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/Arcascope/circadian",
"name": "circadian",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "nbdev jupyter notebook python",
"author": "Arcascope Inc.",
"author_email": "support@arcascope.com",
"download_url": "https://files.pythonhosted.org/packages/fc/3e/499d0004683ff29c4926b66ba04b76abb5eeaaef386e52d5d776130b01e3/circadian-1.0.3.tar.gz",
"platform": null,
"description": "# Circadian\n\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\n[](https://arcascope.github.io/circadian/)\n\n[](https://twitter.com/arcascope)\n[](https://doi.org/10.5281/zenodo.8206871)\n\nWelcome to `circadian`, a computational package for the simulation and\nanalysis of circadian rhythms\n\n## Install\n\n`circadian` can be installed via `pip`:\n\n``` sh\npip install circadian\n```\n\n## Overview\n\nThe `circadian` package implements key mathematical models in the field\nsuch as:\n\n- `Forger99` - [Forger et\n al.\u00a0(1999)](https://doi.org/10.1177/074873099129000867)\n- `Hannay19` and `Hannay19TP` - [Hannay et\n al.\u00a0(2019)](https://doi.org/10.1177/0748730419878298)\n- `Jewett99` - [Kronauer et\n al.\u00a0(1999)](https://doi.org/10.1177/074873049901400608)\n\nSee all the available models at\n[circadian/models.py](https://github.com/Arcascope/circadian/blob/main/circadian/models.py)\n\nAdditionally, `circadian` provides a set of tools for simulating and\nanalzying circadian rhythms:\n\n- Define light schedules using the `Light` class and feed directly into\n the models\n- Calculate phase response curves using the `PRCFinder` class\n- Generate actograms and phase plots with the `circadian.plots` module\n\nFinally, the package streamlines the process of reading, processing, and\nanalyzing wereable data via the `circadian.readers` module.\n\nCheck out the [documentation](https://arcascope.github.io/circadian/)\nfor a full overview of the package and its features.\n\n## Example\n\nThe code below shows how to simulate the circadian rhythm of a shift\nworker for four different models and visualize the results in an\nactogram plot\n\n``` python\nimport numpy as np\nimport matplotlib.pyplot as plt\nimport matplotlib.lines as lines\nfrom circadian.plots import Actogram\nfrom circadian.lights import LightSchedule\nfrom circadian.models import Forger99, Jewett99, Hannay19, Hannay19TP\n\ndays_night = 3\ndays_day = 2\nslam_shift = LightSchedule.ShiftWork(lux=300.0, days_on=days_night, days_off=days_day)\n\ntotal_days = 30\ntime = np.arange(0, 24*total_days, 0.10)\nlight_values = slam_shift(time)\n\nf_model = Forger99()\nkj_model = Jewett99()\nspm_model = Hannay19()\ntpm_model = Hannay19TP()\n\nequilibration_reps = 2\ninitial_conditions_forger = f_model.equilibrate(time, light_values, equilibration_reps)\ninitial_conditions_kj = kj_model.equilibrate(time, light_values, equilibration_reps)\ninitial_conditions_spm = spm_model.equilibrate(time, light_values, equilibration_reps)\ninitial_conditions_tpm = tpm_model.equilibrate(time, light_values, equilibration_reps)\n```\n\nThe models are integrated using an explicit Runge-Kutta 4 (RK4) scheme\n\n``` python\ntrajectory_f = f_model(time, initial_conditions_forger, light_values)\ntrajectory_kj = kj_model(time, initial_conditions_kj, light_values)\ntrajectory_spm = spm_model(time, initial_conditions_spm, light_values)\ntrajectory_tpm = tpm_model(time, initial_conditions_tpm, light_values)\n```\n\nThe Dim Light Melatonin Onset (DLMO), an experimental measurement of\ncircadian phase, is calculated for each model by\n\n``` python\ndlmo_f = f_model.dlmos()\ndlmo_kj = kj_model.dlmos()\ndlmo_spm = spm_model.dlmos()\ndlmo_tpm = tpm_model.dlmos()\n```\n\nLastly, the results of the simulation\u2013DLMOs included\u2013 are visualized in\nan `Actogram` plot from the `circadian.plots` module\n\n``` python\nacto = Actogram(time, light_vals=light_values, opacity=1.0, smooth=False)\nacto.plot_phasemarker(dlmo_f, color='blue')\nacto.plot_phasemarker(dlmo_spm, color='darkgreen')\nacto.plot_phasemarker(dlmo_tpm, color='red')\nacto.plot_phasemarker(dlmo_kj, color='purple')\n# legend\nblue_line = lines.Line2D([], [], color='blue', label='Forger99')\ngreen_line = lines.Line2D([], [], color='darkgreen', label='Hannay19')\nred_line = lines.Line2D([], [], color='red', label='Hannay19TP')\npurple_line = lines.Line2D([], [], color='purple', label='Jewett99')\n\nplt.legend(handles=[blue_line, purple_line, green_line, red_line], \n loc='upper center', bbox_to_anchor=(0.5, 1.12), ncol=4)\nplt.title(\"Actogram for a Simulated Shift Worker\", pad=35)\nplt.tight_layout()\nplt.show()\n```\n\n\n\n# Contributing\n\nWe welcome contributions to circadian via issues, pull requests, or\ncomments! Please see our [contributing\nguidelines](https://arcascope.github.io/circadian/contributing.html) for\nmore information.\n\n# Citation\n\nIf you find `circadian` useful, please cite as:\n\n``` bibtex\n@software{franco_tavella_2023_8206871,\n author = {Franco Tavella and\n Kevin Hannay and\n Olivia Walch},\n title = {{Arcascope/circadian: Refactoring of readers and \n metrics modules}},\n month = aug,\n year = 2023,\n publisher = {Zenodo},\n version = {v1.0.2},\n doi = {10.5281/zenodo.8206871},\n url = {https://doi.org/10.5281/zenodo.8206871}\n}\n```\n\nHead to https://doi.org/10.5281/zenodo.8206871 for more information on\nthe latest release.\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Tools for the simulation and analysis of circadian rhythms",
"version": "1.0.3",
"project_urls": {
"Homepage": "https://github.com/Arcascope/circadian"
},
"split_keywords": [
"nbdev",
"jupyter",
"notebook",
"python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7ffdca7d3f9fd5fd219b6b14bf482eebbfc2d9d865e373b15753787b99c0e10c",
"md5": "4e81f29c3f9831ccab67d28966f546cc",
"sha256": "51d10033f0c9ed92afbd4470fd9ed351f9f1167ea5849598f00ef6aba7eceeff"
},
"downloads": -1,
"filename": "circadian-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e81f29c3f9831ccab67d28966f546cc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 46599,
"upload_time": "2025-08-18T21:41:42",
"upload_time_iso_8601": "2025-08-18T21:41:42.224701Z",
"url": "https://files.pythonhosted.org/packages/7f/fd/ca7d3f9fd5fd219b6b14bf482eebbfc2d9d865e373b15753787b99c0e10c/circadian-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fc3e499d0004683ff29c4926b66ba04b76abb5eeaaef386e52d5d776130b01e3",
"md5": "eb8bd89df17a89bb82878c5de5022d65",
"sha256": "7539603030ad5fb7d1ecdd1b77b968b334480272c1566002ed1d3b069346fce1"
},
"downloads": -1,
"filename": "circadian-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "eb8bd89df17a89bb82878c5de5022d65",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 49937,
"upload_time": "2025-08-18T21:41:47",
"upload_time_iso_8601": "2025-08-18T21:41:47.158013Z",
"url": "https://files.pythonhosted.org/packages/fc/3e/499d0004683ff29c4926b66ba04b76abb5eeaaef386e52d5d776130b01e3/circadian-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 21:41:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Arcascope",
"github_project": "circadian",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "circadian"
}
JSON
