Collections for Plotting

Collections are a number of different symbols that can be plotted as a unit in matplotlib, which is very handy when plotting a large number of the same component, such as junctions in pandapipes. In order to create such collections for different components of a pandapipes network, there are some functions to be found in the plotting module of pandapipes.

Creating Collections

The following functions can be used to create collections for the most important components of a pandapipes network. Please note that some of these functions in fact return more than just one collection:

create_junction_collection(net, junctions=None, size=5, patch_type='circle', color=None, z=None, cmap=None, norm=None, infofunc=None, picker=False, junction_geodata=None, cbar_title='Junction Pressure [bar]', **kwargs)

Creates a matplotlib patch collection of pandapipes junctions.

Parameters

  • net (pandapipesNet) – The pandapipes network

  • junctions (list, default None) – The junctions for which the collections are created. If None, all junctions in the network are considered.

  • size (int, default 5) – Patch size

  • patch_type (str, default "circle") –

    Patch type, can be

    • ”circle” or “ellipse” for an ellipse (cirlces are just ellipses with the same width + height)

    • ”rect” or “rectangle” for a rectangle

    • ”poly<n>” for a polygon with n edges

  • color (iterable, float, default None) – Color or list of colors for every element

  • z (array, default None) – Array of magnitudes for colormap. Used in case of given cmap. If None, net.res_junction.p_bar is used.

  • cmap (matplotlib colormap object, default None) – colormap for the patch colors

  • norm (matplotlib norm object, default None) – matplotlib norm object

  • infofunc (function, default None) – infofunction for the patch element

  • picker (bool, default False) – Picker argument passed to the patch collection

  • junction_geodata (pandas.DataFrame, default None) – Coordinates to use for plotting. If None, net[“junction_geodata”] is used

  • cbar_title (str, default "Junction Pressure [bar]") – colormap bar title in case of given cmap

  • kwargs – Keyword arguments are passed to the patch function and the patch maker

Returns

pc (matplotlib collection object) - patch collection

create_pipe_collection(net, pipes=None, pipe_geodata=None, junction_geodata=None, use_junction_geodata=False, infofunc=None, cmap=None, norm=None, picker=False, z=None, cbar_title='Pipe Loading [%]', clim=None, **kwargs)

Creates a matplotlib pipe collection of pandapipes pipes.

Parameters

  • net (pandapipesNet) – The pandapipes network

  • pipes (list, default None) – The pipes for which the collections are created. If None, all pipes in the network are considered.

  • pipe_geodata (pandas.DataFrame, default None) – Coordinates to use for plotting. If None, net[“pipe_geodata”] is used.

  • junction_geodata (pandas.DataFrame, default None) – Coordinates to use for plotting in case of use_junction_geodata=True. If None, net[“junction_geodata”] is used.

  • use_junction_geodata (bool, default False) – Defines whether junction or pipe geodata are used.

  • infofunc (function, default None) – infofunction for the line element

  • cmap (matplotlib norm object, default None) – colormap for the line colors

  • norm (matplotlib norm object, default None) – matplotlib norm object

  • picker (bool, default False) – Picker argument passed to the patch collection

  • z (array, default None) – Array of pipe loading magnitudes for colormap. Used in case of given cmap. If None, net.res_pipe.loading_percent is used.

  • cbar_title (str, default "Pipe Loading [%]") – colormap bar title in case of given cmap

  • clim (tuple of floats, default None) – Setting the norm limits for image scaling

  • kwargs – Keyword arguments are passed to the patch function and the patch maker

Returns

lc (matplotlib line collection) - line collection for pipes

create_sink_collection(net, sinks=None, size=1.0, infofunc=None, picker=False, orientation=2.6179938779914944, cmap=None, norm=None, z=None, **kwargs)

Creates a matplotlib patch collection of pandapipes sinks.

Parameters

  • net (pandapipesNet) – The pandapipes network

  • sinks (list, default None) – The sinks for which the collections are created. If None, all sinks connected to junctions that have junction_geodata entries are considered.

  • size (float, default 1) – Patch size

  • infofunc (function, default None) – infofunction for the patch element

  • picker (bool, default False) – Picker argument passed to the patch collection

  • orientation (float, default np.pi*(5/6)) – Orientation of sink collection. pi is directed downwards, increasing values lead to clockwise direction changes.

  • cmap (matplotlib norm object, default None) – colormap for the sink colors

  • norm (matplotlib norm object, default None) – matplotlib norm object to normalize the values of z

  • z (array, default None) – Array of sink result magnitudes for colormap. Used in case of given cmap. If None, net.res_sink.mdot_kg_per_s is used.

  • kwargs – Keyword arguments are passed to the patch function

