Hive Plot Matrix#

A HivePlotMatrix is a grid of HivePlot instances for comparative network visualization, analogous to a scatter plot matrix but for hive plots. It supports both convenience methods for common use cases and a generic constructor.

Convenience Methods#

classmethod HivePlotMatrix.from_partition(nodes: NodeCollection | None = None, edges: Edges | ndarray | None = None, *, graph: nx.Graph | None = None, partition_variable: Hashable, sorting_variables: Hashable | Dict[Hashable, Hashable], partition_values: List[Hashable] | None = None, collapsed_group_axis_name: str = 'Other', backend: Literal['matplotlib', 'datashader'] = 'matplotlib', include_diagonal: bool = True, hive_plot_kwargs: Dict | None = None, unify_axes: bool | Dict[Literal['vmin', 'vmax'], float] = False, axis_kwargs: dict | None = None, node_kwargs: dict | None = None, all_edge_kwargs: dict | None = None, repeat_edge_kwargs: dict | None = None, non_repeat_edge_kwargs: dict | None = None, clockwise_edge_kwargs: dict | None = None, counterclockwise_edge_kwargs: dict | None = None, num_steps_per_edge: int = 100, node_graph_metrics: str | Sequence[str] | None = None, edge_graph_metrics: str | Sequence[str] | None = None, node_graph_metric_kwargs: dict[str, dict] | None = None, edge_graph_metric_kwargs: dict[str, dict] | None = None, node_graph_metric_rename: dict[str, str] | None = None, edge_graph_metric_rename: dict[str, str] | None = None, graph_metric_backend: str | None = None, graph_directed: bool | None = None, graph_multigraph: bool | None = None, graph_source_attribute_name: str | None = None, warn_on_parallel_edge_collapse: bool = True, use_numba: bool = True, n_parallel: int | None = None, progress: bool = True) → HivePlotMatrix#

Build a pairwise group matrix for networks with more than 3 groups.

Accepts either of two inputs: tabular data via the nodes (a hiveplotlib.NodeCollection) and edges (a hiveplotlib.Edges instance or a numpy.ndarray of (from, to) pairs), or a NetworkX graph via the graph parameter.

Providing both inputs (or partial inputs) raises a ValueError.

When the graph parameter is provided, graph_directed and graph_multigraph default to graph.is_directed() and graph.is_multigraph() respectively. When nodes and edges are provided, graph_directed defaults to True and graph_multigraph defaults to False. Explicit user values still win in either case. These resolved values are stashed on the resulting HivePlotMatrix and serve as the per-call defaults for any later hiveplotlib.HivePlotMatrix.compute_graph_metrics() call, so a follow-up metric computation will use the same internal-graph type by default.

Note

If you request graph metrics here (via node_graph_metrics / edge_graph_metrics) or later via hiveplotlib.HivePlotMatrix.compute_graph_metrics(), an internal networkx graph is rebuilt from the stored nodes / edges to compute them; an input graph is not reused. The conversion is typically cheap relative to the metrics themselves, but if you want to skip it entirely, attach the metrics as node / edge attributes on graph before passing it (e.g. nx.set_node_attributes(graph, nx.betweenness_centrality(graph), "betweenness")). The converter carries those attributes through as columns on the resulting hiveplotlib.NodeCollection / hiveplotlib.Edges.

Note

Parallel-edge collapse. When graph_multigraph=False (the default for nodes / edges input) and the edge data has same-direction duplicate (from, to) rows, those rows collapse last-write-wins and a UserWarning is emitted (skip it with warn_on_parallel_edge_collapse=False). Reciprocal (a, b) / (b, a) rows that merge only because an undirected build treats the pair symmetrically do not warn (that merge is the definitional meaning of the undirected metric). Either collapse keeps a single row’s attributes, so a metric given an edge weight reflects only one of two differing reciprocal weights. graph_multigraph=True retains both edges only for metrics that accept multigraphs; metrics that require a simple graph (e.g. onion_layers) reject the multigraph, so for those pre-aggregate the reciprocal weights into a single edge before building.

For N groups, creates an N x N upper-triangular matrix:

Diagonal (i, i): repeat axes for the single group.
Off-diagonal (i, j) where i < j: two named groups + collapsed “Other” axis.
Lower triangle: empty (None).

Parameters:

nodes – node data. Default None; required when graph is not provided. Mutually exclusive with graph.
edges – edge data corresponding to provided nodes. If providing a numpy.ndarray of edge data, must be provided as (from, to) pairs. Note, providing an array input does not support the inclusion of edge metadata, whereas the Edges instance input does. Default None; required when graph is not provided. Mutually exclusive with graph.
graph – input networkx graph (any of Graph, DiGraph, MultiGraph, or MultiDiGraph) from which to construct the matrix. Mutually exclusive with the nodes and edges parameters. Default None expects nodes and edges to be provided instead. Distinct from graph_directed / graph_multigraph / graph_source_attribute_name, which configure the internal networkx graph rebuilt for metric computation. To customize the conversion (e.g., override the unique-ID column name or skip the uniqueness check), call hiveplotlib.converters.networkx_to_nodes_edges() directly and pass the resulting nodes and edges instead.
partition_variable – which column in node data to partition on. The unique values of this column define the groups compared in the matrix.
sorting_variables – which column(s) to sort nodes on each axis. Providing a single value uses the same variable for each axis. Alternatively, providing a dictionary of keys as the unique values from partition_variable column data and values being the corresponding sorting variable to use for that axis. Note when providing a dictionary input, _all_ keys for each axis created by the provided partition_variable must be specified (otherwise a MissingSortingVariableError will be raised).
partition_values – which partition values to include and their order. Default None uses all unique values of partition_variable.
collapsed_group_axis_name – name for the collapsed “Other” axis. Default "Other".
backend – visualization backend. Default "matplotlib".
include_diagonal – whether to include diagonal (repeat-axis) cells. Default True.
hive_plot_kwargs – additional keyword arguments passed to each HivePlot constructor.
unify_axes –
whether to unify axis value ranges across all cells. When True, auto-computes global vmin/vmax from the node data and applies them uniformly. When a dict (e.g. {"vmin": 0, "vmax": 10} or {"vmin": 0}), uses explicit values and auto-computes any missing ones. When False (default), axes auto-scale per cell. Pre-computed from the raw data to avoid a double build.

