|
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. |
2 | 12 |
|
3 | | -Entry point that assembles every analysis tab as a Shiny *module*. Launch with:: |
| 13 | +Launch with:: |
4 | 14 |
|
5 | 15 | cd /path/to/circStudio |
6 | 16 | pip install -e src/ |
|
10 | 20 | The three top-level reactive values (``rv_single``, ``rv_batch``, ``rv_mode``) |
11 | 21 | plus a shared ``rv_active_subject`` are created per session and threaded into |
12 | 22 | each module so the analysis tabs always operate on the active recording. |
13 | | -""" |
14 | 23 |
|
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 | +# --------------------------------------------------------------------------- |
16 | 58 |
|
17 | | -import sys |
18 | 59 | 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 |
19 | 67 |
|
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 |
23 | 70 |
|
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" |
29 | 73 |
|
| 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 |
30 | 79 | 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 |
31 | 85 | from shiny import App, reactive, ui # noqa: E402 |
32 | 86 |
|
| 87 | +# Import modules for each analysis tab. Each module has a *_ui and *_server function |
33 | 88 | from modules.upload import upload_ui, upload_server # noqa: E402 |
34 | 89 | 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 |
43 | 92 | from modules.sleep import sleep_ui, sleep_server # noqa: E402 |
44 | 93 | from modules.cosinor import cosinor_ui, cosinor_server # noqa: E402 |
45 | 94 | from modules.lids import lids_ui, lids_server # noqa: E402 |
46 | 95 | from modules.fractal import fractal_ui, fractal_server # noqa: E402 |
47 | 96 | from modules.flm import flm_ui, flm_server # noqa: E402 |
48 | 97 | 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 |
53 | 99 | from modules.llm_chat import llm_chat_ui, llm_chat_server # noqa: E402 |
54 | 100 |
|
| 101 | +# --------------------------------------------------------------------------- |
| 102 | +# Styling |
| 103 | +# --------------------------------------------------------------------------- |
| 104 | +# This links the custom CSS file located in app/www/theme.css. |
55 | 105 | _THEME_DEP = HTMLDependency( |
56 | 106 | name="circstudio-theme", |
57 | 107 | version="1.0.0", |
58 | 108 | head='<link rel="stylesheet" href="theme.css">', |
59 | 109 | ) |
60 | 110 |
|
| 111 | +# Build the main app navigation bar, with one tab for each analysis module |
61 | 112 | app_ui = ui.page_navbar( |
62 | 113 | ui.nav_panel("Data Upload", upload_ui("upload")), |
63 | 114 | ui.nav_panel("Preprocessing", preprocessing_ui("preprocess")), |
|
76 | 127 | header=_THEME_DEP, |
77 | 128 | ) |
78 | 129 |
|
79 | | - |
80 | 130 | 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 ( |
92 | 189 | ("daily", daily_profile_server), |
93 | 190 | ("sleep", sleep_server), |
94 | 191 | ("cosinor", cosinor_server), |
95 | 192 | ("lids", lids_server), |
96 | 193 | ("fractal", fractal_server), |
97 | 194 | ("flm", flm_server), |
98 | 195 | ("ssa", ssa_server), |
| 196 | + ("circ", circ_models_server), |
| 197 | + ("chat", llm_chat_server) |
99 | 198 | ): |
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) |
105 | 200 |
|
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") |
0 commit comments