Skip to content

Commit 22dd77b

Browse files
djmarquesdjmarques
committed
upload sources
1 parent 2034cde commit 22dd77b

13 files changed

Lines changed: 45836 additions & 0 deletions

‎.DS_Store‎

2 KB
Binary file not shown.

‎_sources/api.rst‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
API Reference
2+
=============
3+
4+
.. contents:: Table of Contents
5+
:local:
6+
:depth: 2
7+
8+
9+
Data I/O
10+
========
11+
12+
.. automodule:: circstudio.io.base
13+
:members:
14+
:undoc-members:
15+
:show-inheritance:
16+
17+
.. automodule:: circstudio.io.mask
18+
:members:
19+
:undoc-members:
20+
:show-inheritance:
21+
22+
23+
Rest-Activity Metrics
24+
=====================
25+
26+
.. automodule:: circstudio.analysis.metrics.metrics
27+
:members:
28+
:undoc-members:
29+
:show-inheritance:
30+
31+
32+
Cosinor Analysis
33+
================
34+
35+
.. automodule:: circstudio.analysis.cosinor.cosinor
36+
:members:
37+
:undoc-members:
38+
:show-inheritance:
39+
40+
41+
Mathematical Models
42+
===================
43+
44+
.. automodule:: circstudio.analysis.models.math_models
45+
:members:
46+
:undoc-members:
47+
:show-inheritance:
48+
49+
50+
Sleep Scoring and Diary
51+
=======================
52+
53+
.. automodule:: circstudio.analysis.sleep.sleep
54+
:members:
55+
:undoc-members:
56+
:show-inheritance:
57+
58+
.. automodule:: circstudio.analysis.sleep.diary
59+
:members:
60+
:undoc-members:
61+
:show-inheritance:

‎_sources/index.rst‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
.. circStudio documentation master file, created by
2+
sphinx-quickstart on Fri Jul 18 12:57:01 2025.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
circStudio documentation
7+
========================
8+
9+
`circStudio` is a Python package designed to combine mathematical models of circadian rhythms with
10+
the analysis of actigraphy data. Actigraphy data are collected using a small actigraph unit (actimetry
11+
sensor), which is worn over a given period of time, yielding time series of locomotor activity, light
12+
exposure and skin temperature.
13+
14+
The development of `circStudio` was motivated by limitations in the supported Python versions of
15+
`pyActigraphy` (tested for `python >= 3.7` and `python <= 3.9`) and by the need for a clearer
16+
separation between data processing routines and functions for computing actigraphy-derived metrics.
17+
In addition, although a Python package implementing several mathematical models of circadian rhythms
18+
already exists (`circadian`), it supports input data only from a limited number of actimetry sensor
19+
brands. Conversely, `pyActigraphy` supports data ingestion from a broad range o actimetry sensors,
20+
but does not offer direct support for circadian rhythm modeling.
21+
22+
`circStudio` was therefore developed to bridge this gap by combining the data-handling and analysis
23+
of `pyActigraphy` with established mathematical models of circadian rhythms originally implemented in
24+
`circadian`. Furthermore, the numerical solver used to integrate the underlying systems of differential
25+
equations was reimplemented to improve address improve numerical stability and robustness when applied
26+
to actigraphy data collected in real-world settings.
27+
28+
`circStudio` originated as part of a Master's thesis project by Daniel Marques, under the supervision
29+
of Nuno Morais and Cátia Reis, and has since evolved into an open-source toolkit for the analysis of
30+
actigraphy time series.
31+
32+
.. toctree::
33+
:maxdepth: 2
34+
:caption: Contents:
35+
36+
tutorial_0
37+
tutorial_1
38+
tutorial_2
39+
tutorial_3
40+
tutorial_4
41+
tutorial_5
42+
tutorial_6
43+
tutorial_7
44+
tutorial_8
45+
api

‎_sources/notebooks/submarine_project/submarine_analysis.ipynb‎

Lines changed: 8462 additions & 0 deletions
Large diffs are not rendered by default.

