New architecture and functions for n.explore() using a new PydeckPlotter class #1312

bobbyxng · 2025-08-04T13:49:35Z

Changes proposed in this Pull Request

Improving n.explore() and extending its functionalities with interactive plots
Changing backend from folium to pydeck

Implemented features

Checklist

Code changes are sufficiently documented; i.e. new functions contain docstrings and further explanations may be given in doc.
Unit tests for new features were added (if applicable).
A note for the release notes doc/release_notes.rst of the upcoming release is included.
I consent to the release of this PR's code under the MIT license.

… .show() to .explore()

for more information, see https://pre-commit.ci

…s. Implemented a variety of error checks, warnings and dropping of components in plot.

…ded to empty lines/links.

bobbyxng · 2025-08-14T14:26:42Z

Update: Apart from generating pie charts based on multi-index pd.Series, all functionality from static n.plot() are now implemented in n.explore, with identical API wherever applicable:

Create an interactive map of the PyPSA network using Pydeck.

    Parameters
    ----------
    n : Network
        The PyPSA network to plot.
    bus_sizes : float/dict/pandas.Series
        Sizes of bus points in meters, defaults to 5000.
    bus_colors : str/dict/pandas.Series
        Colors for the buses, defaults to "cadetblue".
    bus_alpha : float/dict/pandas.Series
        Add alpha channel to buses, defaults to 0.7.
    bus_columns : list, default None
        List of bus columns to include. If None, only the bus index and x, y coordinates are used.
        Specify additional columns to include in the tooltip.
    line_flow : float/dict/pandas.Series/None
        Series of line flows indexed by line names, defaults to None. If None, no arrows will be created.
        If a float is provided, it will be used as a constant flow for all lines.
    line_colors : str/dict/pandas.Series
        Colors for the lines, defaults to 'rosybrown'.
    line_alpha : float/dict/pandas.Series
        Add alpha channel to lines, defaults to 0.7.
    line_widths : float/dict/pandas.Series
        Widths of lines in meters, defaults to 1500.
    line_columns : list, default None
        List of line columns to include. If None, only the bus0 and bus1 columns are used.
        Specify additional columns to include in the tooltip.
    link_flow : float/dict/pandas.Series/None
        Series of link flows indexed by link names, defaults to None. If None, no arrows will be created.
        If a float is provided, it will be used as a constant flow for all links.
    link_colors : str/dict/pandas.Series
        Colors for the links, defaults to 'darkseagreen'.
    link_alpha : float/dict/pandas.Series
        Add alpha channel to links, defaults to 0.7.
    link_widths : float/dict/pandas.Series
        Widths of links in meters, defaults to 1500.
    link_columns : list, default None
        List of link columns to include. If None, only the bus0 and bus1 columns are used.
        Specify additional columns to include in the tooltip.
    transformer_flow : float/dict/pandas.Series/None
        Series of transformer flows indexed by transformer names, defaults to None. If None, no arrows will be created.
        If a float is provided, it will be used as a constant flow for all transformers.
    transformer_colors : str/dict/pandas.Series
        Colors for the transformers, defaults to 'orange'.
    transformer_alpha : float/dict/pandas.Series
        Add alpha channel to transformers, defaults to 0.7.
    transformer_widths : float/dict/pandas.Series
        Widths of transformers in meters, defaults to 1500.
    transformer_columns : list, default None
        List of transformer columns to include. If None, only the bus0 and bus1 columns are used.
        Specify additional columns to include in the tooltip.
    arrow_size_factor : float, default 2.5
        Factor to scale the arrow size in relation to line_flow. A value of 1 denotes a multiplier of 1xline_width.
    arrow_colors : str/dict/pandas.Series | None, default None
        Colors for the arrows. If not specified, defaults to the same colors as the respective branch component.
    arrow_alpha : float/dict/pandas.Series, default 1.0
        Add alpha channel to arrows, defaults to 1.0.
    map_style : str
        Map style to use for the plot. One of 'light', 'dark', 'road', 'satellite', 'dark_no_labels', and 'light_no_labels'.
    tooltip : bool, default True
        Whether to add a tooltip to the bus layer.

    Returns
    -------
    pdk.Deck
        The interactive map as a Pydeck Deck object.

Currently, n.explore() would directly return a functioning pydeck object which could be directly manipulated using pydecks built-in methods. It also allows for stacking with other already generated pydeck object, very similar to how matplotlib.pyplot handles stacking.

However, by returning a pydeck object directly, subsequent manipulations to the generated object can only be done on the pydeck object level, not on the PydeckPlotter class (which is introduced in pypsa.plot.maps.interactive).

For example, not implemented though, the PydeckPlotter class can have additional properties like buses_without_coordinates, branch_components_dropped, etc. (tbd. whether this is useful at all).

Long story short, here are the options I see:
a) Keep as it is now, only use PydeckPlotter class for structuring methods, return a pydeck object with n.explore()
b) Return a PydeckPlotter object with n.explore(). Then a user would do the following operation to get the pydeck object: map = n.explore(), followed by map.deck()
c) PydeckPlotter inherits from pydeck class and is extended by additional methods and properties. Requires some refactoring of code.

Do you have any thoughts @lkstrp, @fneum, @FabianHofmann ?

bobbyxng · 2025-08-14T14:29:17Z

Sneak preview:

pypsa/common.py

bobbyxng · 2025-09-23T08:22:25Z

Added auto_scale based on bus_size_max and branch_width_max
Added support for geometry column in branch components

…ependencies.

… new file.

