drawing package

Submodules

drawing.rubber_band module

drawing.rubber_band.add_edge_defaults(H, edges_kwargs)[source]

drawing.rubber_band.draw(H, pos=None, layout=<function spring_layout>, layout_kwargs={}, ax=None, node_radius=None, fill_edges=False, fill_edge_alpha=-0.5, edges_kwargs={}, nodes_kwargs={}, edge_labels_on_edge=True, edge_labels=None, edge_labels_kwargs={}, node_labels=None, node_labels_kwargs={}, with_edge_labels=True, with_node_labels=True, node_label_alpha=0.35, edge_label_alpha=0.35, with_additional_edges=None, contain_hyper_edges=False, additional_edges_kwargs={}, return_pos=False)[source]

Draw a hypergraph as a Matplotlib figure

By default this will draw a colorful “rubber band” like hypergraph, where convex hulls represent edges and are drawn around the nodes they contain.

This is a convenience function that wraps calls with sensible parameters to the following lower-level drawing functions:

draw_hyper_edges,
draw_hyper_edge_labels,
draw_hyper_labels, and
draw_hyper_nodes

The default layout algorithm is nx.spring_layout, but other layouts can be passed in. The Hypergraph is converted to a bipartite graph, and the layout algorithm is passed the bipartite graph.

If you have a pre-determined layout, you can pass in a “pos” dictionary. This is a dictionary mapping from node id’s to x-y coordinates. For example:

>>> pos = {
>>> 'A': (0, 0),
>>> 'B': (1, 2),
>>> 'C': (5, -3)
>>> }

will position the nodes {A, B, C} manually at the locations specified. The coordinate system is in Matplotlib “data coordinates”, and the figure will be centered within the figure.

By default, this will draw in a new figure, but the axis to render in can be specified using ax.

This approach works well for small hypergraphs, and does not guarantee a rigorously “correct” drawing. Overlapping of sets in the drawing generally implies that the sets intersect, but sometimes sets overlap if there is no intersection. It is not possible, in general, to draw a “correct” hypergraph this way for an arbitrary hypergraph, in the same way that not all graphs have planar drawings.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
pos (dict) – mapping of node and edge positions to R^2
layout (function) – layout algorithm to compute
layout_kwargs (dict) – keyword arguments passed to layout function
ax (Axis) – matplotlib axis on which the plot is rendered
fill_edges (bool) – set to True to fill set the facecolor of edges to a lighter version of the edgecolor if no facecolor is otherwise specified
fill_edge_alpha (float) – amount to add to the alpha channel when filling edges. Should be between -1 and 0, causing a decrease in alpha
edges_kwargs (dict) – keyword arguments passed to matplotlib.collections.PolyCollection for edges
node_radius (None, int, float, or dict) – radius of all nodes, or dictionary of node:value; the default (None) calculates radius based on number of collapsed nodes; reasonable values range between 1 and 3
nodes_kwargs (dict) – keyword arguments passed to matplotlib.collections.PolyCollection for nodes
edge_labels_on_edge (bool) – whether to draw edge labels on the edge (rubber band) or inside
edge_labels_kwargs (dict) – keyword arguments passed to matplotlib.annotate for edge labels
node_labels_kwargs (dict) – keyword argumetns passed to matplotlib.annotate for node labels
with_edge_labels (bool) – set to False to make edge labels invisible
with_node_labels (bool) – set to False to make node labels invisible
node_label_alpha (float) – the transparency (alpha) of the box behind text drawn in the figure for node labels
edge_label_alpha (float) – the transparency (alpha) of the box behind text drawn in the figure for edge labels
with_additional_edges (networkx.Graph) –
…
contain_hyper_edges (bool) – whether the rubber band shoudl be drawn around the location of the edge in the bipartite graph. This may be invisibile unless “with_additional_edges” contains this information.

drawing.rubber_band.draw_hyper_edge_labels(H, pos, labels, polys, edge_labels_on_edge=True, ax=None, **kwargs)[source]

