Updating Edges Instance Viz Kwargs

This notebook demonstrates how to change edge viz keyword arguments in a hiveplotlib.Edges instance.

Note: this notebook uses the holoviews-matplotlib viz back end. The topics discussed in this notebook are relevant to multiple back ends, but to run this notebook, Hiveplotlib must be installed with extra packages, which can be done by running:

pip install hiveplotlib[holoviews]

from hiveplotlib import Edges, HivePlot, NodeCollection
from hiveplotlib.datasets import (
    example_edges,
    example_hive_plot,
    example_node_collection,
)

Introduction to Edges Instance Kwargs

The hiveplotlib.Edges instance allows users to add / modify edge kwargs using the Edges.update_edge_viz_kwargs() method.

At a quick glance, this method should seem quite similar to the HivePlot.update_edge_plotting_keyword_arguments() method, which is explored in detail on the HivePlot class-specific Changing Edge Keyword Arguments page.

hp = example_hive_plot(backend="holoviews-matplotlib")

# update kwargs here to propagate to later plot() calls
hp.edges.update_edge_viz_kwargs(color="blue")

# no need for kwargs here; they were set above
hp.plot()

ⓘ

The Edges.update_edge_viz_kwargs() method, however, can help us out in some distinct ways relative to the comparable HivePlot method, which we explore below.

Why Change Kwargs in an Edges Instance?

With all the existing flexibilitiy for changing kwargs in a hiveplotlib.HivePlot instance, when would we want to change keyword arguments specifically in an Edges instance?

The main benefit is that edge kwargs here offer an opportunity to distinguish edges in a way that is independent of the downstream hive plot. Below, we explore two examples of this.

Consistent Kwargs Across Multiple Hive Plots

Suppose we want to color the edges according to a specific edge variable as we create multiple hive plots.

If we are creating multiple HivePlot instances, we need only specify the edge kwargs once for the Edges instance with Edges.update_edge_viz_kwargs().

Below, we contrive an example where switching between two node sorting variables will flip our highlighted edges from the low end to the high end of a pair of axes:

nodes = example_node_collection()

# create `low`-based partition variable
node_partition_low = nodes.create_partition_variable(
    data_column="low",
    labels=["A", "B", "C"],
)

# create additional variable that inverts low values
nodes.data["inverted_low"] = 10 - nodes.data["low"]

edges = example_edges(nodes=nodes)

# create edge variable based on the node `low` values
corresponding_node_df = edges.data.merge(
    nodes.data,
    left_on="from",
    right_on=nodes.unique_id_column,
).merge(
    nodes.data,
    left_on="to",
    right_on=nodes.unique_id_column,
    suffixes=[None, "_to"],
)

low_from_values = corresponding_node_df["low"]
low_to_values = corresponding_node_df["low_to"]
edges.data["average_low_node_values"] = (low_from_values + low_to_values) / 2

# flag edges with a low `average_low_node_values` value
edges.data["small_low"] = "black"
edges.data.loc[
    edges.data["average_low_node_values"].to_numpy() < 4, "small_low"
] = "red"

# use `small_low` as color for future hive plots
#  specified only once here for two hive plots below
edges.update_edge_viz_kwargs(color="small_low")

# no color kwargs on creation
hp_low = HivePlot(
    nodes=nodes,
    edges=edges,
    partition_variable=node_partition_low,
    sorting_variables="low",  # leads to low red edges
    backend="holoviews-matplotlib",
)

# no color kwargs when plotting
fig_low = hp_low.plot(linewidth=2)
fig_low.opts(
    title="The lowest-colored edges\nwith one sorting variable",
    sublabel_format="",
)

# no color kwargs on creation
hp_inverted_low = HivePlot(
    nodes=nodes,
    edges=edges,
    partition_variable=node_partition_low,
    sorting_variables="inverted_low",  # leads to high red edges
    backend="holoviews-matplotlib",
)

# no color kwargs when plotting
fig_inverted_low = hp_inverted_low.plot(linewidth=2)
fig_inverted_low.opts(
    title="Become the highest-colored edges\nwith another sorting variable",
    sublabel_format="",
)

fig_low + fig_inverted_low

ⓘ

Edge Tag Kwargs