Returns

sink_pc - patch collection, sink_lc - line collection

create_source_collection(net, sources=None, size=1.0, infofunc=None, picker=False, orientation=3.665191429188092, cmap=None, norm=None, z=None, **kwargs)

Creates a matplotlib patch collection of pandapipes sources.

Parameters

  • net (pandapipesNet) – The pandapipes network

  • sources (list, default None) – The sources for which the collections are created. If None, all sources connected to junctions that have junction_geodata entries are considered.

  • size (float, default 1.) – Patch size

  • infofunc (function, default None) – infofunction for the patch element

  • picker (bool, default False) – Picker argument passed to the patch collection

  • orientation (float, default np.pi*(7/6)) – Orientation of source collection. pi is directed downwards, increasing values lead to clockwise direction changes.

  • cmap (matplotlib norm object, default None) – colormap for the source colors

  • norm (matplotlib norm object, default None) – matplotlib norm object to normalize the values of z

  • z (array, default None) – Array of source result magnitudes for colormap. Used in case of given cmap. If None, net.res_source.mdot_kg_per_s is used.

  • kwargs – Keyword arguments are passed to the patch function

Returns

source_pc - patch collection, source_lc - line collection

create_ext_grid_collection(net, size=1.0, infofunc=None, orientation=0, picker=False, ext_grids=None, ext_grid_junctions=None, **kwargs)

Creates a matplotlib patch collection of pandapipes ext_grid. Parameters ext_grids, ext_grid_junctions can be used to specify, which ext_grids the collection should be created for.

Parameters

  • net (pandapipesNet) – The pandapipes network

  • size (float, default 1.) – Patch size

  • infofunc (function, default None) – infofunction for the patch element

  • orientation (float, default 0) – Orientation of ext_grid collection. 0 is directed upwards, increasing values lead to clockwise direction changes.

  • picker (bool, default False) – Picker argument passed to the patch collection

  • ext_grids (list, default None) – The ext_grids for which the collections are created. If None, all ext_grids which have the entry coords in ext_grid_geodata are considered.

  • ext_grid_junctions (np.ndarray, default None) – Junctions to be used as ext_grid locations

  • kwargs – Keyword arguments are passed to the patch function

Returns

ext_grid1 - patch collection, ext_grid2 - patch collection

create_valve_collection(net, valves=None, size=5.0, junction_geodata=None, infofunc=None, picker=False, fill_closed=True, respect_valves=False, **kwargs)

Creates a matplotlib patch collection of pandapipes junction-junction valves. Valves are plotted in the center between two junctions with a “helper” line (dashed and thin) being drawn between the junctions as well.

Parameters

  • net (pandapipesNet) – The pandapipes network

  • valves (list, default None) – The valves for which the collections are created. If None, all valves which have entries in the respective junction geodata will be plotted.

  • size (float, default 5.) – Patch size

  • junction_geodata (pandas.DataFrame, default None) – Coordinates to use for plotting. If None, net[“junction_geodata”] is used.

  • infofunc (function, default None) – infofunction for the patch element

  • picker (bool, default False) – Picker argument passed to the patch collection

  • fill_closed (bool, default True) – If True, valves with parameter opened == False will be filled and those with opened == True will have a white facecolor. Vice versa if False.

  • kwargs – Keyword arguments are passed to the patch function

Returns

lc - line collection, pc - patch collection

create_heat_exchanger_collection(net, heat_ex=None, size=5.0, junction_geodata=None, infofunc=None, picker=False, **kwargs)

Creates a matplotlib patch collection of pandapipes junction-junction heat_exchangers. Heat_exchangers are plotted in the center between two junctions with a “helper” line (dashed and thin) being drawn between the junctions as well.

Parameters

  • net (pandapipesNet) – The pandapipes network

  • size (float, default 2.) – Patch size

  • helper_line_style (str, default ":") – Line style of the “helper” line being plotted between two junctions connected by a junction-junction heat_exchanger

  • helper_line_size (float, default 1.) – Line width of the “helper” line being plotted between two junctions connected by a junction-junction heat_exchanger

  • helper_line_color (str, default "gray") – Line color of the “helper” line being plotted between two junctions connected by a junction-junction valve

  • orientation (float, default np.pi/2) – Orientation of heat_exchanger collection. pi is directed downwards, increasing values lead to clockwise direction changes.

  • kwargs – Keyword arguments are passed to the patch function

