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, edges: Edges | ndarray, 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, 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.

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.
edges – edge data.
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.
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.
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.

Returns:

HivePlotMatrix instance.

classmethod HivePlotMatrix.from_variable_sweep(nodes: NodeCollection, edges: Edges | ndarray, 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, use_numba: bool = True, n_parallel: int | None = None, progress: bool = True) → HivePlotMatrix#

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

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.
edges – edge data.
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.
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.

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, 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).

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.
partition_variable – which column in node data to partition on.
sorting_variables – which column(s) to sort nodes on each axis.
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.
use_numba – whether to use numba for Bezier computation.
n_parallel – number of parallel threads for Bezier computation.

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.

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.

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".

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.

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()#: Return the supported visualization back ends for HivePlotMatrix.

hiveplotlib.hiveplot_matrix.hpm_matrix_types()#: Return the supported matrix types for HivePlotMatrix.