‎_sources/tutorial_0.ipynb‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"id": "f8d26bb2-a1e6-4bd5-99dd-20e8e88b7d73",
6+
"metadata": {},
7+
"source": [
8+
"# Quick setup\n",
9+
"\n",
10+
"Welcome to `circStudio`, a Python package for reproducible preprocessing, modeling, and analysis of actigraphy time series in biological rhythm research workflows.\n",
11+
"\n",
12+
"## Requirements\n",
13+
"- Python ≥ 3.12.\n",
14+
"\n",
15+
"You can check your Python version with:"
16+
]
17+
},
18+
{
19+
"cell_type": "markdown",
20+
"id": "c393f203-efd4-47a5-a216-25e0062140dd",
21+
"metadata": {},
22+
"source": [
23+
"```bash\n",
24+
"python --version\n",
25+
"```"
26+
]
27+
},
28+
{
29+
"cell_type": "markdown",
30+
"id": "a7427185-e4f4-49fd-a811-ae6bb37646f0",
31+
"metadata": {},
32+
"source": [
33+
"## Installation\n",
34+
"Install the latest stable version from PyPI:"
35+
]
36+
},
37+
{
38+
"cell_type": "markdown",
39+
"id": "initial_id",
40+
"metadata": {
41+
"ExecuteTime": {
42+
"end_time": "2026-02-18T16:25:05.970483Z",
43+
"start_time": "2026-02-18T16:25:05.967638Z"
44+
}
45+
},
46+
"source": [
47+
"```bash\n",
48+
"pip install circStudio\n",
49+
"```"
50+
]
51+
},
52+
{
53+
"cell_type": "markdown",
54+
"id": "d33bc2ef-477a-43b3-8f9b-25157b4338d1",
55+
"metadata": {},
56+
"source": [
57+
"## (Optional) Installation in an Isolated Environment\n",
58+
"To avoid dependency conflicts and ensure a clean, reproducible setup, install `circStudio` in a dedicated Python environment.\n",
59+
"\n",
60+
"### Using Conda/Miniconda:\n",
61+
"\n",
62+
"```bash\n",
63+
"conda create -n csenv python=3.12 # Create environment (v. 3.12 or 3.13)\n",
64+
"conda activate csenv # Activate environment\n",
65+
"python -m pip install circStudio # Install circStudio\n",
66+
"conda deactivate # Deactivate environment\n",
67+
"```\n",
68+
"\n",
69+
"### Using venv\n",
70+
"```bash\n",
71+
"# MacOS / Linux\n",
72+
"python3 -m venv csenv/ # Create environment\n",
73+
"source csenv/bin/activate # Activate the environment\n",
74+
"python -m pip install circStudio # Install circStudio\n",
75+
"deactivate # Deactivate environment\n",
76+
"\n",
77+
"# Windows (PowerShell)\n",
78+
"PS> py -m venv csenv\\ # Create environment\n",
79+
"PS> csenv\\Scripts\\activate # Activate environment\n",
80+
"PS> python -m pip install circStudio # Install circStudio\n",
81+
"PS> deactivate # Deactivate environment\n",
82+
"```\n",
83+
"\n",
84+
"## Verify installation\n",
85+
"After installation, confirm that `circStudio` can be imported:\n",
86+
"\n",
87+
"```bash\n",
88+
"python -c \"import circstudio; print('circstudio imports')\"\n",
89+
"```\n",
90+
"\n",
91+
"## Sample usage\n",
92+
"The example below illustrates a minimal workflow for loading actigraphy data and computing a basic metric:"
93+
]
94+
},
95+
{
96+
"cell_type": "code",
97+
"execution_count": 10,
98+
"id": "7d40abc1-b24f-4b2e-862c-c2fbc7ca0c0f",
99+
"metadata": {},
100+
"outputs": [
101+
{
102+
"name": "stdout",
103+
"output_type": "stream",
104+
"text": [
105+
"Intradaily variability: 0.56\n"
106+
]
107+
}
108+
],
109+
"source": [
110+
"import pandas as pd\n",
111+
"import circstudio as cs\n",
112+
"import os\n",
113+
"\n",
114+
"# Load sample actigraphy time series\n",
115+
"data_dir = os.path.join(os.path.dirname(cs.__file__), \"data\")\n",
116+
"raw = cs.io.read_atr(os.path.join(data_dir, 'test_sample_atr.txt'))\n",
117+
"\n",
118+
"# Alternative: load a generic actigraphy file using pandas\n",
119+
"# Expected columns: timestamp, activity (and optionally temperature, light)\n",
120+
"#raw = pd.read_csv(\"example_actigraphy.csv\", parse_dates=[\"timestamp\"])\n",
121+
"\n",
122+
"# Compute intradaily variability (IV)\n",
123+
"iv = cs.analysis.IV(data=raw.activity)\n",
124+
"\n",
125+
"print(f\"Intradaily variability: {iv:.2f}\")"
126+
]
127+
},
128+
{
129+
"cell_type": "markdown",
130+
"id": "a48f5b2c-6a9d-4a1d-8675-81a60ba00dca",
131+
"metadata": {},
132+
"source": [
133+
"## Next steps"
134+
]
135+
},
136+
{
137+
"cell_type": "markdown",
138+
"id": "a031c2d9-9de4-4b00-9332-51261969aecb",
139+
"metadata": {},
140+
"source": [
141+
"In the following tutorials, you will learn how to:\n",
142+
"- Use adaptor classes to load common actigraphy file formats.\n",
143+
"- Work directly with the `Raw` class to import and preprocess custom actigraphy data.\n",
144+
"- Compute widely used actigraphy-derived metrics.\n",
145+
"- Perform automatic rest/sleep detection.\n",
146+
"- Apply mathematical models to characterize circadian rhythms and extract mechanistic insights from behavioral time series."
147+
]
148+
}
149+
],
150+
"metadata": {
151+
"kernelspec": {
152+
"display_name": "Python 3 (ipykernel)",
153+
"language": "python",
154+
"name": "python3"
155+
},
156+
"language_info": {
157+
"codemirror_mode": {
158+
"name": "ipython",
159+
"version": 3
160+
},
161+
"file_extension": ".py",
162+
"mimetype": "text/x-python",
163+
"name": "python",
164+
"nbconvert_exporter": "python",
165+
"pygments_lexer": "ipython3",
166+
"version": "3.13.7"
167+
}
168+
},
169+
"nbformat": 4,
170+
"nbformat_minor": 5
171+
}

0 commit comments

Comments
 (0)