Migrating to the New HivePlot Class in 0.26#

Migration Figure Image of migrating geese, generated by Grok (xAI) using the prompt “pop art style clipart of migrating geese flying in the sky.”

Hiveplotlib version 0.26.0 introduced a new, revised HivePlot class.

This new HivePlot class builds on top of the original HivePlot class in previous versions of Hiveplotlib, allowing the user to think about their hive plot visualization at a higher level. It also lets users work with new, more interpretable and flexible node and edge data structures (the new NodeCollection and Edges classes).

This new class is intended to replace previous use of both the hive_plot_n_axes() function and the original HivePlot class (now BaseHivePlot).

This post discusses:

  • Migrating to the new HivePlot class from hive_plot_n_axes.

  • Migrating to the new HivePlot class from the old class.

  • Preserving original HivePlot class behavior with the BaseHivePlot class.

  • Deprecation of hive_plot_n_axes().

Migrating to the New HivePlot Class from hive_plot_n_axes#

The new HivePlot class parameters should look comparable to hive_plot_n_axes() other than some renaming of parameters, with a few notable behavioral differences:

Partition Variable#

The axes_assignments parameter used for partitioning in hive_plot_n_axes() has been replaced by the partition_variable parameter in the new HivePlot class. Rather than having to manually generate a list of lists of node IDs, users should now create a partition in a NodeCollection using the NodeCollection.create_partition_variable() method. For more discussion on this, see the documentation on setting partition variables.

Sorting Variables#

In the new HivePlot class, sorting variables are now set either all to the same node variable, or they can be specified for specific axes according to the axis names as defined by the values in the partition_variable column of node data. For more discussion on this, see the documentation on setting sorting variables.

Repeat Axes#

In the new HivePlot class, repeat axes are specified as either specific axis names as determined by the values in the partition_variable column of node data or all on / off with True / False. For more discussion on this, see the documentation on adding and modifying repeat axes.

Migrating to the New HivePlot Class from the Old Class#

The old HivePlot class could previously be instantiated empty and added to, but the new HivePlot class requires the following inputs:

Nodes#

Nodes must now be provided to the nodes parameter in the form of a hiveplotlib.NodeCollection instance, which is essentially a pandas.DataFrame of node data with some helper methods for making partition variables.

Edges#

Edges must now be provided to the edges parameter in the form of an hiveplotlib.Edges instance, which is essentailly a pandas.DataFrame of edge data. Alternatively, users can provide an (n, 2) numpy.ndarray of (from, to) edge data, but this input does not support the inclusion of any edge-specific metadata.

Partition Variable#

A partition_variable must be provided clarifying which column of node data to use to partition the nodes into axes. For more discussion on this, see the documentation on setting partition variables.

Sorting Variables#

In the new HivePlot class, sorting variables are now set either all to the same node variable, or they can be specified for specific axes according to the axis names as defined by the values in the partition_variable column of node data. For more discussion on this, see the documentation on setting sorting variables.

Modifying HivePlot Instance#

After instantiation of a new HivePlot instance, users can access a suite of new, higher-level node, edge, axis, and hive plot-level manipulations. For more information about these methods, see the API documentation for the new HivePlot class.

Users can also still access all of the old HivePlot class methods in the resulting HivePlot instance. For more information about these methods, see the API documentation for the BaseHivePlot class

Preserving Original HivePlot Class Behavior with the BaseHivePlot Class#

The original HivePlot class has been renamed to BaseHivePlot.

BaseHivePlot will be maintained for direct use in hiveplotlib>=0.26.0 with several breaking changes relative to the old HivePlot class:

Placing Nodes on Axes#

hiveplotlib.BaseHivePlot.place_nodes_on_axis() now works off of a dataframe of node data and metadata via the new node_df parameter, not lists or 1d numpy arrays of unique IDs. The old unique_ids parameter will now raise a TypeError, pointing the user to the node_df parameter. This was a necessary change to support hover information for the interactive viz backends.

Storing Hive Plot Edges#

The hive plot edges constructed in hiveplotlib.BaseHivePlot are now stored under the hive_plot_edges attribute instead of the edges attribute, which is now reserved for storing edges with the higher-level hiveplotlib.Edges class.

Deprecation of hive_plot_n_axes()#

hiveplotlib.hive_plot_n_axes is set to be removed in version 0.28.0. As discussed above, its functionality has been incorporated into the revised HivePlot class.