Draws a label on the hyper edge boundary.

Should be passed Matplotlib PolyCollection representing the hyper-edges, see the return value of draw_hyper_edges.

The label will be draw on the least curvy part of the polygon, and will be aligned parallel to the orientation of the polygon where it is drawn.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
polys (PolyCollection) – collection of polygons returned by draw_hyper_edges
labels (dict) – mapping of node id to string label
ax (Axis) – matplotlib axis on which the plot is rendered
kwargs (dict) – Keyword arguments are passed through to Matplotlib’s annotate function.

drawing.rubber_band.draw_hyper_edges(H, pos, ax=None, node_radius={}, contain_hyper_edges=False, dr=None, fill_edges=False, fill_edge_alpha=-0.5, **kwargs)[source]

Draws a convex hull around the nodes contained within each edge in H

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
pos (dict) – mapping of node and edge positions to R^2
node_radius (dict) – mapping of node to R^1 (radius of each node)
dr (float) – the spacing between concentric rings
ax (Axis) – matplotlib axis on which the plot is rendered
kwargs (dict) – keyword arguments, e.g., linewidth, facecolors, are passed through to the PolyCollection constructor

Returns:

a Matplotlib PolyCollection that can be further styled

Return type:

PolyCollection

drawing.rubber_band.draw_hyper_labels(H, pos, labels, node_radius={}, ax=None, **kwargs)[source]

Draws text labels for the hypergraph nodes.

The label is drawn to the right of the node. The node radius is needed (see draw_hyper_nodes) so the text can be offset appropriately as the node size changes.

The text label can be customized by passing in a dictionary, labels, mapping a node to its custom label. By default, the label is the string representation of the node.

Keyword arguments are passed through to Matplotlib’s annotate function.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
pos (dict) – mapping of node and edge positions to R^2
node_radius (dict) – mapping of node to R^1 (radius of each node)
ax (Axis) – matplotlib axis on which the plot is rendered
labels (dict) – mapping of node to text label
kwargs (dict) – keyword arguments passed to matplotlib.annotate

drawing.rubber_band.draw_hyper_nodes(H, pos, node_radius={}, r0=None, ax=None, **kwargs)[source]

Draws a circle for each node in H.

The position of each node is specified by the a dictionary/list-like, pos, where pos[v] is the xy-coordinate for the vertex. The radius of each node can be specified as a dictionary where node_radius[v] is the radius. If a node is missing from this dictionary, or the node_radius is not specified at all, a sensible default radius is chosen based on distances between nodes given by pos.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
pos (dict) – mapping of node and edge positions to R^2
node_radius (dict) – mapping of node to R^1 (radius of each node)
r0 (float) – minimum distance that concentric rings start from the node position
ax (Axis) – matplotlib axis on which the plot is rendered
kwargs (dict) – keyword arguments, e.g., linewidth, facecolors, are passed through to the PolyCollection constructor

Returns:

a Matplotlib PolyCollection that can be further styled

Return type:

PolyCollection

drawing.rubber_band.get_default_radius(H, pos)[source]

Calculate a reasonable default node radius

This function iterates over the hyper edges and finds the most distant pair of points given the positions provided. Then, the node radius is a fraction of the median of this distance take across all hyper-edges.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
pos (dict) – mapping of node and edge positions to R^2

Returns:

the recommended radius

Return type:

float

drawing.rubber_band.layout_hyper_edges(H, pos, node_radius={}, dr=None, contain_hyper_edges=False)[source]

Draws a convex hull for each edge in H.

Position of the nodes in the graph is specified by the position dictionary, pos. Convex hulls are spaced out such that if one set contains another, the convex hull will surround the contained set. The amount of spacing added between hulls is specified by the parameter, dr.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
pos (dict) – mapping of node and edge positions to R^2
node_radius (dict) – mapping of node to R^1 (radius of each node)
dr (float) – the spacing between concentric rings
ax (Axis) – matplotlib axis on which the plot is rendered