Returns

heat_exchanger, helper_lines

Return type

tuple of patch collections

create_pump_collection(net, pumps=None, table_name='pump', size=5.0, junction_geodata=None, infofunc=None, picker=False, fj_col='from_junction', tj_col='to_junction', **kwargs)

Creates a matplotlib patch collection of pandapipes pumps.

Parameters

  • net (pandapipesNet) – The pandapipes network

  • pumps (list, default None) – The pumps for which the collections are created. If None, all pumps which have entries in the respective junction geodata will be plotted.

  • table_name (str, default 'pump') – Name of the pump table from which to get the data.

  • size (float, default 5.) – Patch size

  • junction_geodata (pandas.DataFrame, default None) – Coordinates to use for plotting. If None, net[“junction_geodata”] is used.

  • infofunc (function, default None) – infofunction for the patch element

  • fj_col (str, default "to_junction") – name of the from_junction column (can be different for different pump types)

  • fj_col – name of the to_junction column (can be different for different pump types)

  • picker (bool, default False) – Picker argument passed to the patch collection

  • kwargs – Keyword arguments are passed to the patch function

Returns

lc - line collection, pc - patch collection

create_compressor_collection(net, cmprs=None, table_name='compressor', size=5.0, junction_geodata=None, color='k', infofunc=None, picker=False, **kwargs)

Creates a matplotlib patch collection of pandapipes compressors. Compressors are plotted in the center between two junctions.

Parameters

  • net (pandapipesNet) – The pandapipes network

  • cmprs (list, default None) – The compressors for which the collections are created. If None, all compressor which have entries in the respective junction geodata will be plotted.

  • size (float, default 5.) – Patch size

  • junction_geodata (pandas.DataFrame, default None) – Coordinates to use for plotting. If None, net[“junction_geodata”] is used.

  • colors (iterable, float, default None) – Color or list of colors for every compressor

  • infofunc (function, default None) – infofunction for the patch element

  • picker (bool, default False) – Picker argument passed to the patch collection

  • kwargs – Keyword arguments are passed to the patch function

Returns

lc - line collection, pc - patch collection

create_pressure_control_collection(net, pcs=None, table_name='press_control', size=5.0, junction_geodata=None, color='k', infofunc=None, picker=False, **kwargs)

Creates a matplotlib patch collection of pandapipes pressure controllers.

Parameters

  • net (pandapipesNet) – The pandapipes network

  • pcs (list, default None) – The pressure controllers for which the collections are created. If None, all pressure controllers which have entries in the respective junction geodata will be plotted.

  • size (float, default 5.) – Patch size

  • junction_geodata (pandas.DataFrame, default None) – Coordinates to use for plotting. If None, net[“junction_geodata”] is used.

  • colors (iterable, float, default None) – Color or list of colors for every valve

  • infofunc (function, default None) – infofunction for the patch element

  • picker (bool, default False) – Picker argument passed to the patch collection

  • kwargs – Keyword arguments are passed to the patch function

Returns

lc - line collection, pc - patch collection

create_flow_control_collection(net, flow_controllers=None, size=5.0, junction_geodata=None, infofunc=None, picker=False, fill_closed=True, respect_in_service=False, **kwargs)

Creates a matplotlib patch collection of pandapipes flow control components.

They are plotted in the center between two junctions and look like a valve with a T on top, if the flow control is active and an I on top, if the flow control is not active.

Parameters

  • net (pandapipesNet) – The pandapipes network

  • flow_controllers (list, default None) – The flow_controllers for which the collections are created. If None, all flow_controllers which have entries in the respective junction geodata will be plotted.

  • size (float, default 5.) – Patch size

  • junction_geodata (pandas.DataFrame, default None) – Coordinates to use for plotting. If None, net[“junction_geodata”] is used.

  • infofunc (function, default None) – infofunction for the patch element

  • picker (bool, default False) – Picker argument passed to the patch collection

  • fill_closed (bool, default True) – If True, flow_controllers with parameter in_service == False will be filled and those with in_service == True will have a white facecolor. Vice versa if False.

  • respect_in_service (bool default False) – if True, out-of-service flow controllers will not be plotted

  • kwargs – Keyword arguments are passed to the patch function

Returns

lc - line collection, pc - patch collection

A bunch of standard collections can be created by create_simple_collections. If the collections should be plotted immediately, use simple_plot.

