drawing package

Submodules

drawing.rubber_band module

drawing.rubber_band.draw(H, pos=None, with_color=True, with_node_counts=False, with_edge_counts=False, layout=<function spring_layout>, layout_kwargs={}, ax=None, node_radius=None, edges_kwargs={}, nodes_kwargs={}, edge_labels={}, edge_labels_kwargs={}, node_labels={}, node_labels_kwargs={}, with_edge_labels=True, with_node_labels=True, label_alpha=0.35, return_pos=False)

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 (Hypergraph) – the entity to be drawn

• pos (dict) – mapping of node and edge positions to R^2

• with_color (bool) – set to False to disable color cycling of edges

• with_node_counts (bool) – set to True to replace the label for collapsed nodes with the number of elements

• with_edge_counts (bool) – set to True to label collapsed edges with number of elements

• 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

• 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_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

• label_alpha (float) – the transparency (alpha) of the box behind text drawn in the figure

drawing.rubber_band.draw_hyper_edge_labels(H, polys, labels={}, ax=None, **kwargs)

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 (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={}, dr=None, **kwargs)

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

Parameters:

• H (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, node_radius={}, ax=None, labels={}, **kwargs)

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 (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)

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 (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)

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 (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)

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 (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, layout=<function spring_layout>, **kwargs)

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 (Hypergraph) – the entity to be drawn

• 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)

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 (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)

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 (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)

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

Parameters:

• H (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)

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 (Hypergraph) – the entity to be drawn

• spacing (float) – amount of whitespace between disconnected components

drawing.util module

drawing.util.get_collapsed_size(v)

drawing.util.get_frozenset_label(S, count=False, override={})

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)

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 (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)

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 (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)

drawing.util.inflate_kwargs(items, kwargs)

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.transpose_inflated_kwargs(inflated)

Module contents

drawing.draw(H, pos=None, with_color=True, with_node_counts=False, with_edge_counts=False, layout=<function spring_layout>, layout_kwargs={}, ax=None, node_radius=None, edges_kwargs={}, nodes_kwargs={}, edge_labels={}, edge_labels_kwargs={}, node_labels={}, node_labels_kwargs={}, with_edge_labels=True, with_node_labels=True, label_alpha=0.35, return_pos=False)

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 (Hypergraph) – the entity to be drawn

• pos (dict) – mapping of node and edge positions to R^2

• with_color (bool) – set to False to disable color cycling of edges

• with_node_counts (bool) – set to True to replace the label for collapsed nodes with the number of elements

• with_edge_counts (bool) – set to True to label collapsed edges with number of elements

• 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

• 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_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

• label_alpha (float) – the transparency (alpha) of the box behind text drawn in the figure

drawing.draw_two_column(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)

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 (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