Visualization#

Interactive network maps built on Plotly’s MapLibre traces.

Every plotting entry point returns the plotly.graph_objects.Figure so that it can be post-processed, embedded or exported by the caller. Outside a Jupyter kernel the figure is additionally written to a standalone HTML file; inside a notebook nothing is written to disk, so the returned figure renders inline. Displaying is opt-in through the renderer argument.

from npap import PartitionAggregatorManager

manager = PartitionAggregatorManager()
manager.load_data("networkx_direct", graph=graph)

# Returns the figure and writes ./my_grid.html when run as a script
fig = manager.plot_network(style="simple", title="My grid")

# Open the interactive map in a browser tab (useful from an IDE)
manager.plot_network(renderer="browser")

# Choose where the export lands, or switch it off entirely
manager.plot_network(output_dir="figures", filename="grid.html")
manager.plot_network(save_html=False)

Quick plotting#

npap.visualization.plot_network(graph, style='simple', partition_map=None, *, renderer=None, save_html=None, output_dir=None, filename=None, show=None, config=None, **kwargs)[source]#

Create a quick network visualization.

This function provides a simple interface for one-line plotting without needing to instantiate the NetworkPlotter class explicitly.

The figure is always returned. Outside Jupyter it is additionally exported as a standalone HTML file; inside a notebook nothing is written to disk so the returned figure renders inline. Pass renderer to display it.

Parameters:

graph (DiGraph) – NetworkX DiGraph with geographical coordinates (lat, lon).
style (str) – Visualization style (‘simple’, ‘voltage_aware’, or ‘clustered’).
partition_map (dict[int, list[Any]] | None) – Optional cluster mapping for ‘clustered’ style.
renderer (str | None) – Plotly renderer used to display the figure. None (default) does not display anything. “auto” lets Plotly choose based on the environment. Any other value (e.g. “browser”) is forwarded to Plotly as-is.
save_html (bool | None) – Whether to export a standalone HTML file. None (default) exports only when running outside a Jupyter kernel.
output_dir (str | Path | None) – Directory for the exported HTML. Defaults to the working directory.
filename (str | None) – File name for the exported HTML. Defaults to a slug of the title.
show (bool | None) – Deprecated. show=True maps to renderer=”browser” and show=False to renderer=None. Use renderer directly instead.
config (PlotConfig | None) – Optional PlotConfig instance to override defaults. If provided, kwargs will further override values from this config.
**kwargs (dict) – Additional configuration parameters passed to PlotConfig. These override both defaults and any provided config values.

Returns:

Plotly Figure object.

Return type:

Figure

Raises:

ValueError – If style is unknown or prerequisites are missing.

Examples

>>> from npap.visualization import plot_network
>>> fig = plot_network(graph, style="voltage_aware", title="My Network")
>>> fig = plot_network(graph, style="clustered", partition_map=result.mapping)
>>> fig = plot_network(graph, renderer="browser")  # open in a browser tab

Figure output#

npap.visualization.deliver_figure(fig, *, renderer=None, save_html=None, output_dir=None, filename=None, title=None)[source]#

Export and/or display a figure without mutating global Plotly state.

By default the figure is written to a standalone HTML file when running outside a Jupyter kernel, and left untouched inside one so that the returned figure renders inline. Displaying is opt-in via renderer.

Parameters:

fig (Figure) – Figure to deliver.
renderer (str | None) – Plotly renderer used to display the figure. None (default) does not display anything. “auto” lets Plotly pick the renderer for the current environment. Any other value (e.g. “browser”, “notebook”, “vscode”, “png”) is forwarded to Plotly as-is.
save_html (bool | None) – Whether to export a standalone HTML file. None (default) exports only when not running inside a Jupyter kernel.
output_dir (str | Path | None) – Directory for the exported HTML. Defaults to the working directory.
filename (str | None) – File name for the exported HTML. Defaults to a slug of title.
title (str | None) – Plot title used to derive the default file name.

Returns:

Path of the written HTML file, or None when nothing was exported.

Return type:

Path | None

npap.visualization.resolve_html_path(output_dir=None, filename=None, title=None)[source]#

Determine the destination path of the exported HTML figure.

Parameters:

output_dir (str | Path | None) – Target directory. Defaults to the current working directory.
filename (str | None) – Explicit file name. Defaults to a slug of title, or DEFAULT_HTML_FILENAME when no title is set.
title (str | None) – Plot title used to derive the file name.

Returns:

Absolute path the HTML figure will be written to.

Return type:

Path

Configuration#

class npap.visualization.PlotConfig[source]

Bases: object

Configure network visualization parameters.

This centralized configuration allows users to customize every aspect of the visualization without modifying code. All parameters have sensible defaults optimized for power system networks.

show_lines

Whether to display transmission lines.

Type:: bool

show_trafos

Whether to display transformers.

Type:: bool

show_dc_links

Whether to display DC links.

Type:: bool

show_nodes

Whether to display nodes/buses.

Type:: bool

line_voltage_threshold

Voltage threshold (kV) for high/low voltage line classification.

Type:: float

line_high_voltage_color

Hex color for high voltage lines.

Type:: str

line_low_voltage_color

Hex color for low voltage lines.

Type:: str

trafo_color

Hex color for transformers.

Type:: str

dc_link_color

Hex color for DC links.

Type:: str

edge_color

Hex color for edges with an unrecognised type.

Type:: str

node_color

