kub-dashboard

The kub-dashboard is a read-only web interface for browsing and exploring Ktirio Urban Building simulation results and location data.

1. Features

  • Run Catalog: Browse all simulation runs (single and ensemble) with filtering and search

  • Run Details: View artifacts, plots, maps, and sample information for each run

  • Location Explorer: Explore locations without running simulations

    • Building inventory statistics and distributions

    • Weather data analysis (temperature, HDD/CDD, heatmaps)

    • Interactive building maps

    • Preprocessing information

2. Installation

The dashboard requires optional dependencies. Install them with:

pip install feelpp-ktirio-urban-building[dashboard]

For weather analysis with NetCDF support, also install:

pip install feelpp-ktirio-urban-building[dashboard,weather]

3. Quick Start

Start the dashboard server:

kub-dashboard serve --cemdb-root /path/to/cemdb

The dashboard will be available at 127.0.0.1:8050

4. Usage

4.1. Synopsis

kub-dashboard {serve,index,print-index,api} [OPTIONS]

4.2. Commands

4.2.1. serve

Start the dashboard web server.

kub-dashboard serve [OPTIONS]

Options:

Option Description

--cemdb-root PATH

CEMDB root directory (default: $CEMDB_ROOT or ~/cemdb)

--host HOST

Host to bind to (default: 127.0.0.1)

--port PORT

Port to bind to (default: 8050)

--debug

Enable debug mode

4.2.2. index

Build or refresh the run index cache.

kub-dashboard index [OPTIONS]

Options:

Option Description

--cemdb-root PATH

CEMDB root directory

--output PATH, -o PATH

Save index to file (parquet or json)

--refresh

Force refresh (clear cache)

4.2.3. print-index

Print a summary of the run index for debugging.

kub-dashboard print-index [--cemdb-root PATH]

4.2.4. api

Run the REST API server only (no dashboard UI).

kub-dashboard api [OPTIONS]

Options:

Option Description

--cemdb-root PATH

CEMDB root directory

--host HOST

Host to bind to (default: 127.0.0.1)

--port PORT

Port to bind to (default: 8050)

--debug

Enable debug mode

5. Environment Variables

Variable Default Description

CEMDB_ROOT

~/cemdb

Default CEMDB root directory

DASHBOARD_HOST

127.0.0.1

Default host

DASHBOARD_PORT

8050

Default port

DASHBOARD_DEBUG

false

Enable debug mode

6. REST API Endpoints

The dashboard exposes a REST API for programmatic access:

Endpoint Description

GET /api/index

Get the run index (cached)

GET /api/run/<location>/<run_type>/<run_id>

Get run manifest with resolved paths

GET /api/locations

Get locations list with inventory summary

GET /api/location/<name>

Get location details

GET /api/location/<name>/weather

Get weather files and quick stats

GET /api/location/<name>/buildings

Get building inventory statistics

GET /api/health

Health check

7. Pages

7.1. Run Catalog (/)

The main landing page displays a table of all simulation runs with:

  • Location, run type, run ID, status

  • Sample count (for ensemble runs)

  • Run date/time

  • Filters for location, type, and search

Click a row to navigate to the run detail page.

7.2. Run Detail (/run/<location>/<run_type>/<run_id>)

Shows detailed information about a specific run:

  • Summary tab: Run information, timing configuration

  • Artifacts tab: List of output artifacts with paths and checksums

  • Plots tab: Visualizations of KPI summaries, distributions, and timers

  • Map tab: Building locations on an interactive map

  • Samples tab: (Ensemble only) List of ensemble samples

7.3. Locations (/locations)

Browse all available locations showing:

  • Building count, run count

  • Available data (GIS, weather, scenarios, preprocessing)

  • Last modified time

7.4. Location Detail (/location/<name>)

Explore a location without running simulations:

  • Building Inventory tab: Statistics, category distribution, attribute completeness

  • Weather Analysis tab: Temperature stats, HDD/CDD, hourly heatmap, extremes

  • Map tab: Building locations visualization

  • Preprocessing tab: Available partitions and files

8. KPI Playbook and Thresholds

The dashboard renders KPI panels using a registry of KPI specifications. Each spec defines the recommended plots, interpretation hints, and default thresholds.

To add a new KPI:

  1. Create a spec in src/python/feelpp/ktirio/ub/dashboard/kpi/specs/

  2. Register it with register_spec(…​)

  3. Provide the desired views and threshold defaults

Location-specific thresholds can be overridden via:

cemdb/locations/<location>/scenarios/kpi_thresholds.yaml

If no specialized spec is found, the dashboard falls back to a generic KPI panel.

9. Architecture

The dashboard is built with:

9.1. Manifest-First Design

The dashboard uses a manifest-first approach:

  1. Runs are discovered by scanning for manifest.json files

  2. Artifact paths are resolved relative to the run root

  3. Heavy datasets (parquet, HDF5) are loaded lazily on demand

  4. Results are cached with TTL to balance freshness and performance

9.2. Path Resolution

For each run, the root directory is determined by:

  1. manifest["artifact_base"] if it exists on disk

  2. Directory containing the manifest.json file

Artifact paths in the manifest are resolved relative to the run root.

10. CEMDB Structure

The dashboard expects the following CEMDB structure:

cemdb/
└── locations/
    └── <location>/
        └── simulations/
            ├── single/
            │   └── run_*/
            │       └── manifest.json
            └── ensemble/
                └── run_*/
                    └── manifest.json

11. Troubleshooting

11.1. Dashboard won’t start

Check that dependencies are installed:

pip install feelpp-ktirio-urban-building[dashboard]

11.2. No runs found

Ensure your CEMDB has the expected structure with manifest.json files in run directories.

11.3. Missing plots

Plots require specific artifact files:

  • Global KPI: database/stats/global_kpi_summary.parquet

  • Building KPI: database/stats/building_kpi_summary.parquet

  • Timers: database/logs/timers.json

  • Map: database/mappings/building_spatial_index.parquet

12. Development

Run the dashboard in debug mode for development:

kub-dashboard serve --debug

Run tests:

pytest tests/dashboard/

13. See Also