Returns:

A mapping from hyper edge ids to paths (Nx2 numpy matrices)

Return type:

dict

drawing.rubber_band.layout_node_link(H, G=None, layout=<function spring_layout>, **kwargs)[source]

Helper function to use a NetwrokX-like graph layout algorithm on a Hypergraph

The hypergraph is converted to a bipartite graph, allowing the usual graph layout techniques to be applied.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
G (Graph) – an additional set of links to consider during the layout process
layout (function) – the layout algorithm which accepts a NetworkX graph and keyword arguments
kwargs (dict) – Keyword arguments are passed through to the layout algorithm

Returns:

mapping of node and edge positions to R^2

Return type:

dict

drawing.two_column module

drawing.two_column.draw(H, with_node_labels=True, with_edge_labels=True, with_node_counts=False, with_edge_counts=False, with_color=True, edge_kwargs=None, ax=None)[source]

Draw a hypergraph using a two-collumn layout.

This is intended reproduce an illustrative technique for bipartite graphs and hypergraphs that is typically used in papers and textbooks.

The left column is reserved for nodes and the right column is reserved for edges. A line is drawn between a node an an edge

The order of nodes and edges is optimized to reduce line crossings between the two columns. Spacing between disconnected components is adjusted to make the diagram easier to read, by reducing the angle of the lines.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
with_node_labels (bool) – False to disable node labels
with_edge_labels (bool) – False to disable edge labels
with_node_counts (bool) – set to True to label collapsed nodes with number of elements
with_edge_counts (bool) – set to True to label collapsed edges with number of elements
with_color (bool) – set to False to disable color cycling of hyper edges
edge_kwargs (dict) – keyword arguments to pass to matplotlib.LineCollection
ax (Axis) – matplotlib axis on which the plot is rendered

drawing.two_column.draw_hyper_edges(H, pos, ax=None, **kwargs)[source]

Renders hyper edges for the two column layout.

Each node-hyper edge membership is rendered as a line connecting the node in the left column to the edge in the right column.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
pos (dict) – mapping of node and edge positions to R^2
ax (Axis) – matplotlib axis on which the plot is rendered
kwargs (dict) – keyword arguments passed to matplotlib.LineCollection

Returns:

the hyper edges

Return type:

LineCollection

drawing.two_column.draw_hyper_labels(H, pos, labels={}, with_node_labels=True, with_edge_labels=True, ax=None)[source]

Renders hyper labels (nodes and edges) for the two column layout.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
pos (dict) – mapping of node and edge positions to R^2
labels (dict) – custom labels for nodes and edges can be supplied
with_node_labels (bool) – False to disable node labels
with_edge_labels (bool) – False to disable edge labels
ax (Axis) – matplotlib axis on which the plot is rendered
kwargs (dict) – keyword arguments passed to matplotlib.LineCollection

drawing.two_column.layout_two_column(H, spacing=2)[source]

Two column (bipartite) layout algorithm.

This algorithm first converts the hypergraph into a bipartite graph and then computes connected components. Disonneccted components are handled independently and then stacked together.

Within a connected component, the spectral ordering of the bipartite graph provides a quick and dirty ordering that minimizes edge crossings in the diagram.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
spacing (float) – amount of whitespace between disconnected components

drawing.util module

drawing.util.create_labels(equivalence_classes, with_counts=True, include_singletons=False, with_labels=True, as_set=False)[source]

Convenience function to format labels for collapsed hyper graphs.

Use hypernetx.Hypergraph.collapse_nodes(return_equivalence_classes=True), for example, to generate the collapsed hypergraph and equivalence classes to input to this function.

Parameters:

equivalence_classes (dict) – equivalence classes mapping an entity to a list of entities to be labeled
with_counts (bool) – show the number of items in the equivalence class
include_singletons (bool) – show the number even if the number of items is 1
with_labels (bool) – show the representative of the equivalence class (the key in the dictionary)
as_set (bool) – show the label as a set of all the members