Hex color for nodes/buses.

Type:: str

edge_width

Width of edge lines in pixels.

Type:: float

node_size

Size of node markers in pixels.

Type:: int

map_style

MapLibre style for the base map.

Type:: str

map_center_lat

Initial map center latitude.

Type:: float

map_center_lon

Initial map center longitude.

Type:: float

map_zoom

Initial map zoom level.

Type:: float

title

Figure title.

Type:: str or None

width

Figure width in pixels.

Type:: int or None

height

Figure height in pixels.

Type:: int or None

cluster_colorscale

Plotly colorscale for cluster coloring.

Type:: str

Attributes:

height
title
width

show_lines: bool = True

show_trafos: bool = True

show_dc_links: bool = True

show_nodes: bool = True

line_voltage_threshold: float = 300.0

line_high_voltage_color: str = '#029E73'

line_low_voltage_color: str = '#CA9161'

trafo_color: str = '#ECE133'

dc_link_color: str = '#CC78BC'

edge_color: str = '#949494'

node_color: str = '#0173B2'

edge_width: float = 1.5

node_size: int = 5

map_style: str = 'carto-positron'

map_center_lat: float = 57.5

map_center_lon: float = 14.0

map_zoom: float = 3.7

title: str | None = None

width: int | None = None

height: int | None = None

cluster_colorscale: str = 'Viridis'

__init__(show_lines=True, show_trafos=True, show_dc_links=True, show_nodes=True, line_voltage_threshold=300.0, line_high_voltage_color='#029E73', line_low_voltage_color='#CA9161', trafo_color='#ECE133', dc_link_color='#CC78BC', edge_color='#949494', node_color='#0173B2', edge_width=1.5, node_size=5, map_style='carto-positron', map_center_lat=57.5, map_center_lon=14.0, map_zoom=3.7, title=None, width=None, height=None, cluster_colorscale='Viridis')

Parameters:

show_lines (bool)
show_trafos (bool)
show_dc_links (bool)
show_nodes (bool)
line_voltage_threshold (float)
line_high_voltage_color (str)
line_low_voltage_color (str)
trafo_color (str)
dc_link_color (str)
edge_color (str)
node_color (str)
edge_width (float)
node_size (int)
map_style (str)
map_center_lat (float)
map_center_lon (float)
map_zoom (float)
title (str | None)
width (int | None)
height (int | None)
cluster_colorscale (str)

Return type:

None

class npap.visualization.PlotStyle[source]

Bases: Enum

Define available visualization styles for power networks.

SIMPLE

All edges rendered uniformly (fastest, minimal visual complexity).

Type:: str

VOLTAGE_AWARE

Edges colored by type and voltage level (recommended for power systems).

Type:: str

CLUSTERED

Nodes colored by cluster assignment (requires prior partitioning).

Type:: str

SIMPLE = 'simple'

VOLTAGE_AWARE = 'voltage_aware'

CLUSTERED = 'clustered'

Plotter#

class npap.visualization.NetworkPlotter[source]

Bases: object

Create high-performance interactive visualizations for power networks.

This class handles the complete visualization pipeline:

Data preparation (coordinate extraction, edge grouping)
Trace generation (edges, nodes)
Figure assembly (layout, styling)

Parameters:

graph (DiGraph) – NetworkX DiGraph with geographical coordinates (lat, lon).
partition_map (dict[int, list[Any]] | None) – Optional mapping of cluster_id to node_ids for cluster visualization.

Examples

>>> plotter = NetworkPlotter(graph, partition_map=partition.mapping)
>>> fig = plotter.plot_clustered()

Methods

`plot_clustered`([config])	Create clustered visualization with nodes colored by cluster assignment.
`plot_simple`([config])	Create simple visualization with uniform edge styling.
`plot_voltage_aware`([config])	Create voltage-aware visualization with edges colored by type and voltage.

__init__(graph, partition_map=None)[source]

Initialize plotter with network data.

Parameters:

graph (DiGraph) – NetworkX DiGraph with geographical coordinates (lat, lon).
partition_map (dict[int, list[Any]] | None) – Optional mapping of cluster_id to node_ids for cluster visualization.

plot_simple(config=None, **output_kwargs)[source]

Create simple visualization with uniform edge styling.

Best for: Initial network overview, maximum performance.

Parameters:

config (PlotConfig | None) – Optional plot configuration.
**output_kwargs (Any) – Output options forwarded to deliver_figure() (renderer, save_html, output_dir, filename).

Returns:

Plotly Figure object.

Return type:

Figure

plot_voltage_aware(config=None, **output_kwargs)[source]

Create voltage-aware visualization with edges colored by type and voltage.

Best for: Understanding network structure, distinguishing transmission levels.

Parameters:

config (PlotConfig | None) – Optional plot configuration.
**output_kwargs (Any) – Output options forwarded to deliver_figure() (renderer, save_html, output_dir, filename).

Returns:

Plotly Figure object.

Return type:

Figure

plot_clustered(config=None, **output_kwargs)[source]

Create clustered visualization with nodes colored by cluster assignment.

Best for: Visualizing partitioning results, understanding cluster geography.

Parameters:

config (PlotConfig | None) – Optional plot configuration.
**output_kwargs (Any) – Output options forwarded to deliver_figure() (renderer, save_html, output_dir, filename).

Returns:

Plotly Figure object.

Return type:

Figure

Raises:

ValueError – If partition_map was not provided during initialization.