Plotly

This notebook discusses how to use the HivePlot class with the plotly visualization back end.

Note: the plotly viz back end requires that Hiveplotlib be installed with extra packages, which can be done by running:

pip install hiveplotlib[plotly]

import matplotlib as mpl
import plotly.graph_objects as go
import plotly.io
from hiveplotlib.datasets import example_hive_plot

plotly.io.renderers.default = "plotly_mimetype+notebook"

Change Plotting Kwargs For Nodes, Edges, and Axes

By default, Hiveplotlib viz keeps all colors black, with standardized sizes that should cover most users’ needs:

hp = example_hive_plot(backend="plotly")

fig = hp.plot()
fig.update_layout(
    title="Base Plotly Hive Plot Viz",
)
fig

All of these defaults, however, can be modified. Below, we modify every color and size to serve as a reference for how to change these defaults with the plotly back end:

fig = hp.plot(
    # node kwarg changes
    node_kwargs={
        "size": 15,
        "color": "rgba(255,255,255,0)",  # empty node fill color
        "line_color": "blue",
        "line_width": 2,  # not called "width", see "Line Width" below
        "opacity": 0.4,  # plotly back end specific
    },
    # axes label kwarg changes
    axes_labels_fontsize=32,
    label_kwargs={
        "color": "purple",
        "weight": "bold",
        "style": "italic",
    },
    # axes kwarg changes
    axes_kwargs={
        "line_width": 10,  # not called "width", see "Line Width" below
        "color": "yellow",
        "opacity": 0.9,  # plotly back end specific
    },
    axes_labels_buffer=1.3,  # move axes labels out a bit
    # edge kwarg changes
    color="red",
    line_width=3,
    opacity=0.1,  # plotly back end specific
)
fig

Line and Node Opacity

The underlying plotly dependency handles transparency differently for lines (i.e. edges, axes in a hive plot) than for scatter points (i.e. nodes in a hive plot).

Although plotting nodes naturally supports an opacity parameter (comparable to an alpha parameter in other viz back ends), this is not the case for off-the-shelf plotly viz of lines. Making lines transparent normally in plotly requires providing an RGBA string for color, i.e.

"rgba(<red val>, <green val>, <blue val>, <alpha val>)"

To make the user experience more consistent when making edges and / or axes more transparent, Hiveplotlib includes formal support for an opacity parameter in the edge and axes viz calls.

Note, users are still welcome to provide "rgba(<red>, <green>, <blue>, <alpha>)" strings for the color parameters. If so, the provided <alpha> value will take priority over any values provided to the opacity parameter.

fig = hp.plot(
    # node kwarg changes
    node_kwargs={
        "size": 15,
        "color": "rgba(255,255,255,0)",  # opacity embedded here
        "line_color": "rgba(0, 0, 255, 0.4)",  # opacity embedded here
        "line_width": 2,
    },
    # axes label kwarg changes
    axes_labels_fontsize=32,
    label_kwargs={
        "color": "purple",
        "weight": "bold",
        "style": "italic",
    },
    # axes kwarg changes
    axes_kwargs={
        "line_width": 10,
        "color": "rgba(255, 255, 0, 0.9)",  # opacity embedded here
    },
    axes_labels_buffer=1.3,
    # edge kwarg changes
    color="rgba(255, 0, 0, 0.1)",  # opacity embedded here
    line_width=3,
)
fig

Line Width

The line_width parameter for edge and axes visualization corresponds to the standard width parameter for plotly lines.

Hiveplotlib exposes this parameter with a different name because width is already the standard name for figure width for the other Hiveplotlib visualization back ends.

Plotting Node Metadata

Users may want to visualize nodes with respect to node metadata. For more on visualizing node metadata, see the Visualizing Node Metadata page.

Below, we demonstrate modifying nodes according to metadata for both size and color.

hp = example_hive_plot(
    repeat_axes=True,
    backend="plotly",
)

# scale the low variable to make more useful sizes in viz
hp.nodes.data["size"] = hp.nodes.data["low"].to_numpy() + 5

# propagate extra node data changes through to data on axes
hp.update_partition_data()

node_kwargs = {
    "line_color": "black",
    "color": "low",  # reference to "low" var in node data
    "size": "size",  # reference to "size" var in node data
    "colorscale": "Magma",
    "cmin": 0,  # fixed color range consistent between each axis
    "cmax": 10,  # fixed color range consistent between each axis
    "showscale": True,
    "colorbar": {
        "title": "Node Variable:<br>'low'",
    },
}

hp.update_node_viz_kwargs(**node_kwargs)

# when including color bar, make wider to maintain 1:1 aspect
fig = hp.plot(
    layout_kwargs={"width": 650, "height": 600},
)

fig

Plotting Edge Metadata

Users may want to visualize edges with respect to edge metadata. For more on visualizing edge metadata, see the Visualizing Edge Metadata page.

Below, we demonstrate modifying edges according to metadata for both line width and color.

Note that when coloring edges by data values with the plotly back end, we have to pre-compute the color of each line based on its corresponding data value. We are using matplotlib color tools for these color calculations below.

hp = example_hive_plot(
    repeat_axes=True,
    backend="plotly",
)

# need to pre-compute our line colors to work with plotly backend
cmap = mpl.colormaps.get_cmap("cividis")
# fixed color range consistent for all edges
norm = mpl.colors.Normalize(vmin=0, vmax=10)
color_list = [
    mpl.colors.rgb2hex(cmap(norm(val))) for val in hp.edges.data["low"]
]

hp.edges.data["width"] = hp.edges.data["low"] / 3
hp.edges.data["color"] = (
    color_list  # have to manually calculate the color strings first
)

# propagate extra edge data changes through to data on axes
hp.update_partition_data()

edge_kwargs = {
    "color": "color",  # based on "low" var in edge data, but color strings must be created above
    "line_width": "width",  # reference to "width" variable in edge data
}

hp.update_edge_plotting_keyword_arguments(**edge_kwargs)

# when including color bar, make wider to maintain 1:1 aspect
fig = hp.plot(
    layout_kwargs={"width": 650, "height": 600},
)

# manually add colorbar
colorbar_trace = go.Scatter(
    x=[None],
    y=[None],
    mode="markers",
    marker={
        "colorscale": "cividis",
        "showscale": True,
        "cmin": 0,
        "cmax": 10,
        "colorbar": {"title": "Edge Variable:<br>'low'"},
    },
)
fig.add_trace(colorbar_trace)

fig

Hover Information

We encourage users to review the high-level overview on adding hover information on the Hover Information page first.

Below, we summarize the unique behavior with the plotly back end when adding or modifying hover information.

Axis Hover Information

With the plotly back end, axis hover information shows up when moving your mouse over the axis label:

hp = example_hive_plot(backend="plotly")

fig = hp.plot(hover="axes")
fig

Axis-Specific Metadata

When a subset of axes has added metadata not available on other axes, the metadata variable will only show up when hovering over that axis label. The axes without the variable will not display the variable name.

Below, we demonstrate this by adding a new metadata variable to only axis A:

hp = example_hive_plot(backend="plotly")

# add metadata value to just axis A
hp.axes["A"].add_metadata({"Special Axis Data": "My Special 'A' Value"})

fig = hp.plot(hover="axes")
fig