drawing.util.get_collapsed_size(v)[source]

drawing.util.get_frozenset_label(S, count=False, override=None)[source]

Helper function for rendering the labels of possibly collapsed nodes and edges

Parameters:

S (iterable) – list of entities to be labeled
count (bool) – True if labels should be counts of entities instead of list

Returns:

mapping of entity to its string representation

Return type:

dict

drawing.util.get_line_graph(H, collapse=True)[source]

Computes the line graph, a directed graph, where a directed edge (u, v) exists if the edge u is a subset of the edge v in the hypergraph.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
collapse (bool) – True if edges should be added if hyper edges are identical

Returns:

A directed graph

Return type:

networkx.DiGraph

drawing.util.get_set_layering(H, collapse=True)[source]

Computes a layering of the edges in the hyper graph.

In this layering, each edge is assigned a level. An edge u will be above (e.g., have a smaller level value) another edge v if v is a subset of u.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
collapse (bool) – True if edges should be added if hyper edges are identical

Returns:

a mapping of vertices in H to integer levels

Return type:

dict

drawing.util.inflate(items, v)[source]

drawing.util.inflate_kwargs(items, kwargs)[source]

Helper function to expand keyword arguments.

Parameters:

n (int) – length of resulting list if argument is expanded
kwargs (dict) – keyword arguments to be expanded

Returns:

dictionary with same keys as kwargs and whose values are lists of length n

Return type:

dict

drawing.util.inflate_labels(entities, labels, labels_kwargs)[source]

drawing.util.layout_with_radius(B, node_and_edge_radius=1, **kwargs)[source]

Convenience function allowing the user to specify ideal radii for nodes and edges in the drawing

The Kamada-Kawai (networkx.kamada_kawai_layout) algorithm is used. The algorithm is passed a all pairs shorteset path matrix that is calculated from the bipartite graph input. The shortest path is determined

Parameters:

B (nx.Graph) – a bipartite graph representing the hypergraph
node_and_edge_radius (float, int, dict, list, or function) – encoding of the radii of nodes in B, which are hyper-edges or hyper-nodes (0 by default)
kwargs (dict) – Keyword arguments are passed through to the networkx.kamada_kawai_layout function

Returns:

mapping of node and edge positions to R^2

Return type:

dict

drawing.util.transpose_inflated_kwargs(inflated)[source]

Module contents

drawing.draw(H, pos=None, layout=<function spring_layout>, layout_kwargs={}, ax=None, node_radius=None, fill_edges=False, fill_edge_alpha=-0.5, edges_kwargs={}, nodes_kwargs={}, edge_labels_on_edge=True, edge_labels=None, edge_labels_kwargs={}, node_labels=None, node_labels_kwargs={}, with_edge_labels=True, with_node_labels=True, node_label_alpha=0.35, edge_label_alpha=0.35, with_additional_edges=None, contain_hyper_edges=False, additional_edges_kwargs={}, return_pos=False)[source]

Draw a hypergraph as a Matplotlib figure

By default this will draw a colorful “rubber band” like hypergraph, where convex hulls represent edges and are drawn around the nodes they contain.

This is a convenience function that wraps calls with sensible parameters to the following lower-level drawing functions:

draw_hyper_edges,
draw_hyper_edge_labels,
draw_hyper_labels, and
draw_hyper_nodes

The default layout algorithm is nx.spring_layout, but other layouts can be passed in. The Hypergraph is converted to a bipartite graph, and the layout algorithm is passed the bipartite graph.

If you have a pre-determined layout, you can pass in a “pos” dictionary. This is a dictionary mapping from node id’s to x-y coordinates. For example:

>>> pos = {
>>> 'A': (0, 0),
>>> 'B': (1, 2),
>>> 'C': (5, -3)
>>> }