Priority of params: axis_kwargs > explicit dict values > auto-computed values.
axis_kwargs – keyword arguments applied uniformly to every axis in every hive plot cell (e.g. {"vmin": 0, "vmax": 1e9} to fix the display range across all axes). Takes precedence over any "axis_kwargs" key inside hive_plot_kwargs.
node_kwargs – keyword arguments forwarded to the node rendering call for every hive plot cell. For the matplotlib backend these are scatter() kwargs; for the datashader backend these are imshow() kwargs applied to the node rasterization. Can be overridden at plot time by passing node_kwargs directly to plot().
all_edge_kwargs – keyword arguments for all edges. Disregarded when using the "datashader" backend.
repeat_edge_kwargs – keyword arguments for repeat edges (diagonal cells). Disregarded when using the "datashader" backend.
non_repeat_edge_kwargs – keyword arguments for non-repeat edges (off-diagonal cells). Disregarded when using the "datashader" backend.
clockwise_edge_kwargs – keyword arguments for edges going clockwise (off-diagonal cells only). Disregarded when using the "datashader" backend.
counterclockwise_edge_kwargs – keyword arguments for edges going counterclockwise (off-diagonal cells only). Disregarded when using the "datashader" backend.
num_steps_per_edge – number of Bezier curve steps per edge.
node_graph_metrics – optional node graph-metric string name (or sequence of names) to compute and attach as columns to nodes before any sub-plot is constructed. Each name must be a key in hiveplotlib.graph_features.GRAPH_NODE_METRICS. Computed once on the underlying nodes / edges (see graph_directed / graph_multigraph) and the augmented columns are then available as partition_variable / sorting_variables. Default None skips computing any metrics.
edge_graph_metrics – optional edge graph-metric string name (or sequence of names) to compute and attach as columns to edges. Each name must be a key in hiveplotlib.graph_features.GRAPH_EDGE_METRICS. Default None skips computing any metrics.
node_graph_metric_kwargs – per-metric **kwargs to forward to each node-metric wrapper, keyed by metric name (e.g. {"betweenness_centrality": {"normalized": False}}).
edge_graph_metric_kwargs – per-metric **kwargs to forward to each edge-metric wrapper, keyed by metric name (e.g. {"edge_betweenness_centrality": {"normalized": False}}).
node_graph_metric_rename – per-metric override mapping from metric name to the column name used on the resulting hiveplotlib.NodeCollection. Useful for resolving collisions when a metric name already exists as a column.
edge_graph_metric_rename – same as node_graph_metric_rename but for edge metrics.
graph_metric_backend – name of a networkx dispatchable backend on which to compute any requested graph metrics. Default None computes everything on default networkx. The value is stored on the resulting HivePlotMatrix and serves as the default for later hiveplotlib.HivePlotMatrix.compute_graph_metrics() calls (see that method for the full precedence chain). degree, in_degree, and out_degree are direct structural reads of the graph, so backend dispatch does not apply to them (the result is identical either way). See the parameter of the same name on HivePlotMatrix and hiveplotlib.graph_features.compute_graph_metrics() for backend-name validation and fallback behavior.
graph_directed – directionality of the internal networkx graph used for metric computation only; it does not affect how any hive plot cell is rendered. An explicit True / False always wins, and if that value conflicts with a requested metric’s requirement a ValueError is raised. What None (the default) does depends on how the matrix is built. From ``nodes`` / ``edges``: the value is inferred when every requested metric that cares about directedness agrees, so node_graph_metrics="triangles" builds an undirected internal graph without setting the flag; with no such metric it defaults to True, matching the (from, to) semantics of hiveplotlib.Edges. A requested set that is itself contradictory (one metric needs a directed graph, another an undirected one) cannot be inferred and raises the same conflict ValueError. From ``graph``: the value is taken from the input graph (graph.is_directed()) and is not inferred from your metrics, so the graph you passed keeps its own type; if a requested metric needs the opposite (e.g. triangles on a directed graph), you get the conflict ValueError rather than a silent re-typing, so pass an explicit graph_directed or convert the graph first (e.g. graph.to_undirected()).
graph_multigraph – unlike graph_directed, this is never inferred from the requested metrics. It controls whether each row in your hiveplotlib.Edges counts as a distinct edge when metrics are computed (across all tags for multi-tag inputs); it does not affect how any hive plot cell is rendered. Passing True together with a metric that rejects multigraphs raises a ValueError. What None (the default) does depends on how the matrix is built. From ``nodes`` / ``edges``: defaults to False, collapsing repeated (from, to) rows into a single edge in the internal graph; set True to keep them distinct. From ``graph``: defaults to the input graph’s own type (graph.is_multigraph()), so the graph you passed keeps its multi-edge structure. See the note on parallel-edge collapse in this method’s description.
graph_source_attribute_name – edge-attribute name used internally to map each metric value computed on a repeated edge back to its specific source row when graph_multigraph=True. Default None resolves to "_hiveplotlib_source", which works for nearly all use cases; override only if it collides with an existing edge column.
warn_on_parallel_edge_collapse – whether to detect and warn about same-direction duplicate (from, to) edges collapsing during metric computation. Default True. Setting False skips the detection entirely (a performance escape hatch for large graphs); it does not change whether edges collapse (duplicates are still merged last-write-wins). To preserve parallel edges instead, use graph_multigraph=True.
use_numba – whether to use numba for Bezier computation.
n_parallel – number of parallel threads for Bezier computation.
progress – whether to show a progress bar.

Raises:

ValueError – if both graph and the nodes and edges parameters are provided, if no input is provided, or if only one of nodes / edges is provided.
ValueError – if the requested node_graph_metrics / edge_graph_metrics have irreconcilable graph-type requirements for the single internal graph: a directedness standoff (one metric needs a directed graph, another an undirected one, caught across the node/edge boundary since they share one graph), or an explicit graph_directed / graph_multigraph value that conflicts with a requested metric. Raised up front, before any metric runs. Resolve a standoff by building two matrices, one per graph_directed.
InvalidGraphMetricBackendError – if graph metrics are requested and graph_metric_backend (or a per-metric "backend" entry in node_graph_metric_kwargs / edge_graph_metric_kwargs) is not an installed networkx dispatchable backend, targets degree / in_degree / out_degree, or is requested on networkx<3.2. Raised up front, before any metric runs; see hiveplotlib.graph_features.compute_graph_metrics().

Returns:

HivePlotMatrix instance.

classmethod HivePlotMatrix.from_variable_sweep(nodes: NodeCollection | None = None, edges: Edges | ndarray | None = None, *, graph: nx.Graph | None = None, partition_variable: Hashable | None = None, sorting_variables: Hashable | Dict[Hashable, Hashable] | None = None, sorting_variables_list: List[Hashable | Dict[Hashable, Hashable]] | None = None, partition_variables_list: List[Hashable] | None = None, repeat_axes: bool | Hashable | List[Hashable] = False, ncols: int | None = None, backend: Literal['matplotlib', 'datashader'] = 'matplotlib', hive_plot_kwargs: Dict | None = None, unify_axes: bool | Dict[Literal['vmin', 'vmax'], float] = False, axis_kwargs: dict | None = None, node_kwargs: dict | None = None, all_edge_kwargs: dict | None = None, repeat_edge_kwargs: dict | None = None, non_repeat_edge_kwargs: dict | None = None, clockwise_edge_kwargs: dict | None = None, counterclockwise_edge_kwargs: dict | None = None, num_steps_per_edge: int = 100, node_graph_metrics: str | Sequence[str] | None = None, edge_graph_metrics: str | Sequence[str] | None = None, node_graph_metric_kwargs: dict[str, dict] | None = None, edge_graph_metric_kwargs: dict[str, dict] | None = None, node_graph_metric_rename: dict[str, str] | None = None, edge_graph_metric_rename: dict[str, str] | None = None, graph_metric_backend: str | None = None, graph_directed: bool | None = None, graph_multigraph: bool | None = None, graph_source_attribute_name: str | None = None, warn_on_parallel_edge_collapse: bool = True, use_numba: bool = True, n_parallel: int | None = None, progress: bool = True) → HivePlotMatrix#

