API Reference

Application-wide configuration constants.

Centralizes paths, color palettes, user lists, and annotation schema so that changes propagate consistently across all modules.

Data loading and persistence for accelerometry signals and annotations.

Handles HDF5 signal file discovery, time-windowed data loading, annotation file I/O (Excel-based), and DataFrame normalization.

visualize_accelerometry.data_loading.clamp_anchor(anchor_timestamp, file_start, file_end, windowsize)

Clamp anchor_timestamp so the window stays within file bounds.

Parameters:

• anchor_timestamp (str) – Current anchor in TIME_FMT.

• file_start (str) – File bounds in TIME_FMT.

• file_end (str) – File bounds in TIME_FMT.

• windowsize (float) – Window duration in seconds.

Returns:

Clamped anchor in TIME_FMT.

Return type:

str

visualize_accelerometry.data_loading.cleanup_annotations(pdf)

Sort and normalize an annotation DataFrame.

Ensures consistent types for datetime, numeric, and string columns so that downstream code (Bokeh serialization, DataFrame filtering) doesn’t encounter NaN or mixed-type surprises.

Parameters:

pdf (DataFrame) – Raw or partially-processed annotations.

Returns:

Cleaned copy.

Return type:

DataFrame

visualize_accelerometry.data_loading.get_annotations_from_files(pattern=None)

Load all per-user annotation Excel files and concatenate them.

Parameters:

pattern (str, optional) – Glob pattern for annotation files. Defaults to ANNOTATIONS_GLOB.

Returns:

Combined annotations (unsorted, not yet cleaned).

Return type:

DataFrame

visualize_accelerometry.data_loading.get_filedata(fname, anchor_timestamp, windowsize)

Load a time window of accelerometry data from an HDF5 file.

Parameters:

• fname (str) – Path to the HDF5 file (without .h5 extension).

• anchor_timestamp (str or None) – Center of the time window in TIME_FMT. If None, the window starts at the beginning of the file.

• windowsize (float) – Total window duration in seconds.

Returns:

(anchor_timestamp, file_start, file_end, pdf) where file_start and file_end are only set on the first load (when anchor_timestamp was None).

Return type:

tuple of (str, str or None, str or None, DataFrame)

visualize_accelerometry.data_loading.get_filenames()

Discover HDF5 files and assign each to an annotator deterministically.

Returns:

Sorted list of "username--filename" strings. The assignment uses a fixed random seed so every server restart produces the same mapping, distributing files evenly across annotators.

Return type:

list of str

visualize_accelerometry.data_loading.save_annotations(pdf_annotations, uname, fname)

Persist the current user’s annotations for one file to disk.

Merges the in-memory annotations with any existing data from other files in the user’s Excel file, then writes the result.

Parameters:

• pdf_annotations (DataFrame) – Full in-memory annotation set (all users, all files).

• uname (str) – Current user whose annotations should be saved.

• fname (str) – Current file path (basename is extracted internally).

Returns:

Freshly-reloaded annotations from all users’ files on disk.

Return type:

DataFrame

Per-session application state.

Each browser session (user) gets its own AppState instance that tracks the current file, time window, signal data, and annotations. Persistent ColumnDataSource objects are shared with Bokeh figures so that updating .data triggers a re-render without rebuilding the entire plot.

class visualize_accelerometry.state.AppState(username)

Per-session application state.

Parameters:

username (str) – Authenticated username for this session.

signal_cds

The downsampled signal CDS currently rendered in the plot. Set externally by app.py / CallbackManager._refresh_plot after each plot (re)build.

Type:

ColumnDataSource or None

selection_bounds

(start_timestamp, end_timestamp) set by the box-select callback, or None when nothing is selected.

Type:

tuple or None

get_displayed_annotations()

Filter annotations for the current user and file.

Returns:

Subset of pdf_annotations matching the current username and fname.

Return type:

DataFrame

load_file_data()

Load signal data for the current file, anchor, and window size.

Returns:

Signal data with timestamp, x, y, z columns, or None if the file is empty / unreadable.

Return type:

DataFrame or None

refresh_annotations()

Reload annotations from disk (all users, all files).

update_annotation_sources()

Sync all annotation ColumnDataSources from pdf_annotations.

Filters out rows with NaT timestamps (e.g. review-only flags that have no time range) to prevent Bokeh NaN serialization errors.

UI callback logic for annotation management.

Contains the CallbackManager class that wires widget events to state mutations + view updates, plus helper functions for creating annotation rows and building summary HTML.

class visualize_accelerometry.callbacks.CallbackManager(state, widgets)

Orchestrates UI callbacks between widget events and AppState.

Parameters:

• state (AppState) – Per-session state object.

• widgets (dict) – Name-to-widget mapping populated by app.py. Must include keys for all buttons, labels, and layout containers.