will position the nodes {A, B, C} manually at the locations specified. The coordinate system is in Matplotlib “data coordinates”, and the figure will be centered within the figure.

By default, this will draw in a new figure, but the axis to render in can be specified using ax.

This approach works well for small hypergraphs, and does not guarantee a rigorously “correct” drawing. Overlapping of sets in the drawing generally implies that the sets intersect, but sometimes sets overlap if there is no intersection. It is not possible, in general, to draw a “correct” hypergraph this way for an arbitrary hypergraph, in the same way that not all graphs have planar drawings.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
pos (dict) – mapping of node and edge positions to R^2
layout (function) – layout algorithm to compute
layout_kwargs (dict) – keyword arguments passed to layout function
ax (Axis) – matplotlib axis on which the plot is rendered
fill_edges (bool) – set to True to fill set the facecolor of edges to a lighter version of the edgecolor if no facecolor is otherwise specified
fill_edge_alpha (float) – amount to add to the alpha channel when filling edges. Should be between -1 and 0, causing a decrease in alpha
edges_kwargs (dict) – keyword arguments passed to matplotlib.collections.PolyCollection for edges
node_radius (None, int, float, or dict) – radius of all nodes, or dictionary of node:value; the default (None) calculates radius based on number of collapsed nodes; reasonable values range between 1 and 3
nodes_kwargs (dict) – keyword arguments passed to matplotlib.collections.PolyCollection for nodes
edge_labels_on_edge (bool) – whether to draw edge labels on the edge (rubber band) or inside
edge_labels_kwargs (dict) – keyword arguments passed to matplotlib.annotate for edge labels
node_labels_kwargs (dict) – keyword argumetns passed to matplotlib.annotate for node labels
with_edge_labels (bool) – set to False to make edge labels invisible
with_node_labels (bool) – set to False to make node labels invisible
node_label_alpha (float) – the transparency (alpha) of the box behind text drawn in the figure for node labels
edge_label_alpha (float) – the transparency (alpha) of the box behind text drawn in the figure for edge labels
with_additional_edges (networkx.Graph) –
…
contain_hyper_edges (bool) – whether the rubber band shoudl be drawn around the location of the edge in the bipartite graph. This may be invisibile unless “with_additional_edges” contains this information.

drawing.draw_bipartite_using_euler(H, pos=None, node_order=None, edge_order=None, edge_labels_kwargs={}, **kwargs)[source]

Draw a hypergraph as a two column bipartite graph using hypernetx.draw.

This function calculates the x- and y-coordinates of nodes and edges by placing edges in the left column and nodes in the right column. The ordering of edges and nodes is determined by default using the networkx.spectral_order method on the bipartite representation of the hypergraph. Node and edge order can also be specified by the user. If one or the other is specified, then the unspecified column (nodes or edges) are sorted using the barycenter method. Additional minor adjustment of node and edge height is performed to improve readability.

Additional encoding kwargs are passed through to the hypernetx.draw method.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
pos (dict) – the positioning of the hypergraph
node_order (list) – specify to override the order of the nodes in the drawing
edge_order (list) – specify to override the order of the edges in the drawing

drawing.draw_incidence_storyline(H, layout=None, layout_kwargs={}, ax=None, fig=None, auto_size=1.0, y_cap_scale=2, edge_order=None, node_order=None, node_labels=None, edge_labels=None, with_node_labels=True, with_edge_labels=True, fill_edges=False, fill_edge_alpha=-0.5, edges_kwargs={}, nodes_kwargs={}, segments_kwargs={}, edge_labels_kwargs={}, node_labels_kwargs={}, edge_labels_on_axis=True, incidences_kwargs={})[source]

Draw a hypergraph as a Storyline with Matplotlib–useful for edge ordered hypergraphs

This drawing has four main elements: * Nodes: drawn as horizontal-ish lines that can bend * Edges: drawin as vertical rounded rectangles * Incidences: the intersection of a node and an edge drawn as a circle * Segments: the portion of a node beetween two incidences