Build a matrix comparing different sorting and/or partition variables.

Providing both inputs (or partial inputs) raises a ValueError.

Note

Three modes based on which list parameters are provided:

sorting_variables_list only: 1D row, each column uses a different sorting variable (requires partition_variable)
partition_variables_list only: 1D row, each column uses a different partition variable (requires sorting_variables)
Both: 2D grid with rows = partition variables, columns = sorting variables

Parameters:

nodes – node data. Default None; required when graph is not provided. Mutually exclusive with graph.
edges – edge data corresponding to provided nodes. If providing a numpy.ndarray of edge data, must be provided as (from, to) pairs. Note, providing an array input does not support the inclusion of edge metadata, whereas the Edges instance input does. Default None; required when graph is not provided. Mutually exclusive with graph.
graph – input networkx graph (any of Graph, DiGraph, MultiGraph, or MultiDiGraph) from which to construct the matrix. Mutually exclusive with the nodes and edges parameters. Default None expects nodes and edges to be provided instead. Distinct from graph_directed / graph_multigraph / graph_source_attribute_name, which configure the internal networkx graph rebuilt for metric computation. To customize the conversion (e.g., override the unique-ID column name or skip the uniqueness check), call hiveplotlib.converters.networkx_to_nodes_edges() directly and pass the resulting nodes and edges instead.
partition_variable – fixed partition variable (required when only partition_variables_list is not provided).
sorting_variables – fixed sorting variable(s) (required when only sorting_variables_list is not provided).
sorting_variables_list – list of sorting variable configurations to compare.
partition_variables_list – list of partition variables to compare.
repeat_axes – which partition groups to create repeat axes for. True creates repeat axes for all groups, False disables repeat axes. When partition_variables_list is provided, only True / False is accepted (specific axis names vary across partition variables).
ncols – when result is 1D, wrap into rows of ncols width. Ignored when both lists are provided.
backend – visualization backend.
hive_plot_kwargs – additional keyword arguments passed to each HivePlot constructor.
unify_axes –
whether to unify axis value ranges across all cells. When True, auto-computes global vmin/vmax from the node data across all sorting variables and applies them uniformly. When a dict (e.g. {"vmin": 0, "vmax": 10} or {"vmin": 0}), uses explicit values and auto-computes any missing ones. When False (default), axes auto-scale per cell.

Priority of params: axis_kwargs > explicit dict values > auto-computed values.
axis_kwargs – keyword arguments applied uniformly to every axis in every hive plot cell (e.g. {"vmin": 0, "vmax": 1e9} to fix the display range across all axes). Takes precedence over any "axis_kwargs" key inside hive_plot_kwargs.
node_kwargs – keyword arguments forwarded to the node rendering call for every hive plot cell. For the matplotlib backend these are scatter() kwargs; for the datashader backend these are imshow() kwargs applied to the node rasterization. Can be overridden at plot time by passing node_kwargs directly to plot().
all_edge_kwargs – keyword arguments for all edges. Disregarded when using the "datashader" backend.
repeat_edge_kwargs – keyword arguments for repeat edges. Disregarded when using the "datashader" backend.
non_repeat_edge_kwargs – keyword arguments for non-repeat edges. Disregarded when using the "datashader" backend.
clockwise_edge_kwargs – keyword arguments for edges going clockwise. Disregarded when using the "datashader" backend.
counterclockwise_edge_kwargs – keyword arguments for edges going counterclockwise. Disregarded when using the "datashader" backend.
num_steps_per_edge – number of Bezier curve steps per edge.
node_graph_metrics – optional node graph-metric string name (or sequence of names) to compute and attach as columns to nodes before any sub-plot is constructed. Each name must be a key in hiveplotlib.graph_features.GRAPH_NODE_METRICS. Computed once on the underlying nodes / edges (see graph_directed / graph_multigraph) and the augmented columns are then available as partition_variable / sorting_variables / partition_variables_list / sorting_variables_list entries. Default None skips computing any metrics.
edge_graph_metrics – optional edge graph-metric string name (or sequence of names) to compute and attach as columns to edges. Each name must be a key in hiveplotlib.graph_features.GRAPH_EDGE_METRICS. Default None skips computing any metrics.
node_graph_metric_kwargs – per-metric **kwargs to forward to each node-metric wrapper, keyed by metric name (e.g. {"betweenness_centrality": {"normalized": False}}).
edge_graph_metric_kwargs – per-metric **kwargs to forward to each edge-metric wrapper, keyed by metric name (e.g. {"edge_betweenness_centrality": {"normalized": False}}).
node_graph_metric_rename – per-metric override mapping from metric name to the column name used on the resulting hiveplotlib.NodeCollection. Useful for resolving collisions when a metric name already exists as a column.
edge_graph_metric_rename – same as node_graph_metric_rename but for edge metrics.
graph_metric_backend – name of a networkx dispatchable backend on which to compute any requested graph metrics. Default None computes everything on default networkx. The value is stored on the resulting HivePlotMatrix and serves as the default for later hiveplotlib.HivePlotMatrix.compute_graph_metrics() calls (see that method for the full precedence chain). degree, in_degree, and out_degree are direct structural reads of the graph, so backend dispatch does not apply to them (the result is identical either way). See the parameter of the same name on HivePlotMatrix and hiveplotlib.graph_features.compute_graph_metrics() for backend-name validation and fallback behavior.
graph_directed – directionality of the internal networkx graph used for metric computation only; it does not affect how any hive plot cell is rendered. An explicit True / False always wins, and if that value conflicts with a requested metric’s requirement a ValueError is raised. What None (the default) does depends on how the matrix is built. From ``nodes`` / ``edges``: the value is inferred when every requested metric that cares about directedness agrees, so node_graph_metrics="triangles" builds an undirected internal graph without setting the flag; with no such metric it defaults to True, matching the (from, to) semantics of hiveplotlib.Edges. A requested set that is itself contradictory (one metric needs a directed graph, another an undirected one) cannot be inferred and raises the same conflict ValueError. From ``graph``: the value is taken from the input graph (graph.is_directed()) and is not inferred from your metrics, so the graph you passed keeps its own type; if a requested metric needs the opposite (e.g. triangles on a directed graph), you get the conflict ValueError rather than a silent re-typing, so pass an explicit graph_directed or convert the graph first (e.g. graph.to_undirected()).
graph_multigraph – unlike graph_directed, this is never inferred from the requested metrics. It controls whether each row in your hiveplotlib.Edges counts as a distinct edge when metrics are computed (across all tags for multi-tag inputs); it does not affect how any hive plot cell is rendered. Passing True together with a metric that rejects multigraphs raises a ValueError. What None (the default) does depends on how the matrix is built. From ``nodes`` / ``edges``: defaults to False, collapsing repeated (from, to) rows into a single edge in the internal graph; set True to keep them distinct. From ``graph``: defaults to the input graph’s own type (graph.is_multigraph()), so the graph you passed keeps its multi-edge structure. See the note on parallel-edge collapse in this method’s description.
graph_source_attribute_name – edge-attribute name used internally to map each metric value computed on a repeated edge back to its specific source row when graph_multigraph=True. Default None resolves to "_hiveplotlib_source", which works for nearly all use cases; override only if it collides with an existing edge column.
warn_on_parallel_edge_collapse – whether to detect and warn about same-direction duplicate (from, to) edges collapsing during metric computation. Default True. Setting False skips the detection entirely (a performance escape hatch for large graphs); it does not change whether edges collapse (duplicates are still merged last-write-wins). To preserve parallel edges instead, use graph_multigraph=True.
use_numba – whether to use numba for Bezier computation.
n_parallel – number of parallel threads for Bezier computation.
progress – whether to show a progress bar.

