pypsa-explorer 0.1.0__py3-none-any.whl

pypsa_explorer/__init__.py

@@ -0,0 +1,20 @@
+"""
+PyPSA Explorer - Interactive dashboard for visualizing and analyzing PyPSA energy system networks.
+
+This package provides a comprehensive web-based dashboard for exploring PyPSA networks
+with interactive visualizations, filtering capabilities, and multi-network support.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Open Energy Transition"
+__email__ = "info@openenergytransition.org"
+
+from pypsa_explorer.app import create_app, run_dashboard
+from pypsa_explorer.utils.network_loader import load_networks
+
+__all__ = [
+    "create_app",
+    "run_dashboard",
+    "load_networks",
+    "__version__",
+]

pypsa_explorer/app.py

@@ -0,0 +1,127 @@
+"""Main application module for PyPSA Explorer dashboard."""
+
+import dash
+import dash_bootstrap_components as dbc
+import pypsa
+import pypsa.consistency
+
+from pypsa_explorer.callbacks import register_all_callbacks
+from pypsa_explorer.config import get_html_template, setup_plotly_theme
+from pypsa_explorer.layouts.dashboard import create_dashboard_layout
+from pypsa_explorer.utils.helpers import resolve_default_network_path
+from pypsa_explorer.utils.network_loader import load_networks
+
+
+def create_app(
+    networks_input: dict[str, pypsa.Network | str] | str | None = None,
+    title: str = "PyPSA Explorer",
+    debug: bool = False,  # noqa: ARG001
+    *,
+    load_default_on_start: bool = True,
+    default_network_path: str = "demo-network.nc",
+) -> dash.Dash:
+    """
+    Create and configure the Dash application.
+
+    Parameters
+    ----------
+    networks_input : dict, str, or None
+        Networks to load. Can be:
+        - dict: {label: network_object_or_path}
+        - str: Path to a single network file
+        - None: Behaviour depends on ``load_default_on_start``
+    title : str
+        Dashboard title
+    debug : bool
+        Whether to run in debug mode
+    load_default_on_start : bool
+        When ``True`` (default) load the bundled demo network if ``networks_input`` is ``None``.
+        When ``False`` start without networks and rely on runtime uploads or sample loading.
+    default_network_path : str
+        Filesystem path to the bundled demo network used when loading the example network.
+
+    Returns
+    -------
+    dash.Dash
+        Configured Dash application instance
+    """
+    # Setup Plotly theme
+    setup_plotly_theme()
+
+    resolved_default_path = resolve_default_network_path(default_network_path)
+    default_path_str = str(resolved_default_path) if resolved_default_path else default_network_path
+
+    # Load networks while allowing empty start states
+    if networks_input is None and not load_default_on_start:
+        networks: dict[str, pypsa.Network] = {}
+    else:
+        networks = load_networks(networks_input, default_network_path=default_path_str)
+
+    # Get the first network as the active network initially (if any)
+    network_labels = list(networks.keys())
+    active_network_label = network_labels[0] if network_labels else None
+
+    # Initialize Dash app
+    app = dash.Dash(
+        __name__,
+        external_stylesheets=[dbc.themes.BOOTSTRAP],
+        title=title,
+    )
+
+    # Set custom HTML template with embedded CSS
+    app.index_string = get_html_template()
+
+    # Create layout
+    app.layout = create_dashboard_layout(
+        networks,
+        active_network_label,
+        default_network_path=default_path_str,
+    )
+
+    # Register all callbacks
+    register_all_callbacks(app, networks, default_network_path=default_path_str)
+
+    return app
+
+
+def run_dashboard(
+    networks_input: dict[str, pypsa.Network | str] | str | None = None,
+    debug: bool = True,
+    host: str = "127.0.0.1",
+    port: int = 8050,
+    *,
+    load_default_on_start: bool = True,
+    default_network_path: str = "demo-network.nc",
+) -> None:
+    """
+    Run the PyPSA Explorer dashboard.
+
+    Parameters
+    ----------
+    networks_input : dict, str, or None
+        Networks to load. Can be:
+        - dict: {label: network_object_or_path} mapping labels to Network objects or file paths
+        - str: Single path to a network file
+        - None: Behaviour depends on ``load_default_on_start``
+    debug : bool
+        Whether to run in debug mode
+    host : str
+        Host to run the server on
+    port : int
+        Port to run the server on
+    load_default_on_start : bool
+        Controls whether the bundled demo network loads automatically when ``networks_input`` is ``None``.
+    default_network_path : str
+        Filesystem path to the bundled demo network used for the sample loader.
+    """
+    app = create_app(
+        networks_input,
+        debug=debug,
+        load_default_on_start=load_default_on_start,
+        default_network_path=default_network_path,
+    )
+
+    print(f"Starting PyPSA Explorer Dashboard on http://{host}:{port}")
+    print("Press Ctrl+C to stop the server")
+
+    app.run(debug=debug, host=host, port=port)

pypsa_explorer/callbacks/__init__.py

@@ -0,0 +1,36 @@
+"""Callback functions for PyPSA Explorer dashboard interactivity."""
+
+from pypsa_explorer.callbacks.data_explorer import register_data_explorer_callbacks
+from pypsa_explorer.callbacks.filters import register_filter_callbacks
+from pypsa_explorer.callbacks.navigation import register_navigation_callbacks
+from pypsa_explorer.callbacks.network import register_network_callbacks
+from pypsa_explorer.callbacks.theme import register_theme_callbacks
+from pypsa_explorer.callbacks.visualizations import register_visualization_callbacks
+
+__all__ = [
+    "register_data_explorer_callbacks",
+    "register_filter_callbacks",
+    "register_navigation_callbacks",
+    "register_network_callbacks",
+    "register_theme_callbacks",
+    "register_visualization_callbacks",
+]
+
+
+def register_all_callbacks(app, networks: dict, *, default_network_path: str) -> None:
+    """
+    Register all dashboard callbacks.
+
+    Parameters
+    ----------
+    app : dash.Dash
+        The Dash application instance
+    networks : dict
+        Dictionary of loaded PyPSA networks
+    """
+    register_filter_callbacks(app)
+    register_navigation_callbacks(app)
+    register_network_callbacks(app, networks, default_network_path=default_network_path)
+    register_visualization_callbacks(app, networks)
+    register_data_explorer_callbacks(app, networks)
+    register_theme_callbacks(app)

pypsa_explorer/callbacks/data_explorer.py

@@ -0,0 +1,227 @@
+"""Data explorer callbacks for interactive component dataframe viewing."""
+
+import logging
+
+import dash
+import pandas as pd
+import pypsa
+from dash import Input, Output, State, ctx, no_update
+
+from pypsa_explorer.utils.data_table import dataframe_to_datatable, get_timeseries_attributes
+
+logger = logging.getLogger(__name__)
+
+# Maximum number of rows to display in tables
+MAX_TABLE_ROWS = 5000
+
+# Mapping of KPI card IDs to component names
+KPI_COMPONENT_MAP = {
+    "kpi-card-buses": "buses",
+    "kpi-card-generators": "generators",
+    "kpi-card-lines": "lines",
+    "kpi-card-links": "links",
+    "kpi-card-storage_units": "storage_units",
+    "kpi-card-stores": "stores",
+}
+
+# Human-readable labels for components
+COMPONENT_LABELS = {
+    "buses": "Nodes",
+    "generators": "Generators",
+    "lines": "Lines",
+    "links": "Links",
+    "storage_units": "Storage Units",
+    "stores": "Stores",
+}
+
+
+def register_data_explorer_callbacks(app: dash.Dash, networks: dict[str, pypsa.Network]) -> None:
+    """Register callbacks for the data explorer modal."""
+
+    @app.callback(
+        [
+            Output("data-explorer-modal", "is_open"),
+            Output("data-explorer-modal-title", "children"),
+            Output("static-data-table", "data"),
+            Output("static-data-table", "columns"),
+            Output("timeseries-attribute-selector", "options"),
+            Output("timeseries-attribute-selector", "value"),
+            Output("active-component-store", "data"),
+        ],
+        [
+            Input("kpi-card-buses", "n_clicks"),
+            Input("kpi-card-generators", "n_clicks"),
+            Input("kpi-card-lines", "n_clicks"),
+            Input("kpi-card-links", "n_clicks"),
+            Input("kpi-card-storage_units", "n_clicks"),
+            Input("kpi-card-stores", "n_clicks"),
+            Input("close-data-explorer-modal", "n_clicks"),
+        ],
+        [
+            State("network-selector", "data"),
+            State("data-explorer-modal", "is_open"),
+        ],
+    )
+    def toggle_modal_and_load_data(
+        buses_clicks: int,
+        generators_clicks: int,
+        lines_clicks: int,
+        links_clicks: int,
+        storage_units_clicks: int,
+        stores_clicks: int,
+        close_clicks: int,  # noqa: ARG001
+        network_label: str | None,
+        is_open: bool,  # noqa: ARG001
+    ) -> tuple[bool, str, list[dict], list[dict], list[dict], str | None, str]:
+        """Toggle modal and load component data when KPI card is clicked."""
+        # Get the ID of the component that triggered the callback
+        triggered_id = ctx.triggered_id
+
+        # If close button was clicked, close the modal
+        if triggered_id == "close-data-explorer-modal":
+            return False, no_update, no_update, no_update, no_update, no_update, no_update  # type: ignore[return-value]
+
+        # If no KPI card was clicked, don't update
+        if triggered_id not in KPI_COMPONENT_MAP:
+            return no_update, no_update, no_update, no_update, no_update, no_update, no_update  # type: ignore[return-value]
+
+        # Check if n_clicks is greater than 0 (actual click, not component recreation)
+        # When KPI cards are recreated during network switch, they reset to n_clicks=0
+        # This check prevents the modal from opening on network changes
+        click_counts = {
+            "kpi-card-buses": buses_clicks,
+            "kpi-card-generators": generators_clicks,
+            "kpi-card-lines": lines_clicks,
+            "kpi-card-links": links_clicks,
+            "kpi-card-storage_units": storage_units_clicks,
+            "kpi-card-stores": stores_clicks,
+        }
+
+        triggered_clicks = click_counts.get(triggered_id, 0)
+
+        # Only proceed if there was an actual click (n_clicks > 0)
+        if triggered_clicks == 0:
+            return no_update, no_update, no_update, no_update, no_update, no_update, no_update  # type: ignore[return-value]
+
+        # Get the component name from the triggered card
+        component_name = KPI_COMPONENT_MAP[triggered_id]
+        component_label = COMPONENT_LABELS[component_name]
+
+        if not network_label or network_label not in networks:
+            return no_update, no_update, no_update, no_update, no_update, no_update, no_update  # type: ignore[return-value]
+
+        try:
+            # Get the active network
+            n = networks[network_label]
+
+            # Get the component dataframe
+            if not hasattr(n, component_name):
+                logger.warning(f"Component '{component_name}' not found in network '{network_label}'")
+                return (
+                    True,
+                    f"{component_label} - No Data Available",
+                    [],
+                    [],
+                    [],
+                    None,
+                    component_name,
+                )
+
+            component_df = getattr(n, component_name)
+
+            # Convert dataframe to dict for DataTable using utility
+            if isinstance(component_df, pd.DataFrame):
+                data, columns = dataframe_to_datatable(component_df)
+            else:
+                logger.warning(f"Component '{component_name}' is not a DataFrame")
+                data = []
+                columns = []
+
+            # Get available time-series attributes using efficient utility
+            timeseries_attrs = get_timeseries_attributes(n, component_name)
+            timeseries_options = [{"label": attr, "value": attr} for attr in timeseries_attrs]
+
+            return (
+                True,  # Open modal
+                f"{component_label} Data ({len(component_df):,} records)",
+                data,
+                columns,
+                timeseries_options,
+                timeseries_options[0]["value"] if timeseries_options else None,
+                component_name,  # Store component name for efficient lookup
+            )
+
+        except Exception as e:
+            logger.error(f"Error loading component data for '{component_name}': {e}")
+            return (
+                True,
+                f"{component_label} - Error Loading Data",
+                [],
+                [],
+                [],
+                None,
+                component_name,
+            )
+
+    @app.callback(
+        [
+            Output("timeseries-data-table", "data"),
+            Output("timeseries-data-table", "columns"),
+        ],
+        [
+            Input("timeseries-attribute-selector", "value"),
+        ],
+        [
+            State("active-component-store", "data"),
+            State("network-selector", "data"),
+        ],
+    )
+    def update_timeseries_data(
+        selected_attribute: str | None,
+        component_name: str | None,
+        network_label: str | None,
+    ) -> tuple[list[dict], list[dict]]:
+        """Update time-series data table when attribute is selected."""
+        if not selected_attribute or not component_name:
+            return [], []
+
+        if not network_label or network_label not in networks:
+            return [], []
+
+        try:
+            # Get the active network
+            n = networks[network_label]
+
+            # Get time-series data
+            timeseries_component = f"{component_name}_t"
+            if not hasattr(n, timeseries_component):
+                logger.warning(f"Time-series component '{timeseries_component}' not found in network '{network_label}'")
+                return [], []
+
+            ts_obj = getattr(n, timeseries_component)
+            if not hasattr(ts_obj, selected_attribute):
+                logger.warning(
+                    f"Attribute '{selected_attribute}' not found in time-series component '{timeseries_component}'"
+                )
+                return [], []
+
+            ts_df = getattr(ts_obj, selected_attribute)
+
+            if isinstance(ts_df, pd.DataFrame):
+                # Check if dataframe exceeds maximum rows
+                if len(ts_df) > MAX_TABLE_ROWS:
+                    logger.warning(
+                        f"Time-series data for '{selected_attribute}' has {len(ts_df):,} rows, "
+                        f"limiting to first {MAX_TABLE_ROWS:,} rows for display"
+                    )
+
+                # Use utility function for efficient conversion with uniform sampling
+                data, columns = dataframe_to_datatable(ts_df, max_rows=MAX_TABLE_ROWS)
+                return data, columns
+
+            logger.warning(f"Time-series attribute '{selected_attribute}' is not a DataFrame")
+            return [], []
+
+        except Exception as e:
+            logger.error(f"Error loading time-series data for '{selected_attribute}': {e}")
+            return [], []

pypsa_explorer/callbacks/filters.py

@@ -0,0 +1,40 @@
+"""Filter-related callbacks for PyPSA Explorer dashboard."""
+
+from typing import Any
+
+from dash import Input, Output
+
+
+def register_filter_callbacks(app) -> None:
+    """Register filter-related callbacks."""
+
+    @app.callback(
+        [
+            Output("global-country-selector", "disabled"),
+            Output("global-country-selector", "value"),
+        ],
+        [Input("global-country-mode", "value")],
+    )
+    def toggle_global_country_selector(mode: str) -> tuple[bool, list[Any]]:
+        """Enable/disable country selector based on mode."""
+        if mode == "All":
+            return True, []
+        else:
+            return False, []
+
+    @app.callback(
+        [
+            Output("global-carrier-selector-container", "style"),
+            Output("carrier-not-applicable-text", "style"),
+            Output("active-tab-store", "data"),
+        ],
+        [Input("tabs", "value")],
+    )
+    def handle_tab_specific_ui(active_tab: str) -> tuple[dict[str, str], dict[str, str], str]:
+        """Handle UI elements based on the active tab."""
+        if active_tab in ["capex", "opex"]:
+            # Hide carrier selector for CAPEX/OPEX tabs
+            return {"display": "none"}, {"display": "block"}, active_tab
+        else:
+            # Show carrier selector for other tabs
+            return {"display": "block"}, {"display": "none"}, active_tab

pypsa_explorer/callbacks/navigation.py

@@ -0,0 +1,55 @@
+"""Navigation callbacks for PyPSA Explorer dashboard."""
+
+from typing import cast
+
+from dash import Input, Output, State, no_update
+
+
+def register_navigation_callbacks(app) -> None:
+    """Register navigation-related callbacks."""
+
+    @app.callback(
+        [
+            Output("welcome-content", "style"),
+            Output("dashboard-content", "style"),
+            Output("page-state", "data"),
+            Output("top-bar-network-selector", "style"),
+        ],
+        [Input("enter-dashboard-btn", "n_clicks")],
+        [
+            State("page-state", "data"),
+            State("network-registry", "data"),
+        ],
+    )
+    def navigate_pages(
+        n_clicks: int | None,
+        page_state: dict[str, str],
+        registry: dict[str, list[str]] | None = None,
+    ) -> tuple[dict[str, str], dict[str, str], dict[str, str], dict[str, str]]:
+        """Manage navigation between welcome page and dashboard."""
+        page_state = page_state or {}
+        has_network = bool(registry and registry.get("order"))
+        current_page = page_state.get("current_page")
+
+        if n_clicks and current_page == "welcome" and has_network:
+            return (
+                {"display": "none"},
+                {"display": "block"},
+                {"current_page": "dashboard"},
+                {"display": "flex"},
+            )
+        if current_page == "dashboard" and has_network:
+            return (
+                cast(dict[str, str], no_update),
+                cast(dict[str, str], no_update),
+                cast(dict[str, str], no_update),
+                {"display": "flex"},
+            )
+
+        # No networks or still on welcome page keeps selector hidden
+        return (
+            cast(dict[str, str], no_update),
+            cast(dict[str, str], no_update),
+            cast(dict[str, str], no_update),
+            {"display": "none"},
+        )