These elements can be flexibly encoded using the same approach for the hypernetx.draw method. For example, the following code will set the color of all nodes to pink:

>>> hypernetx.draw_incidence_storyline(
>>>     H,
>>>     edges_kwargs=dict(color='pink')
>>> )

More on this can be found in the tutorials.

The default layout algorithm is SvenStoryline, which is based on “Storyline Visualization of Events on a Network” (SVEN) [1]. This algorithm can be controlled by passing parameters into the layout_kwargs parameter.

For example: * allow_node_crossings: set to True to allow storylines to cross each other * allow_edge_crossings: set to True to allow storylines to cross edges

One of the two above parameters must be true.

Custom layouts should inherit the Layout class and are passed in using the layout parameter.

Parameters:

H (hnx.Hypergraph) – the entity to be drawn
layout (function) – layout algorithm to compute
layout_kwargs (dict) – keyword arguments passed to layout function
ax (matplotlib.axis.Axis) – axis on which the plot is rendered; if None, uses plt.gca()
fig (matplotlib.figure.Figure) – figure on which the plot is rendered; if None, uses plt.gcf()
auto_size (float) – automatically size and scale the figure based on layout; if None, the figure is not resize
y_cap_scale (float) – adjust pointy-ness of circles drawn on top of edges to adjust distortion caused by figure aspect ratio
edge_order (list) – order to place edges on the x-axis
node_order (list) – suggested ordering of nodes–not necessarily respected because nodes’ lines can cross
node_labels (list, dict, or function) – labels to use for nodes
edge_labels (list, dict, or function) – labels to use for edges
with_edge_labels (bool) – set to False to make edge labels invisible
with_node_labels (bool) – set to False to make node labels invisible
fill_edges (bool) – set to True to fill set the facecolor of edges to a lighter version of the edgecolor if no facecolor is otherwise specified
fill_edge_alpha (float) – amount to add to the alpha channel when filling edges. Should be between -1 and 0, causing a decrease in alpha
edges_kwargs (dict) – keyword arguments passed to matplotlib.collections.PolyCollection for edges
nodes_kwargs (dict) – keyword arguments passed to matplotlib.collections.LineCollection for nodes
segments_kwargs (dict) – keyword arguments passed to matplotlib.collections.LineCollection for segments (overrides nodes_kwargs)
edge_labels_kwargs (dict) – keyword arguments passed to matplotlib.annotate for edge labels
node_labels_kwargs (dict) – keyword argumetns passed to matplotlib.annotate for node labels
edge_labels_on_axis (bool) – when True, draws edge labels on x-axis ticks; otherwise draws edge labels close to the bottom of the edge
incidences_kwargs (dict) – keyword arguments passed to matplotlib.collections.EllipseCollection for incidences

Returns:

the layout object used to position the storylines

Return type:

Layout

References

[1] Arendt, Dustin L., and Leslie M. Blaha. “SVEN: Informative visual representation of complex dynamic structure.” arXiv preprint arXiv:1412.6706 (2014).

drawing.draw_incidence_upset(H, *, node_order=None, edge_order=None, **kwargs)[source]

Draw a hypergraph as an UpSet [1] like diagram with Matplotlib

This uses a spectral ordering of the nodes and edges calculated by Layout to determine the position of nodes and edges. It is similar to the UpSet visulization technique, and is a special case of the storyline layout technique.

Parameters:

H (hypernetx.Hypergraph)
node_order (list) – order to place nodes on the y-axis
edge_order (list) – order to place edges on the x-axis
**kwargs (dict) – passed through to hypernetx.drawing.draw_incidence_storyline

Returns:

the layout object used to position the storylines

Return type:

Layout

References

[1] Lex, Alexander, et al. “UpSet: visualization of intersecting sets.” IEEE transactions on visualization and computer graphics 20.12 (2014): 1983-1992.