Raises:

ValueError – if both graph and the nodes and edges parameters are provided, if no input is provided, or if only one of nodes / edges is provided.
ValueError – if the requested node_graph_metrics / edge_graph_metrics have irreconcilable graph-type requirements for the single internal graph: a directedness standoff (one metric needs a directed graph, another an undirected one, caught across the node/edge boundary since they share one graph), or an explicit graph_directed / graph_multigraph value that conflicts with a requested metric. Raised up front, before any metric runs. Resolve a standoff by building two matrices, one per graph_directed.
InvalidGraphMetricBackendError – if graph metrics are requested and graph_metric_backend (or a per-metric "backend" entry in node_graph_metric_kwargs / edge_graph_metric_kwargs) is not an installed networkx dispatchable backend, targets degree / in_degree / out_degree, or is requested on networkx<3.2. Raised up front, before any metric runs; see hiveplotlib.graph_features.compute_graph_metrics().

Returns:

HivePlotMatrix instance.

classmethod HivePlotMatrix.from_tags(nodes: NodeCollection, edges: Edges | ndarray, *, partition_variable: Hashable, sorting_variables: Hashable | Dict[Hashable, Hashable], tags: List[Hashable] | None = None, repeat_axes: bool | Hashable | List[Hashable] = False, ncols: int | None = None, backend: Literal['matplotlib', 'datashader'] = 'matplotlib', hive_plot_kwargs: Dict | None = None, unify_axes: bool | Dict[Literal['vmin', 'vmax'], float] = False, axis_kwargs: dict | None = None, node_kwargs: dict | None = None, per_tag_plot_kwargs: Dict[Hashable, dict] | None = None, all_edge_kwargs: dict | None = None, repeat_edge_kwargs: dict | None = None, non_repeat_edge_kwargs: dict | None = None, clockwise_edge_kwargs: dict | None = None, counterclockwise_edge_kwargs: dict | None = None, num_steps_per_edge: int = 100, node_graph_metrics: str | Sequence[str] | None = None, edge_graph_metrics: str | Sequence[str] | None = None, node_graph_metric_kwargs: dict[str, dict] | None = None, edge_graph_metric_kwargs: dict[str, dict] | None = None, node_graph_metric_rename: dict[str, str] | None = None, edge_graph_metric_rename: dict[str, str] | None = None, graph_metric_backend: str | None = None, graph_directed: bool = True, graph_multigraph: bool = False, graph_source_attribute_name: str = '_hiveplotlib_source', warn_on_parallel_edge_collapse: bool = True, use_numba: bool = True, n_parallel: int | None = None) → HivePlotMatrix#

Build a matrix comparing different edge tags side by side.

Each cell shows the same nodes and axis layout rendered with a different edge tag. Node positions are identical across all cells, only the visible edges change.

This method is the right choice when your tags represent different relationship types on the same network (e.g., "official", "social", "informal" edges among the same set of people).

Note

Unlike hiveplotlib.HivePlotMatrix.from_partition() and hiveplotlib.HivePlotMatrix.from_variable_sweep(), this classmethod does not accept a networkx graph directly. Tags are a property of the hiveplotlib.Edges object, not of the input graph: a user calling from_tags has already classified their edges into named groups (the keys on edges._data) before construction.

Users with a networkx graph need to assemble multi-tag Edges from a graph manually, converting via hiveplotlib.converters.networkx_to_nodes_edges() and split the resulting single-tag Edges into the desired tag buckets, then pass Edges(data={tag: df, ...}) to from_tags.

The graph_directed, graph_multigraph, and graph_source_attribute_name values you pass here are stashed on the resulting HivePlotMatrix and serve as the per-call defaults for any later hiveplotlib.HivePlotMatrix.compute_graph_metrics() call, so a follow-up metric computation will use the same internal-graph type by default.

Note

If you request graph metrics here (via node_graph_metrics / edge_graph_metrics) or later via hiveplotlib.HivePlotMatrix.compute_graph_metrics(), an internal networkx graph is rebuilt from the stored nodes / edges to compute them. The conversion is typically cheap relative to the metrics themselves; if you want to skip it entirely, attach the metrics as node / edge attributes on your data before construction (e.g. nx.set_node_attributes(graph, nx.betweenness_centrality(graph), "betweenness"), then convert via hiveplotlib.converters.networkx_to_nodes_edges()). The converter carries those attributes through as columns on the resulting hiveplotlib.NodeCollection / hiveplotlib.Edges.

Note

Warning

When NOT to use from_tags: if your tags correspond to fundamentally different network snapshots (such as different time periods where the set of active nodes changes, or where per-tag node attributes differ meaningfully), then from_tags is the wrong tool. All cells will show the full NodeCollection regardless of which nodes actually appear in each tag’s edges, and node positions will be based on the pooled data, not per-tag data.

For per-snapshot comparisons (e.g., year-by-year network evolution), build a separate HivePlot per snapshot and pass the resulting list to the generic HivePlotMatrix constructor.

Parameters:

nodes – node data. Shared across all cells.
edges – edge data corresponding to provided nodes. If providing a numpy.ndarray of edge data, must be provided as (from, to) pairs. Note, providing an array input does not support the inclusion of edge metadata, whereas the Edges instance input does.
partition_variable – which column in node data to partition on.
sorting_variables – which column(s) to sort nodes on each axis. Providing a single value uses the same variable for each axis. Alternatively, providing a dictionary of keys as the unique values from partition_variable column data and values being the corresponding sorting variable to use for that axis. Note when providing a dictionary input, _all_ keys for each axis created by the provided partition_variable must be specified (otherwise a MissingSortingVariableError will be raised).
tags – which edge tags to compare. Default None uses all tags from the edges.
repeat_axes – which partition groups to create repeat axes for. True creates repeat axes for all groups, False disables repeat axes.
ncols – when provided, wraps the 1D row into rows of ncols width.
backend – visualization backend.
hive_plot_kwargs – additional keyword arguments passed to each HivePlot constructor.
unify_axes –
whether to unify axis value ranges across all cells. When True, auto-computes a single global vmin/vmax across all sorting variables and applies them uniformly to every axis. Since different axes correspond to different partition groups, they may naturally have different data ranges; True collapses these into one shared range. When a dict (e.g. {"vmin": 0, "vmax": 10}), uses explicit values and auto-computes any missing ones. When False (default), each axis auto-scales to its own data range.

Priority of params: axis_kwargs > explicit dict values > auto-computed values.
axis_kwargs – keyword arguments applied uniformly to every axis in every hive plot cell (e.g. {"vmin": 0, "vmax": 1e9} to fix the display range across all axes). Because all hive plot cells share the same partition_variable, the same kwargs are applied to every axis in every cell. Takes precedence over any "axis_kwargs" key inside hive_plot_kwargs.
node_kwargs – keyword arguments forwarded to the node rendering call for every hive plot cell. For the matplotlib backend these are scatter() kwargs; for the datashader backend these are imshow() kwargs applied to the node rasterization. Can be overridden at plot time by passing node_kwargs directly to plot().
per_tag_plot_kwargs – per-tag keyword arguments forwarded to each hive plot cell’s plot call (e.g. {"Older": {"cmap_edges": "Blues"}, "Newer": {"cmap_edges": "Oranges"}}). Stored on the instance; can be overridden at plot time via per_tag_kwargs on plot(). Works for both the matplotlib and datashader backends; any plot-time kwarg accepted by the hive plot cell renderer can be supplied. The primary datashader use case is per-tag cmap_edges.
all_edge_kwargs – keyword arguments for all edges. Disregarded when using the "datashader" backend.
repeat_edge_kwargs – keyword arguments for repeat edges. Disregarded when using the "datashader" backend.
non_repeat_edge_kwargs – keyword arguments for non-repeat edges. Disregarded when using the "datashader" backend.
clockwise_edge_kwargs – keyword arguments for edges going clockwise. Disregarded when using the "datashader" backend.
counterclockwise_edge_kwargs – keyword arguments for edges going counterclockwise. Disregarded when using the "datashader" backend.
num_steps_per_edge – number of Bezier curve steps per edge.
node_graph_metrics – optional node graph-metric string name (or sequence of names) to compute and attach as columns to nodes before any sub-plot is constructed. Each name must be a key in hiveplotlib.graph_features.GRAPH_NODE_METRICS. Computed once on the underlying nodes / edges (across all tags; see graph_directed / graph_multigraph) and the augmented columns are then available as partition_variable / sorting_variables. Default None skips computing any metrics.
edge_graph_metrics – optional edge graph-metric string name (or sequence of names) to compute and attach as columns to edges. Each name must be a key in hiveplotlib.graph_features.GRAPH_EDGE_METRICS. Default None skips computing any metrics.
node_graph_metric_kwargs – per-metric **kwargs to forward to each node-metric wrapper, keyed by metric name (e.g. {"betweenness_centrality": {"normalized": False}}).
edge_graph_metric_kwargs – per-metric **kwargs to forward to each edge-metric wrapper, keyed by metric name (e.g. {"edge_betweenness_centrality": {"normalized": False}}).
node_graph_metric_rename – per-metric override mapping from metric name to the column name used on the resulting hiveplotlib.NodeCollection. Useful for resolving collisions when a metric name already exists as a column.
edge_graph_metric_rename – same as node_graph_metric_rename but for edge metrics.
graph_metric_backend – name of a networkx dispatchable backend on which to compute any requested graph metrics. Default None computes everything on default networkx. The value is stored on the resulting HivePlotMatrix and serves as the default for later hiveplotlib.HivePlotMatrix.compute_graph_metrics() calls (see that method for the full precedence chain). degree, in_degree, and out_degree are direct structural reads of the graph, so backend dispatch does not apply to them (the result is identical either way). See the parameter of the same name on HivePlotMatrix and hiveplotlib.graph_features.compute_graph_metrics() for backend-name validation and fallback behavior.
graph_directed – this constructor fixes directedness to whatever you pass and never infers it from the requested metrics; use from_partition() or from_variable_sweep() if you want directedness inferred from the metric set. It sets the directionality of the internal networkx graph used for metric computation; it does not affect how any hive plot cell is rendered. Directedness defaults to True, matching the (from, to) semantics of hiveplotlib.Edges, so an undirected-only metric like triangles needs an explicit graph_directed=False here. A requested set with both a directed-required and an undirected-required metric, or an explicit graph_directed that conflicts with a requested metric, raises a ValueError.
graph_multigraph – unlike graph_directed, this is never inferred from the requested metrics. It controls whether each row in your hiveplotlib.Edges counts as a distinct edge when metrics are computed (across all tags for multi-tag inputs); it does not affect how any hive plot cell is rendered. Defaults to False, collapsing repeated (from, to) rows into a single edge in the internal graph; set True to keep them distinct. Passing True with a metric that rejects multigraphs raises a ValueError. See the note on parallel-edge collapse above.
graph_source_attribute_name – edge-attribute name used internally to map each metric value computed on a repeated edge back to its specific source row when graph_multigraph=True. Defaults to "_hiveplotlib_source", which works for nearly all use cases; override only if it collides with an existing edge column.
warn_on_parallel_edge_collapse – whether to detect and warn about same-direction duplicate (from, to) edges collapsing during metric computation. Default True. Setting False skips the detection entirely (a performance escape hatch for large graphs); it does not change whether edges collapse (duplicates are still merged last-write-wins). To preserve parallel edges instead, use graph_multigraph=True.
use_numba – whether to use numba for Bezier computation.
n_parallel – number of parallel threads for Bezier computation.

Raises:

ValueError – if the requested node_graph_metrics / edge_graph_metrics have irreconcilable graph-type requirements for the single internal graph: a directedness standoff (one metric needs a directed graph, another an undirected one, caught across the node/edge boundary since they share one graph), or a graph_directed / graph_multigraph value that conflicts with a requested metric. Raised up front, before any metric runs. Resolve a standoff by building two matrices, one per graph_directed value.
InvalidGraphMetricBackendError – if graph metrics are requested and graph_metric_backend (or a per-metric "backend" entry in node_graph_metric_kwargs / edge_graph_metric_kwargs) is not an installed networkx dispatchable backend, targets degree / in_degree / out_degree, or is requested on networkx<3.2. Raised up front, before any metric runs; see hiveplotlib.graph_features.compute_graph_metrics().