add_notes(notes_text='')

Set notes text on all annotations within the selection.

mark_annotation(artifact)

Add a new annotation for the selected time range.

move_next_window()

Advance the anchor timestamp by one full window, clamped to file end.

move_prev_window()

Move the anchor timestamp back by one full window, clamped to file start.

plot_new_file(fname_with_user, _empty_depth=0)

Switch to a different file and update the plot.

Parameters:

fname_with_user (str) – "username--filename" string from the file picker.

remove_selected_annotations()

Delete all annotations within the current selection bounds.

save()

Persist annotations to disk and refresh the summary.

toggle_flag(flag_name)

Toggle a boolean flag (segment/scoring/review) on selected annotations.

Parameters:

flag_name (str) – Column name to toggle ("segment", "scoring", or "review").

update_anchor_timestamp(value)

Parse and store a user-entered anchor time string.

Parameters:

value (str) – Time string in TIME_FMT.

update_annotations()

Sync annotation overlay CDS data and refresh selection state.

update_plot(force_rebuild=False, _empty_depth=0)

Load data for the current file/anchor and update the plot.

When an existing plot exists and force_rebuild is False, only the CDS data and axis ranges are patched (much faster than a full figure rebuild). Falls back to a full rebuild when no existing plot is available or when the fast path fails.

If the file is empty or unreadable, shows a notification and advances to the next file in the dropdown.

update_review_flags(new_reviews)

Sync file-level review flags with the multi-select widget.

Review flags are annotation rows with review=1 and no time range (start_time is NaT). This method diffs the widget state against the current review flags and adds/removes rows accordingly.

Parameters:

new_reviews (list of str) – Currently selected artifact types in the review widget.

update_selection()

Update button states and selection tables based on current bounds.

Enables/disables annotation buttons depending on whether a region is selected and whether existing annotations fall within it.

update_windowsize(value)

Parse and store a user-entered window size.

Parameters:

value (str) – Numeric string, optionally suffixed with "s".

visualize_accelerometry.callbacks.build_summary_html(state)

Build an HTML summary table for all annotations on the current file.

Parameters:

state (AppState) – Current session state.

Returns:

HTML string for the summary pane.

Return type:

str

visualize_accelerometry.callbacks.capture_new_annotation(start_ts, end_ts, artifact, fname, uname)

Create a single-row DataFrame representing a new annotation.

Parameters:

• start_ts (Timestamp) – Time bounds of the annotated segment.

• end_ts (Timestamp) – Time bounds of the annotated segment.

• artifact (str) – Activity type (e.g. "chair_stand", "tug").

• fname (str) – Path to the signal file (basename is extracted).

• uname (str) – Username of the annotator.

Returns:

One-row DataFrame matching ANNOTATION_COLUMNS.

Return type:

DataFrame

Plotting module — native Bokeh figures with LTTB downsampling.

Creates a main signal plot (with annotation overlays and box-select) and a range selector (minimap) for navigating large time series. LTTB downsampling keeps the browser responsive by limiting the number of points sent over the websocket while preserving visual fidelity.

visualize_accelerometry.plotting.make_plot(pdf, annotation_cds)

Create the main signal plot and range selector.

Parameters:

• pdf (DataFrame or None) – Signal data with columns timestamp, x, y, z. If None or empty, returns empty placeholder plots.

• annotation_cds (dict[str, ColumnDataSource]) – Persistent Bokeh ColumnDataSources keyed by annotation type ("chair_stand", "segment", etc.). Their .data is updated externally; the plot just references them so overlays refresh without rebuilding the figure.

Returns:

(main_pane, range_pane, main_fig, signal_cds, range_source) where signal_cds is the downsampled signal data source and range_source is the minimap CDS (both needed for fast in-place data updates on navigation).

Return type:

tuple of (Panel.pane.Bokeh, Panel.pane.Bokeh, Figure, ColumnDataSource, ColumnDataSource)

visualize_accelerometry.plotting.update_plot_data(pdf, signal_cds, main_fig, range_source=None)

Update an existing plot’s data without rebuilding figures.

Replaces the signal CDS data, adjusts x/y ranges, and optionally updates the range selector CDS. Much faster than make_plot because Bokeh sends only a data-patch over the websocket instead of tearing down and reconstructing the entire document subtree.

Parameters:

• pdf (DataFrame) – New signal data with timestamp, x, y, z.

• signal_cds (ColumnDataSource) – The main signal CDS to update (returned by make_plot).

• main_fig (Figure) – The main plot figure (for x_range / y_range adjustment).

• range_source (ColumnDataSource or None) – The range selector CDS. If None, the minimap is not updated.

Returns:

True if updated successfully, False if a full rebuild is needed.

Return type:

bool