Edges.update_edge_viz_kwargs() also allows us to add kwargs to specific tags of edge data. (For more on edge tags, see the Multiple Tags of Edge Data page.)

Below, we tag each set of inter-group edges with respect to a specific partition, giving each tag its own color. When using this partition variable for our hive plot, this will result in lighting up each set of inter-group edges a different color.

If we switch to a completely uncorrelated partition, however, we will get an overlapping mess of color.

# generate all nodes for a standard 3 axis hive plot
nodes = example_node_collection()

# we will make tags of edges based on this partition
low_partition = nodes.create_partition_variable(
    data_column="low",
    labels=["A", "B", "C"],
    partition_variable_name="low_partition",
)

# create a completely unrelated partition for later
med_partition = nodes.create_partition_variable(
    data_column="med",
    labels=["D", "E", "F"],
    partition_variable_name="med_partition",
)

# build out multi tag edge data based on `low` partition
edge_data = {}

# get subsets of edges each restricted to one pair of axes
for axis_to_skip in ["A", "B", "C"]:
    subset_df = nodes.data[nodes.data[low_partition] != axis_to_skip]

    subset_nodes = NodeCollection(
        data=subset_df,
        unique_id_column=nodes.unique_id_column,
    )

    subset_edges = example_edges(
        nodes=subset_nodes,
    )
    edge_data[f"Not {axis_to_skip}"] = subset_edges.data

edges = Edges(data=edge_data)

# color each tag of edges
edge_kwargs = {
    "Not A": {"color": "red"},
    "Not B": {"color": "blue"},
    "Not C": {"color": "gold"},
}

for k in edge_kwargs:
    # propagate specific kwargs to specific tags of edges
    edges.update_edge_viz_kwargs(tag=k, **edge_kwargs[k])

# no color kwargs on creation
hp = HivePlot(
    nodes=nodes,
    edges=edges,
    partition_variable=low_partition,  # partition matches tags
    sorting_variables="low",
    backend="holoviews-matplotlib",
)

# no color kwargs when plotting
fig_low = hp.plot()

fig_low.opts(
    title="Edges tagged by low-partition\nin low-partitioned Hive Plot",
    sublabel_format="",
)

# change partition to the one unrelated to our tags
hp.set_partition(
    partition_variable=med_partition,
    sorting_variables="med",
)

# still no color kwargs when plotting
fig_med = hp.plot()

fig_med.opts(
    title="Same tags\nbut now med-partitioned",
    sublabel_format="",
)

fig_low + fig_med

ⓘ

Edge Instance Kwargs Overwritten by HivePlot Kwargs

Edge keyword arguments from running Edges.update_edge_viz_kwargs() will be deprioritized in favor of keyword arguments provided to any of the edge kwargs stored in the HivePlot.edge_plotting_keyword_arguments attribute or additional kwargs provided when calling HivePlot.plot().

If the edge kwargs provided to Edges are distinct from the HivePlot edge kwargs, however, then we will see both sets of edge kwargs in the final visualization:

# recreate our low-partitioned example from above
hp = HivePlot(
    nodes=nodes,
    edges=edges,
    partition_variable=low_partition,  # partition matches tags
    sorting_variables="low",
    backend="holoviews-matplotlib",
)

# only plotting the kwargs stored in `Edges`
fig_with_edge_kwargs = hp.plot()
fig_with_edge_kwargs.opts(
    title="Original figure\nshows Edges kwargs",
    sublabel_format="",
    fontsize={"title": 16},
)

# `plot()` edge kwargs overwrite `Edges` kwargs
fig_overwrite_edge_kwargs = hp.plot(color="blue")
fig_overwrite_edge_kwargs.opts(
    title="HivePlot kwargs\noverwrite Edges kwargs",
    sublabel_format="",
    fontsize={"title": 16},
)

# non-overlapping kwargs both show up
fig_non_overlapping_edge_kwargs = hp.plot(linestyle="--")
fig_non_overlapping_edge_kwargs.opts(
    title="Non-overlapping kwargs\nshows both",
    sublabel_format="",
    fontsize={"title": 16},
)

(
    fig_with_edge_kwargs
    + fig_overwrite_edge_kwargs
    + fig_non_overlapping_edge_kwargs
)

ⓘ