Returns:

HivePlotMatrix instance.

Generic Constructor#

The generic constructor accepts a list-of-lists or dictionary of HivePlot instances. For common patterns, use the convenience methods above.

class hiveplotlib.HivePlotMatrix(hive_plots: List[List[HivePlot | None]] | Dict[Tuple[int, int], HivePlot], row_labels: List[Hashable] | None = None, col_labels: List[Hashable] | None = None, backend: Literal['matplotlib', 'datashader'] | None = None, unify_axes: bool | Dict[str, float] = False, axis_kwargs: dict | None = None, node_kwargs: dict | None = None, all_edge_kwargs: dict | None = None, repeat_edge_kwargs: dict | None = None, non_repeat_edge_kwargs: dict | None = None, clockwise_edge_kwargs: dict | None = None, counterclockwise_edge_kwargs: dict | None = None, node_graph_metrics: str | Sequence[str] | None = None, edge_graph_metrics: str | Sequence[str] | None = None, node_graph_metric_kwargs: dict[str, dict] | None = None, edge_graph_metric_kwargs: dict[str, dict] | None = None, node_graph_metric_rename: dict[str, str] | None = None, edge_graph_metric_rename: dict[str, str] | None = None, graph_metric_backend: str | None = None, graph_directed: bool = True, graph_multigraph: bool = False, graph_source_attribute_name: str = '_hiveplotlib_source', warn_on_parallel_edge_collapse: bool = True)#

Matrix of HivePlot instances for comparative network visualization.

A HivePlotMatrix stores a 2D grid of HivePlot instances (or None for empty cells), along with optional row and column labels. This class provides both a generic constructor and convenience methods for common use cases.

The generic constructor accepts a list-of-lists or dictionary of HivePlot instances. For common patterns, use the convenience methods:

from_partition(): pairwise group matrix for networks with >3 groups.
from_variable_sweep(): compare different sorting and/or partition variables.
from_tags(): compare different edge tags side by side.

Parameters:

hive_plots – 2D grid of HivePlot instances. Can be provided as a list of lists (where inner lists are rows and None represents empty cells) or as a dictionary mapping (row, col) tuples to HivePlot instances.
row_labels – labels for each row. Length must match the number of rows.
col_labels – labels for each column. Length must match the number of columns.
backend – visualization backend to use. When provided, sets the backend on all populated cells. When None (default), the backend is inferred from the first populated hive plot cell.
unify_axes –
whether to unify axis value ranges across all cells. When True, auto-computes global vmin/vmax from all axes in all hive plots and applies them uniformly. When a dict (e.g. {"vmin": 0, "vmax": 10} or {"vmin": 0}), uses explicit values and auto-computes any missing ones. When False (default), axes keep their per-cell ranges. Triggers a rebuild of already-built HivePlot instances.

Priority of params: axis_kwargs > explicit dict values > auto-computed values.
axis_kwargs – keyword arguments applied uniformly to every axis in every populated hive plot cell (e.g. {"vmin": 0, "vmax": 1e9} to fix the display range across all axes). Applied post-construction via update_axis(), so it overwrites any per-axis settings already present on the supplied HivePlot instances.
node_kwargs – keyword arguments forwarded to the node rendering call for every hive plot cell. For the matplotlib backend these are scatter() kwargs; for the datashader backend these are imshow() kwargs applied to the node rasterization. Can be overridden at plot time by passing node_kwargs directly to plot().
all_edge_kwargs – keyword arguments for all edges. Disregarded when using the "datashader" backend.
repeat_edge_kwargs – keyword arguments for repeat edges. Disregarded when using the "datashader" backend.
non_repeat_edge_kwargs – keyword arguments for non-repeat edges. Disregarded when using the "datashader" backend.
clockwise_edge_kwargs – keyword arguments for edges going clockwise. Disregarded when using the "datashader" backend.
counterclockwise_edge_kwargs – keyword arguments for edges going counterclockwise. Disregarded when using the "datashader" backend.
node_graph_metrics –
optional node graph-metric string name (or sequence of names) to compute and attach as columns to the underlying hiveplotlib.NodeCollection of every populated cell at construction time.

Note

On the generic HivePlotMatrix constructor, metrics are computed and attached after sub-plot construction (every cell’s HivePlot instance must already exist), so the resulting metric columns cannot drive partition_variable / sorting_variables inside each sub-plot. If you want to compute HPM partition or sorting variables on the fly, reach for one of the from_partition() / from_variable_sweep() / from_tags() classmethods instead. Those compute metrics before sub-plot construction.

Each name must be a key in hiveplotlib.graph_features.GRAPH_NODE_METRICS. Metrics are computed once per distinct underlying hiveplotlib.NodeCollection / hiveplotlib.Edges pair across the matrix (deduplicated by identity), so global metrics like betweenness_centrality produce a consistent value across all cells that share the same source data. Default None skips computing any metrics.
edge_graph_metrics –
optional edge graph-metric string name (or sequence of names) to compute and attach as columns to the underlying hiveplotlib.Edges of every populated cell at construction time.

Note

Same timing caveat as node_graph_metrics note above: edge metrics are attached after sub-plot construction on this generic constructor and so cannot drive sub-plot partition / sorting variables. Reach for one of the from_* classmethods if you need metric-derived columns on the fly to feed into sub-plot construction.

