accelerometry-annotator 3.2.0__py3-none-any.whl

accelerometry_annotator-3.2.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: accelerometry-annotator
+Version: 3.2.0
+Summary: Web-based tool for visualizing and annotating wrist-worn accelerometry data from physical performance assessments.
+Author-email: Manu Murugesan <manorathan@uchicago.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/TavoloPerUno/py_visualize_accelerometry
+Project-URL: Documentation, https://tavoloperuno.github.io/py_visualize_accelerometry/
+Project-URL: Demo, https://tavoloperuno-accelerometry-viewer-demo.hf.space/
+Project-URL: Repository, https://github.com/TavoloPerUno/py_visualize_accelerometry
+Project-URL: Issues, https://github.com/TavoloPerUno/py_visualize_accelerometry/issues
+Keywords: accelerometry,annotation,wearable-sensors,gait-analysis,physical-performance,time-series,data-visualization,bokeh,panel
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bokeh<3.4,>=3.3
+Requires-Dist: panel<1.4,>=1.3
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: tables
+Requires-Dist: openpyxl
+Requires-Dist: jinja2
+Provides-Extra: lttb
+Requires-Dist: lttbc; extra == "lttb"
+Dynamic: license-file
+
+# Accelerometry Annotation Tool
+
+A web-based application for visualizing and annotating wrist-worn accelerometry data from physical performance assessments. Built with [Panel](https://panel.holoviz.org/) and [Bokeh](https://bokeh.org/), it enables research teams to collaboratively label activity segments in large time-series recordings.
+
+![Full application view](docs/images/demo_full_app.png)
+
+## Live Demo
+
+A publicly accessible demo is hosted on Hugging Face Spaces:
+
+**[Launch Demo](https://tavoloperuno-accelerometry-viewer-demo.hf.space/)**
+
+| Username | Password | Role |
+|---|---|---|
+| `demo_admin` | `demo` | Admin (can manage users, impersonate) |
+| `demo_user` | `demo` | Annotator |
+
+> **Note:** The demo uses real accelerometer data from the dataset below,
+> resampled and composed into short recordings (~10 min at 85 Hz). It does
+> not contain real participant recordings. Example annotations are
+> pre-populated to showcase labeling, flags, and inter-annotator variability.
+>
+> Alharbi, F. (2022). *Accelerometer Gyro Mobile Phone Dataset* [Dataset]. UCI Machine Learning Repository. https://doi.org/10.3390/s22176513
+
+## Shared Server Deployment (HPC / Slurm)
+
+For HPC environments, you can run a single shared instance via Slurm that all team members connect to through SSH tunneling.
+
+**Connect** (each user — submits job automatically if not running):
+```bash
+bash hpc_utils/connect.sh
+```
+
+**Stop the server**:
+```bash
+bash hpc_utils/stop_server.sh
+```
+
+## What it does
+
+Researchers collect tri-axial accelerometry signals (x, y, z) during standardized physical performance tests. This tool lets annotators visually inspect those signals and mark the time boundaries of each test:
+
+- **Chair Stand Test** — Measures lower-extremity strength by timing repeated sit-to-stand cycles from a standard chair. A key indicator of fall risk and functional independence in older adults.
+- **Timed Up and Go (TUG)** — Assesses functional mobility: the participant rises from a chair, walks 3 meters, turns, walks back, and sits down. Taking 12+ seconds indicates increased fall risk (CDC STEADI).
+- **3-Meter Walk Test** — Measures gait speed over a short distance as a proxy for mobility and physical function. Gait speed is widely regarded as "the sixth vital sign" for predicting disability and mortality.
+- **6-Minute Walk Test** — A submaximal endurance test where the participant walks as far as possible in 6 minutes. Used to evaluate aerobic capacity in cardiac and pulmonary research.
+
+## Features
+
+- **LTTB downsampling** — Renders 500K+ data points smoothly by reducing to ~5,000 visually representative points using the Largest Triangle Three Buckets algorithm
+- **Range selector** — Minimap for navigating long recordings without losing context
+- **Box-select annotation** — Select a time range and label it with one click
+- **Segment, scoring, and review flags** — Mark annotations for segmentation, scoring, or review with distinct hatch-pattern overlays
+- **Notes** — Attach free-text notes to any annotation
+- **Multi-user collaboration** — Each annotator sees their own file assignments; admins can impersonate users and manage accounts
+- **Authentication** — Built-in basic auth (or OAuth for production deployments)
+- **Auto-save to Excel** — Per-user annotation files for easy downstream analysis
+
+## Installation
+
+### Prerequisites
+
+- Python 3.9+
+- Conda (recommended) or pip
+
+### Setup
+
+```bash
+# Clone the repository
+git clone git@github.com:TavoloPerUno/py_visualize_accelerometry.git
+cd py_visualize_accelerometry
+
+# Create and activate conda environment
+conda create -n panel_app python=3.12
+conda activate panel_app
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+### Data setup
+
+Place HDF5 accelerometry files (`.h5`) in:
+```
+visualize_accelerometry/data/readings/
+```
+
+Each file should contain a `readings` table with columns: `timestamp`, `x`, `y`, `z`.
+
+### Credentials
+
+Create a `credentials.json` file in the project root:
+```json
+{
+    "username1": "password1",
+    "username2": "password2"
+}
+```
+
+See `credentials.json.example` for reference.
+
+## Running the app
+
+### Local development
+
+```bash
+panel serve visualize_accelerometry/app.py \
+    --port 5601 \
+    --basic-auth credentials.json \
+    --cookie-secret $(python -c "import secrets; print(secrets.token_hex(32))") \
+    --allow-websocket-origin localhost:5601 \
+    --basic-login-template visualize_accelerometry/templates/login.html
+```
+
+Then open http://localhost:5601/app in your browser.
+
+### HPC (SLURM)
+
+See [Shared server startup](docs/shared-server-startup.md) for the self-service shared server workflow, or [Slurm deployment guide](docs/slurm-deployment.md) for the full deployment guide.
+
+## Project structure
+
+```
+py_visualize_accelerometry/
+├── visualize_accelerometry/
+│   ├── app.py              # Main Panel application and layout
+│   ├── callbacks.py         # UI event handlers and annotation logic
+│   ├── config.py            # Colors, paths, user lists, constants
+│   ├── data_loading.py      # HDF5 I/O, annotation file management
+│   ├── plotting.py          # Bokeh plots with LTTB downsampling
+│   ├── state.py             # Per-session state management
+│   ├── templates/           # Login/logout HTML templates
+│   ├── static/              # Favicon, logo
+│   └── data/
+│       ├── readings/        # HDF5 accelerometry files
+│       └── output/          # Per-user annotation Excel files
+├── hpc_utils/               # HPC deployment scripts (Slurm, SSH tunneling)
+│   ├── connect.sh           # Self-service connect script
+│   ├── start_server.sh      # Slurm job script
+│   ├── stop_server.sh       # Stop running server
+│   └── logs/                # Job and server logs
+├── requirements.txt
+└── credentials.json         # Auth credentials (not in repo)
+```
+
+## Documentation
+
+Full documentation is available at [https://tavoloperuno.github.io/py_visualize_accelerometry/](https://tavoloperuno.github.io/py_visualize_accelerometry/).
+
+To build documentation locally:
+
+```bash
+pip install sphinx sphinx-rtd-theme myst-parser
+cd docs
+make html
+open _build/html/index.html
+```
+
+## Versioning and releases
+
+This project uses [Semantic Versioning](https://semver.org/). The canonical version lives in `visualize_accelerometry/__init__.py` as `__version__`.
+
+### Cutting a release
+
+1. Update `__version__` in `visualize_accelerometry/__init__.py`
+2. Update `CHANGELOG.md` with the new version's changes
+3. Commit the changes:
+   ```bash
+   git add visualize_accelerometry/__init__.py CHANGELOG.md
+   git commit -m "release: v<VERSION>"
+   ```
+4. Create and push the tag:
+   ```bash
+   git tag v<VERSION>
+   git push git v<VERSION>
+   ```
+5. The `release.yml` GitHub Actions workflow will automatically create a GitHub Release with auto-generated notes from commits since the last tag.
+
+## License
+
+This project is developed by the [National Social Life, Health, and Aging Project (NSHAP)](https://www.norc.org/research/projects/national-social-life-health-and-aging-project.html) lab at the University of Chicago.

accelerometry_annotator-3.2.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+accelerometry_annotator-3.2.0.dist-info/licenses/LICENSE,sha256=24OmAApTAqr0wMqDnUbzu3Wwt-_rKwIsmWZxFuejOz0,1135
+visualize_accelerometry/__init__.py,sha256=OUX37Yd6ZO82d0GJL2dmK0gZTtc_xvlTvGQIl2I-D8k,22
+visualize_accelerometry/app.py,sha256=oDwOLdpGEqhS7vYdE90vGkbot7bq0ngPIUBgPwQSpX4,44309
+visualize_accelerometry/callbacks.py,sha256=QA38LkPdx58jsp4VOvFsN8z_WREGrj6p25kIgIGnxVg,24331
+visualize_accelerometry/config.py,sha256=jn1em9kU3I0r9dlx_K1ZbxisqNRTZEWNBlIdvg3Gwe0,3108
+visualize_accelerometry/data_loading.py,sha256=FCoV0pVEzexdUZ67yeNYeHxfs2_6IbazcyxAim2bzmQ,7884
+visualize_accelerometry/plotting.py,sha256=-Hf93NnrdOt13Dlpi12lb_rQS0LP7vS48zsPWi0BCak,8686
+visualize_accelerometry/state.py,sha256=XD9eFPqykX2t1meE5jE412xQI3wc5pTcVKPRjl7QKPg,6153
+visualize_accelerometry/js/download.js,sha256=sXDdJJXQHN33b1RtqMAtOX8Fqzu8iJ-ITezuJNpAzAk,921
+visualize_accelerometry/static/favicon.ico,sha256=gfs-mRx1Xhw4W3ljhkri-jsLYUT9L-QrSzzz0-mXfMQ,63276
+visualize_accelerometry/static/favicon.svg,sha256=YRzC7kvrawoZVSGDy13zIVEtNnTSZIJGArt1PnhHxO0,1256
+visualize_accelerometry/static/logo-dark.svg,sha256=I1V26j0tj8VkJRolw3eh-s8yEuCw2gLpyl2ITyYoLkk,2383
+visualize_accelerometry/static/logo.jpg,sha256=gfs-mRx1Xhw4W3ljhkri-jsLYUT9L-QrSzzz0-mXfMQ,63276
+visualize_accelerometry/static/logo.svg,sha256=yEz7qqFDUItZJha94oE9Ze9gYfyYBLF4OwTNi5kXaAM,2349
+visualize_accelerometry/templates/index.html,sha256=kVwp2zoQDednF3fF2-TwaCg4nqD1PFqPbf9MM3Qn-_E,656
+visualize_accelerometry/templates/login.html,sha256=IZKShhDbNV13PpZkBadbGhHCFJzjhO6q_KFTa3dWXEU,9858
+visualize_accelerometry/templates/logout.html,sha256=hpdp45-cHxQMkrNqWiIDfgGj6OzUsw2Qas2VPnrGtO4,7120
+accelerometry_annotator-3.2.0.dist-info/METADATA,sha256=DP0K8qaKJrjhcUas0dSXwCQSTvusnqN68sdI3Q-s3Cw,8948
+accelerometry_annotator-3.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+accelerometry_annotator-3.2.0.dist-info/top_level.txt,sha256=qWW2zE_4GqJHwfAfmDhxXeJ5kbdLd3Fw6wene6gq_YU,24
+accelerometry_annotator-3.2.0.dist-info/RECORD,,

accelerometry_annotator-3.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

accelerometry_annotator-3.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 National Social Life, Health, and Aging Project (NSHAP),
+University of Chicago
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

accelerometry_annotator-3.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+visualize_accelerometry

visualize_accelerometry/__init__.py

@@ -0,0 +1 @@
+__version__ = "3.2.0"