create_simple_collections(net, respect_valves=False, respect_in_service=True, pipe_width=5.0, junction_size=1.0, ext_grid_size=1.0, plot_sinks=False, plot_sources=False, sink_size=1.0, source_size=1.0, valve_size=1.0, pump_size=1.0, heat_exchanger_size=1.0, pressure_control_size=1.0, compressor_size=1.0, flow_control_size=1.0, scale_size=True, junction_color='r', pipe_color='silver', ext_grid_color='orange', valve_color='silver', pump_color='silver', heat_exchanger_color='silver', pressure_control_color='silver', compressor_color='silver', flow_control_color='silver', library='igraph', as_dict=True, **kwargs)

Plots a pandapipes network as simple as possible. If no geodata is available, artificial geodata is generated. For advanced plotting see the tutorial

Parameters

  • net (pandapipesNet) – The pandapipes format network.

  • respect_valves (bool default False) – Respect valves if artificial geodata is created. .. note:: This Flag is ignored if plot_line_switches is True

  • respect_in_service (bool default True) – Respect only components which are in service.

  • pipe_width (float, default 5.0) – width of pipes

  • junction_size (float, default 1.0) – Relative size of junctions to plot. The value junction_size is multiplied with mean_distance_between_buses, which equals the distance between the max geoocord and the min divided by 200: mean_distance_between_buses = sum((net[‘bus_geodata’].max() - net[‘bus_geodata’].min()) / 200)

  • ext_grid_size (float, default 1.0) – Relative size of ext_grids to plot. See bus sizes for details. Note: ext_grids are plottet as rectangles

  • plot_sinks (bool, default False) – Flag to decide whether sink symbols should be drawn.

  • plot_sources (bool, default False) – Flag to decide whether source symbols should be drawn.

  • sink_size (float, default 1.0) – Relative size of sinks to plot.

  • source_size (float, default 1.0) – Relative size of sources to plot.

  • valve_size (float, default 1.0) – Relative size of valves to plot.

  • pump_size (float, default 1.0) – Relative size of pumps to plot.

  • heat_exchanger_size (float, default 1.0) – Relative size of heat_exchanger to plot.

  • pressure_control_size (float, default 1.0) – Relative size of pres_control to plot.

  • compressor_size (float, default 1.0) – Relative size of compressor to plot.

  • flow_control_size (float, default 1.0) – Relative size of flow_control to plot.

  • scale_size (bool, default True) – Flag if junction_size, ext_grid_size, valve_size- and distance will be scaled with respect to grid mean distances

  • junction_color (str, tuple, default "r") – Junction Color. See also matplotlib or seaborn documentation on how to choose colors.

  • pipe_color (str, tuple, default "silver") – Pipe Color.

  • ext_grid_color (str, tuple, default "orange") – External Grid Color.

  • valve_color (str, tuple, default "silver") – Valve Color.

  • pump_color (str, tuple, default "silver") – Pump Color.

  • heat_exchanger_color (str, tuple, default "silver") – Heat Exchanger Color.

  • pressure_control_color (str, tuple, default "silver") – Pressure Control Color.

  • compressor_color (str, tuple, default "silver") – Compressor Color.

  • flow_control_color (str, tuple, default "silver") – Flow Control Color.

  • library (str, default "igraph") – library name to create generic coordinates (case of missing geodata). Choose “igraph” to use igraph package or “networkx” to use networkx package. NOTE: Currently the networkx implementation is not working!

  • as_dict (bool, default True) – flag whether to return dictionary for network components or just a list

Returns

collections - list of simple collections for the given network

Drawing Collections

In order to draw a number of created collections, they can be added to a list and handed over to the function draw_collections() which is actually part of pandapower. It returns a matplotlib axes, which can be extended by using add_collections_to_axes().

draw_collections(collections, figsize=(10, 8), ax=None, plot_colorbars=True, set_aspect=True, axes_visible=(False, False), copy_collections=True, draw=True)

Draws matplotlib collections which can be created with the create collection functions.

Input:

collections (list) - iterable of collection objects, may include tuples of collections

OPTIONAL:

figsize (tuple, (10,8)) - figsize of the matplotlib figure

ax (axis, None) - matplotlib axis object to plot into, new axis is created if None

plot_colorbars (bool, True) - defines whether colorbars should be plotted

set_aspect (bool, True) - defines whether ‘equal’ and ‘datalim’ aspects of axis scaling should be set.

axes_visible (tuple, (False, False)) - defines visibility of (xaxis, yaxis)

OUTPUT:

ax - matplotlib axes

add_collections_to_axes(ax, collections, plot_colorbars=True, copy_collections=True)