Node Inspector App

Interactive sound data visualization tool that displays time-frequency cochleograms from the sa_node_day lite server (default), optional PostgreSQL historical data, or live Munisense portal data.

Standalone version of the original report_pipeline_2026/apps/node_inspector_db_app/, using sa_project_store for project configuration instead of src.sa_config.

Quick Start

./run_node_inspector.sh

Then open http://localhost:5011 in your browser.

The launch script automatically kills any existing process on port 5011.

Features

• Historical data: Full-day visualizations from the sa_node_day lite server by default, or PostgreSQL as an option
• Runtime source switch: Toggle between lite server and DB directly in the UI
• Live data: Real-time data from Munisense portal (15-105 minute intervals)
• Interactive calendar: Date picker with node availability indication
• Multiple projects: All projects from sa_projects_vps0 with active locations
• Click-to-inspect: Click on the plot to see detailed time/frequency information
• Line overlays: Mark and annotate specific time points
• Audio clips: Download, play, and annotate audio clips from the portal

Requirements

• Python 3.11+ (SA_3.13 conda environment)
• sa_node_day installed from ~/SA_projects/sa_libs/sa_node_day
• Munisense portal credentials in login_info.config
• sa_project_store (pip-installed from ~/SA_projects/sa_libs/sa_project_store)
• sa_fetcher, sa_pipeline (pip-installed)
• Optional: PostgreSQL with sa_preloader database on localhost:5433 when data_source = "db"
• Optional: sa_preloader for the PostgreSQL path

Python Dependencies

pip install bokeh holoviews datashader numpy pytz xarray matplotlib zstandard
pip install -e ~/SA_projects/sa_libs/sa_project_store
pip install -e ~/SA_projects/sa_libs/sa_node_day

Optional for data_source = "db":

pip install psycopg2-binary

Configuration

app_config.toml

Local settings not provided by sa_project_store:

• repo_path — path to the sa_projects_vps0 git clone
• data_source — "lite" (default) or "db"
• server_url — base URL for the sa_node_day lite server
• TF_Bg_shift — additive offset for DB data (default 30.5)
• offset_hours — day boundary offset (default 6)
• [db] — PostgreSQL connection (host, port, dbname), used only when data_source = "db"
• clips_dir — audio clip storage (default: <app_dir>/clips)
• login_config_fallback — path to Munisense login credentials

Per-project overrides are supported:

[project_overrides.gilze-rijen]
offset_hours = 0

Project definitions

Projects are loaded from sa_projects_vps0 via sa_project_store.ProjectStore. Only projects with active locations (those having a location_id) are shown. To add or modify projects, edit the corresponding project.toml in sa_projects_vps0/projects/<name>/.

Architecture

node_inspector_app/
├── main.py                  # Bokeh application entry point
├── config.py                # Configuration via sa_project_store + app_config.toml
├── app_config.toml          # Local settings (DB, paths, defaults)
├── run_node_inspector.sh    # Launch script (auto-kills stale process)
├── data/
│   ├── retrieval.py         # Data fetching (lite server / DB + portal), filtered to needed characteristics
│   ├── processing.py        # DataProcessor class
│   ├── audio_clips.py       # MP3 clip storage and annotation
│   └── audio_downloader_bridge.py  # Background clip downloads
├── ui/
│   └── date_picker.py       # Calendar widget
├── plotting/
│   └── overlays.py          # Click handlers and line overlays
├── utils/
│   └── helpers.py           # Utility functions
├── datashaded_images.py     # HoloViews/datashader visualization
├── sa_fetcher_tools.py      # Munisense API utilities
└── retrieved_data/          # DB-only interpreted cache directory

Differences from original

• No dependency on report_pipeline_2026 — all imports are self-contained or from pip-installed packages
• sa_project_store replaces src.sa_config for project definitions
• Characteristic filtering — only fetches/processes the 6 characteristics needed for visualization (EdB_MP_s, EdB_s, Bg_s, Bg_m, Bg_h, ms:laeq94), improving performance and avoiding bugs in unused unpacking code paths

Caching

When data_source = "lite", historical fetches use the shared sa_node_day cache at ~/.cache/sa_node_day, so notebooks, scripts, and the inspector app all reuse the same local cache. The "Clear Cache" button clears that shared cache.

When data_source = "db", processed day data is cached in retrieved_data/ as compressed pickle files (.interpreted.pkl.zst). The same UI button clears that DB-only interpreted cache.

Troubleshooting

Session token expired

Refresh the browser page (Cmd+R).

No data for date

Check that:
1. If data_source = "lite", the server_url endpoint is reachable
2. If data_source = "db", the PostgreSQL instance is running on localhost:5433
4. Data exists for the selected node and date
5. The portal credentials in login_info.config are valid

Project not showing

The project must have at least one location with a location_id in its project.toml. Check sa_projects_vps0/projects/<name>/project.toml.