Skip to content

Commit f30cfa0

Browse files
committed
document app and preprocessing
1 parent 3e9a306 commit f30cfa0

6 files changed

Lines changed: 1688 additions & 532 deletions

File tree

‎.DS_Store‎

2 KB
Binary file not shown.

‎app/.DS_Store‎

4 KB
Binary file not shown.

‎app/app.py‎

Lines changed: 140 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
1-
"""circStudio Shiny app - interactive actigraphy analysis.
1+
"""
2+
circStudio Shiny web app
3+
-------------------------
4+
Each analysis tab is a Shiny module in its own file in the modules package. This file
5+
assembles them into a single Shiny app and defines the per-session reactive state passed
6+
to every module.
7+
8+
Each analysis page has two parts:
9+
1. A ``*_ui``function, which defines what the user sees in the browser.
10+
2. A ``*_server``function, which defines what happens when the user uploads data, clicks
11+
buttons, changes parameters, or requests plots.
212
3-
Entry point that assembles every analysis tab as a Shiny *module*. Launch with::
13+
Launch with::
414
515
cd /path/to/circStudio
616
pip install -e src/
@@ -10,54 +20,95 @@
1020
The three top-level reactive values (``rv_single``, ``rv_batch``, ``rv_mode``)
1121
plus a shared ``rv_active_subject`` are created per session and threaded into
1222
each module so the analysis tabs always operate on the active recording.
13-
"""
1423
15-
from __future__ import annotations
24+
Data flow
25+
----------
26+
The app keeps four shared reactive (rv) values per user session:
27+
28+
``rv_single``
29+
Holds one uploaded actigraphy file, i.e., a ``Raw``object.
30+
31+
``rv_batch``
32+
Holds a batch collection when several a directory with several recordings
33+
is specified.
34+
35+
``rv_mode``
36+
Either "single" or "batch", depending on whether the user uploaded a single
37+
recording or specified a directory with several recordings.
38+
39+
``rv_active_subject```
40+
In batch mode, stores which subject is currently selected for analysis.
41+
42+
These values are passed into the modlules so that all tabsanalyse the same currently
43+
active recording or subject.
44+
"""
45+
# ---------------------------------------------------------------------------
46+
# Project directory structure
47+
# ---------------------------------------------------------------------------
48+
# circStudio/
49+
# ├── app/
50+
# │ ├── app.py
51+
# │ ├── modules/
52+
# │ └── www/
53+
# └── src/
54+
# └── circstudio/
55+
#
56+
# The code below constructs this structure from the location of app.py
57+
# ---------------------------------------------------------------------------
1658

17-
import sys
1859
from pathlib import Path
60+
from import_paths import _add_import_path
61+
62+
# Absolute path to this app.py file (Path(__file__) == path to this file)
63+
_this_file = Path(__file__).resolve()
64+
65+
# Directory containing this app.py file (app/)
66+
app_dir = _this_file.parent
1967

20-
# Make ``utils`` and the ``modules`` package importable regardless of CWD.
21-
APP_DIR = Path(__file__).resolve().parent
22-
sys.path.insert(0, str(APP_DIR))
68+
# Project (circStudio/) directory
69+
_project_dir = app_dir.parent
2370

24-
# Also make the bundled ``circstudio`` package importable straight from
25-
# ``src/`` so the app runs even when circStudio was not pip-installed.
26-
_SRC_DIR = APP_DIR.parent / "src"
27-
if _SRC_DIR.is_dir():
28-
sys.path.insert(0, str(_SRC_DIR))
71+
# Source code directory containing the circStudio package
72+
src_dir = _project_dir / "src"
2973

74+
# Put app/ and src/ on the import path so `modules`, `utils`, and `circstudio` resolve
75+
_add_import_path(app_dir)
76+
_add_import_path(src_dir)
77+
78+
# HTMLDependency is used to include a custom CSS theme for the app
3079
from htmltools import HTMLDependency # noqa: E402
80+
81+
# Shiny core imports:
82+
# - App: application object
83+
# - reactive: reactive values/effects/calculations
84+
# - ui: user interface constructors
3185
from shiny import App, reactive, ui # noqa: E402
3286

87+
# Import modules for each analysis tab. Each module has a *_ui and *_server function
3388
from modules.upload import upload_ui, upload_server # noqa: E402
3489
from modules.preprocessing import preprocessing_ui, preprocessing_server # noqa: E402
35-
from modules.batch_overview import ( # noqa: E402
36-
batch_overview_ui,
37-
batch_overview_server,
38-
)
39-
from modules.daily_profile import ( # noqa: E402
40-
daily_profile_ui,
41-
daily_profile_server,
42-
)
90+
from modules.batch_overview import batch_overview_ui, batch_overview_server # noqa: E402
91+
from modules.daily_profile import daily_profile_ui, daily_profile_server # noqa: E402
4392
from modules.sleep import sleep_ui, sleep_server # noqa: E402
4493
from modules.cosinor import cosinor_ui, cosinor_server # noqa: E402
4594
from modules.lids import lids_ui, lids_server # noqa: E402
4695
from modules.fractal import fractal_ui, fractal_server # noqa: E402
4796
from modules.flm import flm_ui, flm_server # noqa: E402
4897
from modules.ssa import ssa_ui, ssa_server # noqa: E402
49-
from modules.circ_models import ( # noqa: E402
50-
circ_models_ui,
51-
circ_models_server,
52-
)
98+
from modules.circ_models import circ_models_ui, circ_models_server # noqa : E402
5399
from modules.llm_chat import llm_chat_ui, llm_chat_server # noqa: E402
54100