Each name must be a key in hiveplotlib.graph_features.GRAPH_EDGE_METRICS. Default None skips computing any metrics.
node_graph_metric_kwargs – per-metric **kwargs to forward to each node-metric wrapper, keyed by metric name (e.g. {"betweenness_centrality": {"normalized": False}}).
edge_graph_metric_kwargs – per-metric **kwargs to forward to each edge-metric wrapper, keyed by metric name (e.g. {"edge_betweenness_centrality": {"normalized": False}}).
node_graph_metric_rename – per-metric override mapping from metric name to the column name used on the resulting hiveplotlib.NodeCollection. Useful for resolving collisions when a metric name already exists as a column.
edge_graph_metric_rename – same as node_graph_metric_rename but for edge metrics.
graph_metric_backend – name of a networkx dispatchable backend (e.g. "parallel", registered by the nx-parallel package) on which to compute any requested graph metrics. Default None computes everything on default networkx. The value is stored on the resulting HivePlotMatrix and serves as the default for later hiveplotlib.HivePlotMatrix.compute_graph_metrics() calls (see that method for the full precedence chain). degree, in_degree, and out_degree are direct structural reads of the graph, so backend dispatch does not apply to them (the result is identical either way). See hiveplotlib.graph_features.compute_graph_metrics() for backend-name validation and the fallback behavior for metrics a backend does not implement.
graph_directed – this constructor fixes directedness to whatever you pass and never infers it from the requested metrics; use from_partition() or from_variable_sweep() if you want directedness inferred from the metric set. It sets the directionality of the internal networkx graph built when computing graph metrics; it does not affect how any hive plot cell is rendered. Directedness defaults to True, matching the (from, to) semantics of hiveplotlib.Edges, so an undirected-only metric like triangles needs an explicit graph_directed=False here. A requested set with both a directed-required and an undirected-required metric, or an explicit graph_directed that conflicts with a requested metric, raises a ValueError.
graph_multigraph – unlike graph_directed, this is never inferred from the requested metrics. It controls whether each row in the hiveplotlib.Edges class counts as a distinct edge when metrics are computed (across all tags for multi-tag inputs); it does not affect how any hive plot cell is rendered. Defaults to False, collapsing repeated (from, to) rows into a single edge in the internal graph; set True to keep them distinct. Passing True with a metric that rejects multigraphs raises a ValueError. See the note on parallel-edge collapse below.
graph_source_attribute_name – edge-attribute name used internally to map each metric value computed on a repeated edge back to its specific source row when graph_multigraph=True. Default "_hiveplotlib_source" works for nearly all use cases; override only if it collides with an existing edge column.
warn_on_parallel_edge_collapse – whether to detect and warn about same-direction duplicate (from, to) edges collapsing during metric computation. Default True. Setting False skips the detection entirely (a performance escape hatch for large graphs); it does not change whether edges collapse (duplicates are still merged last-write-wins). To preserve parallel edges instead, use graph_multigraph=True.

Note

Controlling the internal graph type. graph_directed, graph_multigraph, and graph_source_attribute_name together pin the default type of the internal networkx graph used to generate any requested graph metrics (directed vs. undirected, simple vs. multi, and how repeated edges map back to source rows). The one rule to keep in mind: directedness is inferred from the requested metrics only on from_partition() and from_variable_sweep() when you leave graph_directed unset, while __init__ and from_tags() keep whatever directedness you pass and never infer it. A graph built from a graph input keeps its own type, and graph_multigraph is never inferred on any path. The Computing Graph Metrics notebook walks through these cases, including the exact ways a graph-type mismatch stops computation.

Note

Properties#

property HivePlotMatrix.shape: Tuple[int, int]#

Return the shape (nrows, ncols) of the matrix.

Returns:: tuple of (number of rows, number of columns).

property HivePlotMatrix.row_labels: List[Hashable] | None#

Return the row labels.

Returns:: list of row labels, or None if not set.

property HivePlotMatrix.col_labels: List[Hashable] | None#

Return the column labels.

Returns:: list of column labels, or None if not set.

property HivePlotMatrix.cell_labels: Dict[Tuple[int, int], Hashable] | None#

Return per-cell labels for wrapped layouts.

When ncols wrapping is used, cell labels map (row, col) to the label for that cell. Returns None for non-wrapped layouts.

Returns:: dictionary mapping (row, col) to label, or None.

property HivePlotMatrix.matrix_type: Literal['generic', 'from_partition', 'from_variable_sweep', 'from_tags']#

Return the matrix type.

Returns:: one of "generic", "from_partition", "from_variable_sweep", or "from_tags".

property HivePlotMatrix.backend: Literal['matplotlib', 'datashader']#

Return the visualization backend currently set on this matrix.

Read-only; use set_viz_backend() to change the backend.

Returns:: backend string (one of the values in hiveplotlib.hiveplot_matrix.HPM_SUPPORTED_VIZ_BACKENDS).

Cell Access & Iteration#

HivePlotMatrix.__getitem__(key: Tuple[int, int]) → HivePlot | None#

Get a HivePlot at position (row, col).

Parameters:: key – (row, col) tuple.
Returns:: HivePlot instance or None.

HivePlotMatrix.__setitem__(key: Tuple[int, int], value: HivePlot | None) → None#

Set a HivePlot at position (row, col).

Parameters:

key – (row, col) tuple.
value – HivePlot instance or None.

Returns:

None.

HivePlotMatrix.iter_populated_cells() → Iterator[Tuple[int, int, HivePlot]]#

Iterate over populated (non-None) cells.

Returns:: iterator yielding (row, col, HivePlot) tuples.

Bulk Modification#

HivePlotMatrix.set_viz_backend(backend: Literal['matplotlib', 'datashader']) → None#

Set the visualization backend for the matrix and all populated cells.

Parameters:: backend – which viz backend to use for plotting.
Raises:: InvalidVizBackendError – if backend is not a supported backend.
Returns:: None.

HivePlotMatrix.update_all_edge_plotting_keyword_arguments(edge_kwarg_setting: Literal['all_edge_kwargs', 'repeat_edge_kwargs', 'non_repeat_edge_kwargs', 'clockwise_edge_kwargs', 'counterclockwise_edge_kwargs'] = 'all_edge_kwargs', reset_edge_kwarg_setting: bool = False, rebuild_edges: bool = False, **kwargs: object) → None#

Update edge plotting keyword arguments for all populated cells.

Parameters:

edge_kwarg_setting – which edge kwarg setting to modify.
reset_edge_kwarg_setting – whether to overwrite existing keyword arguments for the chosen edge_kwarg_setting.
rebuild_edges – whether to only update edge kwargs or to also redraw the edges. Default False only updates edge kwargs.
kwargs – additional keyword arguments to provide to the specified edge kwarg setting.

Returns:

None.

HivePlotMatrix.compute_graph_metrics(*, node_graph_metrics: str | Sequence[str] | None = None, edge_graph_metrics: str | Sequence[str] | None = None, node_graph_metric_kwargs: dict[str, dict] | None = None, edge_graph_metric_kwargs: dict[str, dict] | None = None, node_graph_metric_rename: dict[str, str] | None = None, edge_graph_metric_rename: dict[str, str] | None = None, graph_metric_backend: str | None = None, graph_directed: bool | None = None, graph_multigraph: bool | None = None, graph_source_attribute_name: str | None = None, warn_on_parallel_edge_collapse: bool | None = None) → None#

Compute graph metrics in place on every populated cell of this HivePlotMatrix.

For each populated cell, builds an internal networkx graph from its underlying hiveplotlib.NodeCollection / hiveplotlib.Edges, runs the requested metrics, and replaces that cell’s nodes / edges with augmented copies containing the resulting metric columns.

Cells that share the same underlying nodes and edges pair (by identity) have metrics computed exactly once and the result is propagated to every cell in the group, so global metrics like betweenness_centrality stay consistent across cells sharing the same source data.

Note

graph_directed and graph_multigraph control the internal graph used for metric computation only; they do not change how any hive plot cell is rendered. They do, however, affect which metrics are valid (e.g. in_degree requires graph_directed=True).