bobbyxng · 2025-09-24T10:49:35Z

Finalised unit tests
Added release nots.
Demo: https://bxio.ng/files/pypsa-explore-demo

From my side it's also ready to merge :)
Thank you both @lkstrp and @fneum !

bobbyxng self-assigned this Aug 4, 2025

bobbyxng marked this pull request as draft August 4, 2025 13:50

bobbyxng changed the title ~~Extending n.explore()~~ New architecture and functions for n.explore() using a new PydeckPlotter class Aug 4, 2025

Base automatically changed from new-opt to master August 12, 2025 21:03

bobbyxng added 11 commits August 13, 2025 10:01

Initialising notebook

2dd9245

Initial architecture and class PydeckPlotter

ca82ef0

Updated pyproject.toml to include pydeck dependency.

d7d98aa

Fixing pre-commit errors

b79ba66

Typing fixes.

c0a6fc4

Added initial view state.

0bfafef

Cleaned up explore() in interactive notebook. Allow stacking. Renamed…

0d4e94e

… .show() to .explore()

Added bus colors, cleaned up properties and return pydeck object only.

ae312a6

Implemented tooltips and bus_columns subsetting, defaults to true.

5686e55

Added PathLayer for lines, code simplification and reuse.

eec7ab0

Added default value tooltip

85f1219

bobbyxng force-pushed the new-explore branch from 26d5a2d to 85f1219 Compare August 13, 2025 08:13

pre-commit-ci bot and others added 11 commits August 13, 2025 08:13

[pre-commit.ci] auto fixes from pre-commit.com hooks

db14894

for more information, see https://pre-commit.ci

Small typo fixes.

ec46c74

Added initial endogenous arrowhead functionality for flows.

12d72e0

Merge branch 'master' into new-explore

d3a120d

Added flow sizing and coloring for arrows.

641f170

Added reindex to _convert_to_series to make it more robust.

4c46abc

Finished adding all bus and branch components and their main argument…

35dfdcd

…s. Implemented a variety of error checks, warnings and dropping of components in plot.

Added coords to default tooltip.

2b50894

Added default pitch, bearing and parameters to fix z-fighting issue

1626b9b

Bug fix: Made explore() more robust if only broken lines/links are ad…

298f733

…ded to empty lines/links.

Revert pitch, bearing to 0. Added TODO in _convert_to_series function.

ab724bc

bobbyxng commented Aug 14, 2025

View reviewed changes

pypsa/common.py Show resolved Hide resolved

bobbyxng added 2 commits September 22, 2025 20:56

Finalised code, all features added.

e36c8a1

Merge branch 'master' into new-explore

56032f8

bobbyxng added 19 commits September 23, 2025 12:15

Added unit tests test_plot_maps_common.py

682de11

Fixed test flip_polgon_preserves_shape.

27ebdea

Merge branch 'master' into new-explore

9fb768c

Fixed deprecated warnings related to n.static.

cac9cf9

added basic test for n.explore() and removed mapclassify and folium d…

83aad97

…ependencies.

Correct docstring for interactive.py

46dcd7e

added basic test for n.explore().

68b612e

Temporarily disable test_cartopy_graceful_fallback(self).

cc1ee14

Merge branch 'master' into new-explore

98af69c

Reactivated test_cartopy_graceful_fallback(self).

5a88bb4

Fixed test_optional_dependencies.

f1f09d5

Fixed test_optional_dependencies.

bb931c5

Fixed relative paths in pytest tests for cartopy check.

0707c73

Fix unit test test_optional_dependencies.py.

96abbdd

Bug fixes in explore (use branch_components if specified).

18cbff7

Added Pydeckplotter/explore tests and moved previous explore tests to…

b391ab5

… new file.

Updated testing.

5329a36

Added release notes.

b02ca88

Added pie chart bus_split_circle test.

097a2f3

lkstrp merged commit c2b9a06 into master Sep 24, 2025
26 checks passed

lkstrp deleted the new-explore branch September 24, 2025 11:19

This was referenced Sep 24, 2025

v1.0 Documentation for new Network.explore(...) API #1374

Closed

Fixed misaligned indices for pie charts. #1375

Merged

v1.0 Documentation for new Network.explore(...) API (corrected, rebased) #1376

Merged

Irieo mentioned this pull request Oct 16, 2025

Expand n.explore() to show outputs of solved networks #1279

Closed

FabianHofmann mentioned this pull request Oct 22, 2025

harmonize features & update optimization framework enricogiglio/PyPSA#2

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

New architecture and functions for n.explore() using a new PydeckPlotter class #1312

New architecture and functions for n.explore() using a new PydeckPlotter class #1312

Uh oh!

bobbyxng commented Aug 4, 2025 •

edited

Loading

Uh oh!

bobbyxng commented Aug 14, 2025

Uh oh!

bobbyxng commented Aug 14, 2025

Uh oh!

Uh oh!

bobbyxng commented Sep 23, 2025

Uh oh!

bobbyxng commented Sep 24, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

New architecture and functions for n.explore() using a new PydeckPlotter class #1312

New architecture and functions for n.explore() using a new PydeckPlotter class #1312

Uh oh!

Conversation

bobbyxng commented Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes proposed in this Pull Request

Implemented features

Checklist

Uh oh!

bobbyxng commented Aug 14, 2025

Uh oh!

bobbyxng commented Aug 14, 2025

Uh oh!

Uh oh!

bobbyxng commented Sep 23, 2025

Uh oh!

bobbyxng commented Sep 24, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bobbyxng commented Aug 4, 2025 •

edited

Loading