accelerometry-annotator 3.4.2

Web-based tool for visualizing and annotating accelerometry data from physical performance assessments.

Accelerometry Annotation Tool

A web-based application for visualizing and annotating accelerometry data. Built with Panel and Bokeh, it enables research teams to collaboratively label activity segments in large time-series recordings. The app is sensor-agnostic — it works with any tri-axial accelerometry data stored in HDF5 format.

Live Demo

A publicly accessible demo is hosted on Hugging Face Spaces:

Launch Demo

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.

AlSahly, A. (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 hpc_utils/connect.sh

Stop the server:

bash hpc_utils/stop_server.sh

What it does

Researchers collect tri-axial accelerometry signals (x, y, z) and need to identify and label activity segments within those recordings. This tool lets annotators visually inspect signals and mark the time boundaries of activities of interest.

The built-in activity labels are configured for standardized physical performance tests, but the app can load and visualize accelerometry data from any setting:

• Chair Stand Test — Repeated sit-to-stand cycles measuring lower-extremity strength
• Timed Up and Go (TUG) — Rise, walk 3 m, turn, walk back, sit — assesses functional mobility
• 3-Meter Walk Test — Short-distance gait speed as a proxy for mobility and physical function
• 6-Minute Walk Test — Submaximal endurance test for aerobic capacity

Features

• LTTB downsampling — Renders 500K+ data points smoothly by reducing to ~10,000 visually representative points using the Largest Triangle Three Buckets algorithm
• Server-side HDF5 filtering — Loads only the visible time window from disk using PyTables where clauses, keeping load times under 20 ms even for 1 GB+ files
• Fast navigation — Previous/Next updates plot data in place (no full figure rebuild), so transitions are near-instant
• Network latency indicator — Header displays live round-trip latency to the server, color-coded by speed
• 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

# Clone the repository
git clone [e-mail]: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:

{
    "username1": "password1",
    "username2": "password2"
}

See credentials.json.example for reference.

Running the app

Local development

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 for the self-service shared server workflow, or Slurm deployment guide 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/.

To build documentation locally:

pip install sphinx furo sphinx-copybutton myst-parser
cd docs
make html
open _build/html/index.html

Versioning and releases

This project uses Semantic Versioning. 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:

   git add visualize_accelerometry/__init__.py CHANGELOG.md
   git commit -m "release: v<VERSION>"
   

4. Create and push the tag:

   git tag v<VERSION>
   git push origin 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

MIT License. This project is developed by the National Social Life, Health, and Aging Project (NSHAP) lab at the University of Chicago.