Note

Parameters:

node_graph_metrics – string key (or sequence of keys) from hiveplotlib.graph_features.GRAPH_NODE_METRICS to compute.
edge_graph_metrics – string key (or sequence of keys) from hiveplotlib.graph_features.GRAPH_EDGE_METRICS to compute.
node_graph_metric_kwargs – per-metric **kwargs to forward to each wrapper, keyed by node metric name (e.g. {"betweenness_centrality": {"normalized": False}}).
edge_graph_metric_kwargs – same as node_graph_metric_kwargs but for edge metrics (e.g. {"edge_betweenness_centrality": {"normalized": False}}).
node_graph_metric_rename – per-node metric column-name override (resolves collisions with existing node columns).
edge_graph_metric_rename – same as node_graph_metric_rename but for edge metrics.
graph_metric_backend – name of a networkx dispatchable backend on which to compute the requested metrics for this call. An explicit value applies to this call only and does not mutate the value stored at construction time; left None, the stored value is reused (to run just this one call on default networkx under a stored construction backend, pass graph_metric_backend="networkx"). Precedence when several levels are set: a per-metric "backend" entry in node_graph_metric_kwargs / edge_graph_metric_kwargs beats this per-call graph_metric_backend, which beats the value stored at construction time. See the parameter of the same name on HivePlotMatrix and hiveplotlib.graph_features.compute_graph_metrics() for backend-name validation and fallback behavior.
graph_directed – directionality of the internal graph used for metric computation. An explicit value on this call applies to this call only, always wins, and does not mutate the stored setting; if it conflicts with a requested metric’s requirement, a ValueError explains the clash. Left None, behavior follows how the HivePlotMatrix was constructed. If directedness was pinned at construction (via __init__ or from_tags(), which take a concrete graph_directed default and always pin it; via from_partition() / from_variable_sweep() with an explicit graph_directed; or any matrix built from a graph): the stored value is reused and not re-inferred, so a metric needing the opposite directedness raises the conflict ValueError. If left unpinned (built via from_partition() / from_variable_sweep() from nodes / edges without graph_directed): directedness stays unpinned and is inferred from the requested set on every call when unambiguous (so node_graph_metrics="triangles" builds an undirected graph), falling back to True when the request does not decide it; a contradictory set (one metric needs a directed graph, another an undirected one) cannot be inferred and raises the conflict ValueError.
graph_multigraph – unlike graph_directed, this is never inferred from the requested metrics. It controls whether each row in the hiveplotlib.Edges class counts as a distinct edge when metrics are computed (across all tags for multi-tag inputs). An explicit value on this call applies to this call only, wins, and does not mutate the stored setting; passing True with a metric that rejects multigraphs raises a ValueError. Left None, uses the value stored at construction time (False when built from nodes / edges, graph.is_multigraph() when built from a graph). See the note on parallel-edge collapse above.
graph_source_attribute_name – edge-attribute name used internally to map each metric value computed on a repeated edge back to its specific source row when graph_multigraph=True. Defaults to the value stored on this HivePlotMatrix at construction time (__init__ defaults to "_hiveplotlib_source", which works for nearly all use cases; override only if it collides with an existing edge column). Explicit overrides apply to this call only; they do not mutate the stored attribute.
warn_on_parallel_edge_collapse – whether to detect and warn about same-direction duplicate (from, to) edges collapsing during metric computation. Left None, uses the value stored at construction time (default True); an explicit value applies to this call only and does not mutate the stored setting. Setting False skips the detection entirely (a performance escape hatch for large graphs); it does not change whether edges collapse (duplicates are still merged last-write-wins). To preserve parallel edges instead, use graph_multigraph=True.

Returns:

None. Replaces each populated cell’s nodes / edges in place.

Raises:

ValueError – if the requested metrics have irreconcilable graph-type requirements for the single internal graph: a directedness standoff (one metric needs a directed graph, another an undirected one, caught across the node/edge boundary since they share one graph), or an explicit graph_directed / graph_multigraph value that conflicts with a requested metric. Raised up front, before any metric runs. Resolve a standoff by running two calls, one per graph_directed value.
InvalidGraphMetricBackendError – if the effective graph_metric_backend (or a per-metric "backend" entry) is not an installed networkx dispatchable backend, targets degree / in_degree / out_degree, or is requested on networkx<3.2. Raised up front, before any metric runs; see hiveplotlib.graph_features.compute_graph_metrics().

Plotting#

HivePlotMatrix.plot(**kwargs)#

Plot the hive plot matrix.

Creates a matplotlib subplot grid and renders each populated cell. Plotting behavior varies based on the matrix type:

"from_partition": diagonal cells are zoomed to the repeat-axis quadrant with separate buffer and pixel-spread settings; labels are positioned relative to diagonal vs off-diagonal placement.
"from_variable_sweep" / "from_tags" / "generic": all cells rendered with identical settings (buffer, pixel spread, zoom).

Note

When the backend is set to datashader, any provided node or edge plotting keyword arguments will be disregarded, as attributes like color and size are reserved for datashading. Global vmax values for node and edge density are auto-computed across all cells when not explicitly provided.

Parameters:: kwargs – keyword arguments forwarded to hive_plot_matrix_viz().
Returns:: viz data structures. For the matplotlib backend, (fig, axes). For the datashader backend, (fig, axes, im_nodes_dict, im_edges_dict). See hive_plot_matrix_viz() for details.

Utilities#

HivePlotMatrix.copy() → HivePlotMatrix#

Return a deep copy of the HivePlotMatrix instance.

Returns:: copy of the HivePlotMatrix instance.

Constants#

hiveplotlib.hiveplot_matrix.HPM_SUPPORTED_VIZ_BACKENDS#

The visualization backends supported by HivePlotMatrix.

A narrower set than hiveplotlib.hiveplot.SUPPORTED_VIZ_BACKENDS:

"matplotlib": the default; each cell renders into its own Axes on a shared figure.
"datashader": each cell renders a rasterized aggregation via imshow(), for matrices dense enough to benefit from server-side rasterization.

Set on a matrix via the backend argument to hiveplotlib.HivePlotMatrix (or its from_* constructors), or after construction with hiveplotlib.HivePlotMatrix.set_viz_backend().

alias of Literal[‘matplotlib’, ‘datashader’]

hiveplotlib.hiveplot_matrix.HPM_MATRIX_TYPES#

The matrix types supported by HivePlotMatrix.

"generic": constructed directly via __init__.
"from_partition": built via hiveplotlib.HivePlotMatrix.from_partition().
"from_variable_sweep": built via hiveplotlib.HivePlotMatrix.from_variable_sweep().
"from_tags": built via hiveplotlib.HivePlotMatrix.from_tags().

alias of Literal[‘generic’, ‘from_partition’, ‘from_variable_sweep’, ‘from_tags’]