Converters#

Hiveplotlib streamlines two different types of conversion:

  • Moving to and from NetworkX (building hive plots from NetworkX graphs and exporting hive plots to NetworkX graphs).

  • Serialization (exporting hive plots to JSON for downstream visualization in other libraries or outside Python).

Much of the low-level conversion machinery lives in hiveplotlib.converters (rendered in full under “Low-Level Converters Module Reference” below), but the JSON serializer exists only as a class method. The curated discussion below makes these converters easy to find from this page.

NetworkX Conversion#

Hiveplotlib supports bidirectional conversion between hiveplotlib data structures and NetworkX graphs.

Converting from NetworkX to a Hive Plot#

Hive plots can be built from any flavor of NetworkX graph (directed, undirected, multigraph, or directed multigraph) most easily via the HivePlot class, which accepts a networkx graph via the graph parameter as an alternative to the usual nodes and edges parameters.

Users can also use the lower-level conversion function hiveplotlib.converters.networkx_to_nodes_edges() to build a (NodeCollection, Edges) pair from a networkx graph.

Converting from a Hive Plot to NetworkX#

Hive plots can be exported to NetworkX graphs via the HivePlot inherited class method to_networkx(), which returns a networkx graph with the hive plot’s node and edge information. The type of returned graph is selectable by the directed and multigraph parameters.

Users can also use the lower-level conversion function hiveplotlib.converters.nodes_edges_to_networkx() to build a networkx graph from a (NodeCollection, Edges) pair.

JSON Serialization#

hiveplotlib.HivePlot.to_json() serializes a hive plot’s axes, node placements, edge curves, and resolved node-viz kwargs (all in Cartesian coordinates) to a JSON string, intended for downstream visualization in other libraries or outside Python.

Low-Level Converters Module Reference#

Converters from various data structures to hiveplotlib-ready structures.

hiveplotlib.converters.networkx_to_nodes_edges(graph: Graph, unique_id_name: str = 'unique_id', check_uniqueness: bool = True) → tuple[NodeCollection, Edges]#

Take a networkx graph and return hiveplotlib-friendly data structures.

Specifically, returns a NodeCollection instance of node data and an Edges instance of edge data. These outputs can be fed directly into HivePlot().

Parameters:

  • graph – networkx graph (any of Graph, DiGraph, MultiGraph, or MultiDiGraph).

  • unique_id_name – name to use for unique IDs.

  • check_uniqueness – whether or not to check that provided Node instances have unique IDs.

Returns:

a (NodeCollection, Edges) pair of hiveplotlib data structures.

hiveplotlib.converters.nodes_edges_to_networkx(nodes: NodeCollection, edges: Edges, *, directed: bool = True, multigraph: bool = True, tag_attribute_name: str = 'tag', source_attribute_name: str | None = None) → Graph#

Convert a (NodeCollection, Edges) pair to a networkx graph.

The concrete return type is determined by directed and multigraph:

The defaults preserve duplicate edges faithfully and assume directed edges.

All non-(from / to) Edges DataFrame columns become edge attributes on the resulting graph. All non-unique_id_column node DataFrame columns become node attributes. The visualization-only attributes node_viz_kwargs / edge_viz_kwargs are not included.

Multi-tag hiveplotlib.Edges: when more than one tag is present, the original tag is written as an edge attribute under tag_attribute_name (default "tag"). If that name collides with an existing column on any tag’s edge DataFrame, a ValueError is raised. Single-tag input does not write a tag attribute.

Optional source-row annotation: pass a string for source_attribute_name to tag each edge with a (tag, row_index) tuple pointing back to its source row in the input hiveplotlib.Edges. This is useful for joining graph-level computations (e.g. edge metrics) back onto the original edge DataFrame (including when there are multiple parallel edges in a multigraph). Default None skips this annotation.

Note

When multigraph=False but duplicate (from, to) pairs exist, networkx’s networkx.Graph / networkx.DiGraph will silently merge duplicates (last write wins). For an undirected networkx.Graph, reciprocal (a, b) / (b, a) rows likewise merge into a single undirected edge (last write wins), so the merged edge carries only the surviving row’s attributes (e.g. a weight). Build with multigraph=True to retain both edges as parallel edges, or pre-aggregate the weights into a single edge beforehand.

Parameters:

  • nodes – hiveplotlib.NodeCollection of node data.

  • edges – hiveplotlib.Edges of edge data (single-tag or multi-tag).

  • directed – whether to return a networkx.DiGraph-family graph. Default True.

  • multigraph – whether to return a Multi*-family graph. Default True.

  • tag_attribute_name – edge-attribute name to use when storing the original tag on multi-tag inputs. Default "tag".

  • source_attribute_name – optional edge-attribute name under which to store a (tag, row_index) source-row identifier for every edge, useful for joining graph-level computations back onto the original edge DataFrame. Default None skips annotation.

Returns:

networkx graph (one of networkx.Graph, networkx.DiGraph, networkx.MultiGraph, or networkx.MultiDiGraph).

Raises:

  • ValueError – if tag_attribute_name collides with an existing edge column on a multi-tag hiveplotlib.Edges instance.

  • ValueError – if source_attribute_name is a string and collides with an existing edge column on any tag.