https://github.com/ghammad/pyactigraphy
Python-based open source package for actigraphy data analysis
https://github.com/ghammad/pyactigraphy
actigraphy actimetry circadian open-source physical-activity python rest-activity-rhythms sleep
Last synced: 12 months ago
JSON representation
Python-based open source package for actigraphy data analysis
- Host: GitHub
- URL: https://github.com/ghammad/pyactigraphy
- Owner: ghammad
- License: gpl-3.0
- Created: 2018-12-10T10:15:54.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-03-27T13:42:24.000Z (about 1 year ago)
- Last Synced: 2025-05-16T16:09:18.805Z (12 months ago)
- Topics: actigraphy, actimetry, circadian, open-source, physical-activity, python, rest-activity-rhythms, sleep
- Language: Python
- Homepage: https://ghammad.github.io/pyActigraphy
- Size: 77 MB
- Stars: 146
- Watchers: 5
- Forks: 30
- Open Issues: 30
-
Metadata Files:
- Readme: README.rst
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
Awesome Lists containing this project
README
.. image:: https://img.shields.io/badge/License-GPL%20v3-blue.svg
:target: https://www.gnu.org/licenses/gpl-3.0
.. image:: https://gitlab.com/ghammad/pyActigraphy/badges/master/pipeline.svg?key_text=CI+tests
:target: https://gitlab.com/ghammad/pyActigraphy/commits/master
.. .. image:: https://gitlab.com/ghammad/pyActigraphy/badges/master/coverage.svg
.. :target: https://gitlab.com/ghammad/pyActigraphy/commits/master
.. image:: https://img.shields.io/pypi/v/pyActigraphy.svg
:target: https://pypi.org/project/pyActigraphy
.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.2537920.svg
:target: https://doi.org/10.5281/zenodo.2537920
.. image:: https://bestpractices.coreinfrastructure.org/projects/6933/badge
:target: https://bestpractices.coreinfrastructure.org/projects/6933
.. image:: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg
:target: CODE_OF_CONDUCT.md
**pyActigraphy**
================
Open-source python package for actigraphy and light exposure data visualization and analysis.
This package is meant to provide a comprehensive set of tools to:
* read native actigraphy data files with various formats:
* Actigraph: wGT3X-BT
* CamNtech: Actiwatch 4, 7, L(-Plus) and MotionWatch 8
* Condor Instrument: ActTrust 2
* Daqtix: Daqtometer
* Respironics: Actiwatch 2 and Actiwatch Spectrum (plus)
* Tempatilumi (CE Brasil)
..
* **NEW** read actigraphy data format from the `MESA dataset `_, hosted by the `National Sleep Research Resource `_.
* **NEW** read actigraphy data files produced by the `accelerometer `_ package that can be used to calibrate and convert raw accelerometer data recorded with:
* Axivity: AX3, device used by UK Biobank,
* Activinsights: GENEActiv, used by the Whitehall II study.
..
* **NEW** read light exposure data recorded by the aforementioned devices (when available)
* clean the raw data and mask spurious periods of inactivity
* produce activity profile plots
* visualize sleep agendas and compute summary statistics
* calculate typical wake/sleep cycle-related variables:
* Non-parametric rest-activity variables: IS(m), IV(m), RA
* Activity or Rest fragmentation: kRA, kAR
* Sleep regularity index (SRI)
..
* **NEW** compute light exposure metrics (TAT, :math:`MLit^{500}`, summary statistics, ...)
* automatically detect rest periods using various algorithms (Cole-Kripke, Sadeh, ..., Crespo, Roenneberg)
* perform complex analyses:
* Cosinor analysis
* Detrended Fluctuation Analysis (DFA)
* Functional Linear Modelling (FLM)
* Locomotor Inactivity During Sleep (LIDS)
* Singular Spectrum Analysis (SSA)
* and much more...
Citation
========
We are very pleased to announce that the `v1.0 `_ version of the pyActigraphy package has been published. So, if you find this package useful in your research, please consider citing:
Hammad G, Reyt M, Beliy N, Baillet M, Deantoni M, Lesoinne A, et al. (2021) pyActigraphy: Open-source python package for actigraphy data visualization and analysis. PLoS Comput Biol 17(10): e1009514. https://doi.org/10.1371/journal.pcbi.1009514
pyLight
=======
In the context of the Daylight Academy Project, `The role of daylight for humans `_ and
thanks to the support of its members, Dr. Mirjam Münch and Prof. `Manuel Spitschan `_,
a pyActigraphy module for analysing light exposure data has been developed, **pyLight**.
This module is part of the Human Light Exposure Database and is included in pyActigraphy version `v1.1 `_ and higher.
When using this module, please consider citing:
Hammad, G., Wulff, K., Skene, D. J., Münch, M., & Spitschan, M. (2024). Open-Source Python Module for the Analysis of Personalized Light Exposure Data from Wearable Light Loggers and Dosimeters. LEUKOS, 20(4), 380–389. https://doi.org/10.1080/15502724.2023.2296863
Code and documentation
======================
The pyActigraphy package is open-source and its source code is accessible `online `_.
An online documentation of the package is also available `here `_.
It contains `notebooks `_ illustrating various functionalities of the package. Specific tutorials for the processing and the analysis of light exposure data with pyLight are also available.
Installation
============
For the time being, :code:`pyActigraphy` has been tested for :code:`python>=3.7 & python<=3.9`. Dependencies will be installed automatically.
Before installing python packages, it is often advised to create a virtual environment:
#. Via `venv `_ (Linux/Mac OS)
#. Via `miniconda _` (Linux/Mac OS/Windows)
Installing pyActigraphy (alone)
-----------------------
Within a virtual env, in a Terminal (Linux/Mac OS) or in an Anaconda Prompt (if you installed miniconda/anaconda), simply type:
* For users:
.. code-block:: shell
python -m pip install numba==0.57.1
python -m pip install pyActigraphy
To update the package:
.. code-block:: shell
python -m pip install -U pyActigraphy
* For developers:
.. code-block:: shell
python -m pip install numba==0.57.1
git clone git@github.com:ghammad/pyActigraphy.git
cd pyActigraphy/
git checkout develop
python -m pip install -e .
Installing pyActigraphy+Jupyter (tutorials)
--------------------------------------------------
The `pyActigraphy` package provides a series of tutorial `notebooks `_. These `Jupyter notebooks `_ (file extension: .ipynb) are part of the package but can also be downloaded from the `Github repository `_.
In order to interactively run these tutorials, one needs to install the Jupyter Notebook application.
While users are encouraged to install and tailor these tools to their needs, a simpler one-stop-shop solution consists in using `Anaconda `_.
Instructions:
#. Download and install `Anaconda Distribution `_
#. Via the **Anaconda Prompt** (Windows) or a **Terminal** (Mac OS, Linux):
#. Create a virtual environment:
.. code-block:: shell
conda create -n pyActi39 python=3.9
#. Activate the newly created environment:
.. code-block:: shell
conda activate pyActi39
#. Install the `Numba `_ package which is a dependency of :code:`pyActigraphy`:
.. code-block:: shell
python -m pip install numba==0.57.1
#. Install :code:`pyActigraphy`:
.. code-block:: shell
python -m pip install pyActigraphy
#. Launch the Jupyter Notebook via the Anaconda Navigator:
#. Via the application menu (On Windows)
#. Via a **Terminal** (On Mac OS/Linux only):
.. code-block:: shell
anaconda-navigator
.. warning::
Once the navigator is running, **before** launching the Jupyter Notebook app, select the **pyActi39** environment (instead of :code:`base (root)`)
.. image:: docs/source/img/anaconda-navigator-instructions.png
:width: 600
#. Download the tutorial `notebooks `_:
* `pyActigraphy-Intro.ipynb `_
* `pyActigraphy-Batch.ipynb `_
* `pyActigraphy-Masking.ipynb `_
* `pyActigraphy-SSt-log.ipynb `_
* `pyActigraphy-Sleep-Algorithms.ipynb `_
* `pyActigraphy-Sleep-Diary.ipynb `_
* `pyActigraphy-StateTransitionProb.ipynb `_
#. Via the Jupyter interface, navigate to the tutorial notebooks you previously downloaded and simply launch them.
#. Voilà. Good luck.
Quick start
===========
The following example illustrates how to calculate the interdaily stability
with the pyActigraphy package:
.. code-block:: python
>>> import pyActigraphy
>>> rawAWD = pyActigraphy.io.read_raw_awd('/path/to/your/favourite/file.AWD')
>>> rawAWD.IS()
0.6900175913031027
>>> rawAWD.IS(freq='30min', binarize=True, threshold=4)
0.6245582891144925
>>> rawAWD.IS(freq='1H', binarize=False)
0.5257020914453097
Contributing
============
There are plenty of ways to contribute to this package, including (but not limiting to):
* report bugs (and, ideally, how to reproduce the bug)
* suggest improvements
* improve the documentation
Authors
=======
* **Grégory Hammad** `@ghammad `_ - *Initial and main developer*
* **Mathilde Reyt** `@ReytMathilde `_
See also the list of `contributors `_ who participated in this project.
License
=======
This project is licensed under the GNU GPL-3.0 License - see the `LICENSE `_ file for details
Acknowledgments
===============
* **Aubin Ardois** `@aardoi `_ developed the first version of the MTN class during his internship at the CRC, in May-August 2018.
* The CRC colleagues for their support, ideas, etc.