101+
# ---------------------------------------------------------------------------
102+
# Styling
103+
# ---------------------------------------------------------------------------
104+
# This links the custom CSS file located in app/www/theme.css.
55105
_THEME_DEP = HTMLDependency(
56106
name="circstudio-theme",
57107
version="1.0.0",
58108
head='<link rel="stylesheet" href="theme.css">',
59109
)
60110

111+
# Build the main app navigation bar, with one tab for each analysis module
61112
app_ui = ui.page_navbar(
62113
ui.nav_panel("Data Upload", upload_ui("upload")),
63114
ui.nav_panel("Preprocessing", preprocessing_ui("preprocess")),
@@ -76,31 +127,77 @@
76127
header=_THEME_DEP,
77128
)
78129

79-
80130
def server(input, output, session):
81-
# Per-session reactive state.
82-
rv_single = reactive.Value(None) # holds a single Raw object
83-
rv_batch = reactive.Value(None) # holds a BatchCollection
84-
rv_mode = reactive.Value("single") # "single" | "batch"
85-
rv_active_subject = reactive.Value(None) # global subject (batch mode)
86-
87-
upload_server("upload", rv_single, rv_batch, rv_mode)
88-
preprocessing_server("preprocess", rv_single, rv_batch, rv_mode, rv_active_subject)
89-
batch_overview_server("batch", rv_batch, rv_active_subject)
90-
91-
for sid, srv in (
131+
# -----------------------------------------------------------------------
132+
# Per-session reactive state
133+
# -----------------------------------------------------------------------
134+
# Reactive values are containers that notify downstream code when their
135+
# contents change. For example, when a user uploads a new recording, tabs
136+
# that depend on that recording can automatically update
137+
138+
# Holds a single ``Raw``object
139+
rv_single = reactive.Value(None)
140+
141+
# Holds a batch collection of recordings
142+
rv_batch = reactive.Value(None)
143+
144+
# Either "single" or "batch"
145+
rv_mode = reactive.Value("single")
146+
147+
# Current subject in batch mode
148+
rv_active_subject = reactive.Value(None)
149+
150+
# -----------------------------------------------------------------------
151+
# Connect each tab's server to the shared reactive state. The following
152+
# four variables constitute the app's shared memory:
153+
#
154+
# rv_single: single loaded actigraphy recording (single mode)
155+
# rv_batch: batch collection of recordings (batch mode)
156+
# rv_mode: "single" or "batch"
157+
# rv_active_subject: current subject in batch mode
158+
#
159+
# When one tab updates one, the others will react automatically.
160+
# -----------------------------------------------------------------------
161+
162+
# The loading module does not neeed information about the selected subject
163+
upload_server(
164+
"upload",
165+
rv_single,
166+
rv_batch,
167+
rv_mode
168+
)
169+
170+
# The preprocessing module needs information on the selected subject
171+
preprocessing_server(
172+
"preprocess",
173+
rv_single,
174+
rv_batch,
175+
rv_mode,
176+
rv_active_subject
177+
)
178+
179+
# The batch module onlyb requires information about the collection
180+
# And selected subject
181+
batch_overview_server(
182+
"batch",
183+
rv_batch,
184+
rv_active_subject
185+
)
186+
187+
# All remaining modules take the same four values, set them up in a loop
188+
for tab_id, server_func in (
92189
("daily", daily_profile_server),
93190
("sleep", sleep_server),
94191
("cosinor", cosinor_server),
95192
("lids", lids_server),
96193
("fractal", fractal_server),
97194
("flm", flm_server),
98195
("ssa", ssa_server),
196+
("circ", circ_models_server),
197+
("chat", llm_chat_server)
99198
):
100-
srv(sid, rv_single, rv_batch, rv_mode, rv_active_subject)
101-
102-
circ_models_server("circ", rv_single, rv_batch, rv_mode, rv_active_subject)
103-
llm_chat_server("chat", rv_single, rv_batch, rv_mode, rv_active_subject)
104-
199+
server_func(tab_id, rv_single, rv_batch, rv_mode, rv_active_subject)
105200

106-
app = App(app_ui, server, static_assets=APP_DIR / "www")
201+
# Assemble the Shiny app from the UI layout and server logic
202+
# Serve static files (CSS) from app/www
203+
app = App(app_ui, server, static_assets=app_dir / "www")

‎app/import_paths.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
import sys
2+
from pathlib import Path
3+
4+
def _add_import_path(folder: Path) -> None:
5+
"""
6+
Add a local folder to Python's import search path.
7+
8+
Parameters
9+
----------
10+
path:
11+
Folder that should be search when importing Python modules.
12+
13+
Notes
14+
-----
15+
``sys.path.insert(0, ...)`` puts the folder at the beginning of the
16+
search path, so that local modules are found before any installed packages.
17+
"""
18+
if folder.is_dir():
19+
sys.path.insert(0, str(folder))

0 commit comments

Comments
 (0)