# Human Circadian Rhythms Simulation Package in Python
Tools for simulating human circadian rhythms for a given light schedule. This package implements models for human circadian rhythms and some tools for visualizing the rhythms in python.
I have (7/2019) updated this library to use Python 3. It should be compatible with python 2 although I won't be
spending much time on ensuring this in the future.
The background for these models can be found in our article published in the Journal of Biological Rhythms:
https://journals.sagepub.com/eprint/CZRXAPFRWA94ZMFDZWWW/full
Some things to note are the differential equations since the code relies heavily on them. In particular, equations such as the Kronauer-Jewett Model are important and you will find this particular equation featured within the code of the twopop_model.py file. Frequently applied equations include:
* Kronauer-Jewett Light Process
* VDP Model
* Clock Neuron Model
* Cauchy (Lorentzian) Distribution
* Least-squares cost function
Enjoy!
Common dependencies/Libraries:
* numpy
* math
* matplotlib
* scipy
* pandas
* statsmodels
* pylab
* numba
Note: The code here uses the most recent and updated versions of these libraries.
## Installing the Package
This repo is now available as a pip3 package. It may be installed by giving the command:
pip3 install HCRSimPY
The dependencies for the install are given in the file requirements.txt. You
can install the dependencies once you have downloaded the requirements.txt file by
giving:
pip3 install -r requirements.txt
That being said it doesn't have any exotic dependencies, most of the libraries will be installed for anyone who does scientific programming in python.
## Model interface
One of the main ideas for this package is to compile a source of human circadian models with their associated parameter values. This field has now grown to the point that many model variants exists and (I think) it is worthwhile to create a simple open-source way to simulate the circadian dynamics using a selection of models.
The available models may be imported (once the package is installed) with the command:
```{python}
from HCRSimPY.models import *
```
The list of models available can be found in the HCRSimPY/models directory in the repo above. Those files are written with the hope that they are readable by someone who has just begun learning python.
Okay great we can import some models, but the idea is to have a uniform input and output to simulate circadian dynamics using one of the available models.
All of the these models are implemented as a python class, with their parameters stored as members of that class. They are all initialized by passing in a time dependent light function.
```{python}
from HCRSimPY.models import *
mymodel=chosenModel(LightTimeSeries)
```
All of these models have the following methods defined for them.....
* setParameters: called when the model is created, used default param values. Can be called to reset parameters to the default easily.
* updateParameters: Given a dictionary of parameters this will update the model parameter values
* getParameters: gives you a dictionary of the current parameter values.
* derv: defines the dynamical system for the ODE solvers.
* integrateModel(tend, initial): integrates the model for t=(0,tend) using the initial
values init.
* integrateModelData((tstart,tend), init, dt=0.1): This can integrate on a given time interval.
* integrateTransients(numdays=50) Integrates using the given light scehdules for a long period. Used to get rid of transients.
* getTS(): Once you have interated the model you can use this to give a pandas dataframe of the solution. This should be organized to be Time,Light_Level,Phase,R plus any other model specific columns needed. R here is the amplitude of the limit cycle oscillator.
The idea to to be able to quickly change between and compare the outputs for different models. ]
Here is an example run for the forger1999 vdp model.
```{python}
#Example run for forger 99 vdp model
import pylab as plt
from HCRSimPY.plots import *
from HCRSimPY.light_schedules import *
from HCRSimPY.models import *
from HCRSimPY.plots import actogram
duration=16.0 #gets 8 hours of sleep
intensity=150.0
wake=6.0
LightFunReg=lambda t: RegularLightSimple(t,intensity,wake,duration)
a=vdp_forger99_model(LightFunReg)
a.integrateModel(24*40)
tsdf=a.getTS()
plt.figure()
ax=plt.gca()
acto=actogram(ax, tsdf) #add an actogram to those axes
plt.title('Forger 1999 VDP Entrainment under Regular Light Conditions')
plt.tight_layout()
plt.show()
```
More examples of using the library are in the Examples directory above.
# Circadian Plots
I have implemented a actogram plotter and stoboscopic plot methods which can be plotted using the getTS method (they use that dataframe).
I would like to build some additional circadian visualizing tools in the future.
# Create your own light schedules
For each of the models you can pass in and defined light schedule which gives light levels in lux. The file LightSchedules has some I have developed but you can build your own from data or otherwise.
For measured data schedules you can pass in an interpolated light function from the data. I have implemented this for several data sets using actiwatch data. You probably will want to smooth the input before interpolating.
# Help wanted
I would welcome any help or corrections people have on creating classes for different human models. I will try to be the most commonly used ones in here first.
# Goals
* I would like to build up a nice database of models and a ensemble method for
simulating from a suite of models.
* I would also like to build a database of fit parameter values for the models
# Development Notes
Virtual environment for dev
* source hcrsim/bin/activate
* pip install -e .
* pip freeze > requirements.txt
* deactivate
# Further Documentation
Dated May/June 2022
* Updated package requirement specifications
* More comments and documentation of software available for light schedule
* Added PEP-8 compliance
* Variable renaming for clarification
* Less code ambiguity
* Restructured code in general
* Imported new packages
* Resolved issues and errors with vdp_hilaire07_model.py
* Updated vdp_hilaire07_model.py
* Resolved issues and errors with test_vdp_simple.py
* Updated test_vdp_simple.py
* Overall code readability enhanced
* Minor syntax errors resolved overall
* Various implementations of differential equations/mathematical models inspected and corrected
* Ex from prev.: Kronauer-Jewett Light Process, Clock Neuron Model, etc...
Raw data
{
"_id": null,
"home_page": "https://github.com/khannay/HCRSimPY",
"name": "HCRSimPY",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Kevin Hannay",
"author_email": "khannay24@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/85/0e/f7a6f86cf2e3901779c41afc35459b6bd5f2492e27f4a32afd80da0fbc9c/HCRSimPY-1.0.7.tar.gz",
"platform": null,
"description": "# Human Circadian Rhythms Simulation Package in Python\n\nTools for simulating human circadian rhythms for a given light schedule. This package implements models for human circadian rhythms and some tools for visualizing the rhythms in python.\n\nI have (7/2019) updated this library to use Python 3. It should be compatible with python 2 although I won't be\nspending much time on ensuring this in the future.\n\nThe background for these models can be found in our article published in the Journal of Biological Rhythms:\n\nhttps://journals.sagepub.com/eprint/CZRXAPFRWA94ZMFDZWWW/full\n\nSome things to note are the differential equations since the code relies heavily on them. In particular, equations such as the Kronauer-Jewett Model are important and you will find this particular equation featured within the code of the twopop_model.py file. Frequently applied equations include:\n\n* Kronauer-Jewett Light Process\n\n* VDP Model\n\n* Clock Neuron Model\n\n* Cauchy (Lorentzian) Distribution\n\n* Least-squares cost function\n\n\n\nEnjoy!\n\nCommon dependencies/Libraries:\n* numpy\n* math\n* matplotlib\n* scipy\n* pandas\n* statsmodels\n* pylab\n* numba\n\n\nNote: The code here uses the most recent and updated versions of these libraries.\n\n\n## Installing the Package\n\nThis repo is now available as a pip3 package. It may be installed by giving the command:\n\npip3 install HCRSimPY\n\nThe dependencies for the install are given in the file requirements.txt. You\ncan install the dependencies once you have downloaded the requirements.txt file by\ngiving:\n\npip3 install -r requirements.txt\n\nThat being said it doesn't have any exotic dependencies, most of the libraries will be installed for anyone who does scientific programming in python.\n\n## Model interface\n\nOne of the main ideas for this package is to compile a source of human circadian models with their associated parameter values. This field has now grown to the point that many model variants exists and (I think) it is worthwhile to create a simple open-source way to simulate the circadian dynamics using a selection of models.\n\nThe available models may be imported (once the package is installed) with the command:\n\n```{python}\nfrom HCRSimPY.models import *\n```\n\nThe list of models available can be found in the HCRSimPY/models directory in the repo above. Those files are written with the hope that they are readable by someone who has just begun learning python.\n\nOkay great we can import some models, but the idea is to have a uniform input and output to simulate circadian dynamics using one of the available models.\n\nAll of the these models are implemented as a python class, with their parameters stored as members of that class. They are all initialized by passing in a time dependent light function.\n\n```{python}\nfrom HCRSimPY.models import *\nmymodel=chosenModel(LightTimeSeries)\n```\n\nAll of these models have the following methods defined for them.....\n\n* setParameters: called when the model is created, used default param values. Can be called to reset parameters to the default easily.\n* updateParameters: Given a dictionary of parameters this will update the model parameter values\n* getParameters: gives you a dictionary of the current parameter values.\n* derv: defines the dynamical system for the ODE solvers.\n* integrateModel(tend, initial): integrates the model for t=(0,tend) using the initial\nvalues init.\n* integrateModelData((tstart,tend), init, dt=0.1): This can integrate on a given time interval.\n* integrateTransients(numdays=50) Integrates using the given light scehdules for a long period. Used to get rid of transients.\n* getTS(): Once you have interated the model you can use this to give a pandas dataframe of the solution. This should be organized to be Time,Light_Level,Phase,R plus any other model specific columns needed. R here is the amplitude of the limit cycle oscillator.\n\nThe idea to to be able to quickly change between and compare the outputs for different models. ]\n\nHere is an example run for the forger1999 vdp model.\n\n```{python}\n#Example run for forger 99 vdp model\n\nimport pylab as plt\n\n\nfrom HCRSimPY.plots import *\nfrom HCRSimPY.light_schedules import *\nfrom HCRSimPY.models import *\nfrom HCRSimPY.plots import actogram\n\n\nduration=16.0 #gets 8 hours of sleep\nintensity=150.0\nwake=6.0\nLightFunReg=lambda t: RegularLightSimple(t,intensity,wake,duration)\n\na=vdp_forger99_model(LightFunReg)\na.integrateModel(24*40)\ntsdf=a.getTS()\n\n\nplt.figure()\nax=plt.gca()\nacto=actogram(ax, tsdf) #add an actogram to those axes\n\nplt.title('Forger 1999 VDP Entrainment under Regular Light Conditions')\nplt.tight_layout()\nplt.show()\n\n```\n\nMore examples of using the library are in the Examples directory above.\n\n# Circadian Plots\n\nI have implemented a actogram plotter and stoboscopic plot methods which can be plotted using the getTS method (they use that dataframe).\n\nI would like to build some additional circadian visualizing tools in the future.\n\n# Create your own light schedules\n\nFor each of the models you can pass in and defined light schedule which gives light levels in lux. The file LightSchedules has some I have developed but you can build your own from data or otherwise.\n\nFor measured data schedules you can pass in an interpolated light function from the data. I have implemented this for several data sets using actiwatch data. You probably will want to smooth the input before interpolating.\n\n# Help wanted\n\nI would welcome any help or corrections people have on creating classes for different human models. I will try to be the most commonly used ones in here first.\n\n# Goals\n\n* I would like to build up a nice database of models and a ensemble method for\nsimulating from a suite of models.\n* I would also like to build a database of fit parameter values for the models\n\n\n# Development Notes\n\nVirtual environment for dev\n\n* source hcrsim/bin/activate\n* pip install -e .\n* pip freeze > requirements.txt\n* deactivate\n\n# Further Documentation\nDated May/June 2022\n\n* Updated package requirement specifications\n* More comments and documentation of software available for light schedule\n* Added PEP-8 compliance\n* Variable renaming for clarification\n* Less code ambiguity\n* Restructured code in general\n\n* Imported new packages\n* Resolved issues and errors with vdp_hilaire07_model.py\n* Updated vdp_hilaire07_model.py\n* Resolved issues and errors with test_vdp_simple.py\n* Updated test_vdp_simple.py\n* Overall code readability enhanced\n* Minor syntax errors resolved overall\n\n* Various implementations of differential equations/mathematical models inspected and corrected\n* Ex from prev.: Kronauer-Jewett Light Process, Clock Neuron Model, etc... \n\n",
"bugtrack_url": null,
"license": "",
"summary": "A package to simulate and analyze human circadian rhythms.",
"version": "1.0.7",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "b6d1adc2d6811548f1e44da7e16c89ae",
"sha256": "33d23c40eb707cef9f67b9d3d500a95b7718285662d09aeb4011429f7d39ae65"
},
"downloads": -1,
"filename": "HCRSimPY-1.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b6d1adc2d6811548f1e44da7e16c89ae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 35057,
"upload_time": "2022-11-30T14:38:56",
"upload_time_iso_8601": "2022-11-30T14:38:56.452946Z",
"url": "https://files.pythonhosted.org/packages/c4/8e/4a13c2ce56320468a0120202a0d6fb5d28b2f2c4eba7df31e818235c22e9/HCRSimPY-1.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "69c95c2e2f96d0a1ca5384b280d7aee0",
"sha256": "41b8a86eb069555816dabf7240e4047ffd6044c84c10b062c52df9392176560c"
},
"downloads": -1,
"filename": "HCRSimPY-1.0.7.tar.gz",
"has_sig": false,
"md5_digest": "69c95c2e2f96d0a1ca5384b280d7aee0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26739,
"upload_time": "2022-11-30T14:38:57",
"upload_time_iso_8601": "2022-11-30T14:38:57.966966Z",
"url": "https://files.pythonhosted.org/packages/85/0e/f7a6f86cf2e3901779c41afc35459b6bd5f2492e27f4a32afd80da0fbc9c/HCRSimPY-1.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-11-30 14:38:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "khannay",
"github_project": "HCRSimPY",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "certifi",
"specs": []
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"2.1.1"
]
]
},
{
"name": "colorclass",
"specs": [
[
"==",
"2.2.2"
]
]
},
{
"name": "contourpy",
"specs": [
[
"==",
"1.0.6"
]
]
},
{
"name": "cycler",
"specs": [
[
"==",
"0.11.0"
]
]
},
{
"name": "docopt",
"specs": [
[
"==",
"0.6.2"
]
]
},
{
"name": "docutils",
"specs": [
[
"==",
"0.19"
]
]
},
{
"name": "flake8",
"specs": [
[
"==",
"6.0.0"
]
]
},
{
"name": "fonttools",
"specs": [
[
"==",
"4.38.0"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.4"
]
]
},
{
"name": "kiwisolver",
"specs": [
[
"==",
"1.4.4"
]
]
},
{
"name": "llvmlite",
"specs": [
[
"==",
"0.39.1"
]
]
},
{
"name": "matplotlib",
"specs": [
[
"==",
"3.6.2"
]
]
},
{
"name": "mccabe",
"specs": [
[
"==",
"0.7.0"
]
]
},
{
"name": "numba",
"specs": [
[
"==",
"0.56.4"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"1.23.5"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"21.3"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"1.5.2"
]
]
},
{
"name": "patsy",
"specs": [
[
"==",
"0.5.3"
]
]
},
{
"name": "Pillow",
"specs": [
[
"==",
"9.3.0"
]
]
},
{
"name": "pip-upgrader",
"specs": [
[
"==",
"1.4.15"
]
]
},
{
"name": "pycodestyle",
"specs": [
[
"==",
"2.10.0"
]
]
},
{
"name": "pyflakes",
"specs": [
[
"==",
"3.0.1"
]
]
},
{
"name": "pyparsing",
"specs": [
[
"==",
"3.0.9"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.8.2"
]
]
},
{
"name": "pytz",
"specs": [
[
"==",
"2022.6"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.28.1"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.9.3"
]
]
},
{
"name": "seaborn",
"specs": [
[
"==",
"0.12.1"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.16.0"
]
]
},
{
"name": "statsmodels",
"specs": [
[
"==",
"0.13.5"
]
]
},
{
"name": "terminaltables",
"specs": [
[
"==",
"3.1.10"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"1.26.13"
]
]
}
],
"lcname": "hcrsimpy"
}
JSON
