Changing Visualization Back Ends#

This notebook covers changing the visualization back end.

[1]:

import traceback

from hiveplotlib.datasets import example_hive_plot
from hiveplotlib.hiveplot import supported_viz_backends

Hiveplotlib supports multiple viz back ends in addition to the default matplotlib back end.

To check which back ends Hiveplotlib supports, users can always run the hiveplotlib.hiveplot.supported_viz_backends() function.

[2]:

supported_viz_backends()

[2]:

typing.Literal['bokeh', 'datashader', 'holoviews-bokeh', 'holoviews-matplotlib', 'matplotlib', 'plotly']

If you are using a non-matplotlib viz back end, make sure to install the added dependencies when installing Hiveplotlib, i.e.

  • pip install hiveplotlib[bokeh] when using the bokeh back end.

  • pip install hiveplotlib[datashader] when using the datashader back end.

  • pip install hiveplotlib[holoviews] when using either of the holoviews-matplotlib or holoviews-bokeh back ends.

  • pip install hiveplotlib[plotly] when using the plotly back end.

These additional viz depencies will not install with the base Hiveplotlib installation (i.e. pip install hiveplotlib).

In this notebook, we will change between using the matplotlib and holoviews-bokeh back ends. Before running this notebook, be sure to install the holoviews dependencies as discussed above.

Setting the Viz Back End#

The HivePlot class uses matplotlib by default for plotting. We can change this either on initialization with the backend parameter, or we can change it with the HivePlot.set_viz_backend() method.

Setting the Viz Back End on Hive Plot Initialization#

By default a HivePlot instance sets backend="matplotlib", but we can override this default on initialization to any of the supported viz back ends.

[3]:

hp = example_hive_plot(backend="holoviews-bokeh")
hp.plot()
ⓘ 
[3]:

Changing the Viz Back End on an Existing Hive Plot#

We can also change the viz back end on an existing hive plot with the HivePlot.set_viz_backend() method.

[4]:

# initializes with default matplotlib
hp = example_hive_plot()

hp.plot();
../_images/notebooks_changing_viz_backends_9_0.png 
[5]:

hp.set_viz_backend("holoviews-bokeh")
hp.plot()
ⓘ 
[5]:

Invalid Viz Back Ends#

If a user provides an unsupported viz back end, a InvalidVizBackendError will be raised.

[6]:

from hiveplotlib.exceptions import InvalidVizBackendError

try:
    example_hive_plot(backend="unsupported_back_end")
except InvalidVizBackendError:
    traceback.print_exc()

Traceback (most recent call last):
  File "/tmp/ipykernel_20255/485113766.py", line 4, in <module>
    example_hive_plot(backend="unsupported_back_end")
  File "/home/garyk/repos/hiveplotlib/src/hiveplotlib/datasets/toy_hive_plots.py", line 407, in example_hive_plot
    return HivePlot(
           ^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/src/hiveplotlib/hiveplot.py", line 1725, in __init__
    self.set_viz_backend(backend=backend)
  File "/home/garyk/repos/hiveplotlib/src/hiveplotlib/hiveplot.py", line 2711, in set_viz_backend
    raise InvalidVizBackendError(msg)
hiveplotlib.exceptions.hive_plot.InvalidVizBackendError: Requested backend 'unsupported_back_end' not among supported backends ('bokeh', 'datashader', 'holoviews-bokeh', 'holoviews-matplotlib', 'matplotlib', 'plotly').

Fixing Kwarg Incompatibility When Changing Viz Back Ends#

Different viz back ends use different plotting keyword arguments. When we switch back ends, depending on our settings, we thus might need to rename or remove some keyword arguments used in plotting.

For nodes and axes, users will need to rename their kwargs accordingly.

For edge kwargs, however, Hiveplotlib offers special support due to the multiple ways users can provide edge kwargs (for more, see the Changing Edge Keyword Arguments page).

For edges, users can use the HivePlot.rename_edge_kwargs() method. This offers two means of support:

  1. For edge kwargs that have a different name with a different back end (e.g. linewidth to line_width), we can rename them by calling HivePlot.rename_edge_kwargs(old_name=new_name).

  2. For edge kwargs that have no name in the new back end, we can drop them by calling HivePlot.rename_edge_kwargs(old_name=None).

Let’s replicate both (1) and (2) with a conversion from matplotlib to holoviews-bokeh:

[7]:

hp = example_hive_plot(
    all_edge_kwargs={
        "color": "deeppink",  # no conversion necessary
        "zorder": 10,  # no hv-bokeh equivalent
        "linewidth": 2,  # needs name conversion in hv-bokeh
    },
)
hp.plot();
../_images/notebooks_changing_viz_backends_14_0.png

If we set the back end to holoviews-bokeh, we’ll get an error about not recognizing zorder when we try to plot:

[8]:

hp.set_viz_backend("holoviews-bokeh")

try:
    hp.plot()
except ValueError:
    traceback.print_exc()
ⓘ 
Traceback (most recent call last):
  File "/tmp/ipykernel_20255/1341551726.py", line 4, in <module>
    hp.plot()
  File "/home/garyk/repos/hiveplotlib/src/hiveplotlib/hiveplot.py", line 3804, in plot
    return hive_plot_viz(self, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/src/hiveplotlib/viz/holoviews.py", line 899, in hive_plot_viz
    fig = edge_viz(
          ^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/src/hiveplotlib/viz/holoviews.py", line 713, in edge_viz
    temp_curves = hv.Contours(
                  ^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/accessors.py", line 43, in pipelined_call
    result = __call__(*args, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/accessors.py", line 607, in __call__
    return self._dispatch_opts( *args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/accessors.py", line 611, in _dispatch_opts
    return self._base_opts(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/accessors.py", line 694, in _base_opts
    return self._obj.options(*new_args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/data/__init__.py", line 204, in pipelined_fn
    result = method_fn(*args, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/data/__init__.py", line 1312, in options
    return super().options(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/dimension.py", line 1366, in options
    expanded_backends = [(backend, opts._expand_options(options, backend))]
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/util/__init__.py", line 377, in _expand_options
    cls._options_error(opt, objtype, backend, valid_options)
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/util/__init__.py", line 418, in _options_error
    raise ValueError(f'Unexpected option {opt!r} for {objtype} type '
ValueError: Unexpected option 'zorder' for Contours type across all extensions. Similar options for current extension ('bokeh') are: ['border'].

Since holoviews-bokeh doesn’t support any form of zorder, we must eliminate that kwarg:

[9]:

hp.rename_edge_kwargs(zorder=None)

With zorder removed, we can try plotting again, but we have one more unrecognized kwarg in linewidth:

[10]:

try:
    hp.plot()
except ValueError:
    traceback.print_exc()
ⓘ 
Traceback (most recent call last):
  File "/tmp/ipykernel_20255/26058341.py", line 2, in <module>
    hp.plot()
  File "/home/garyk/repos/hiveplotlib/src/hiveplotlib/hiveplot.py", line 3804, in plot
    return hive_plot_viz(self, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/src/hiveplotlib/viz/holoviews.py", line 899, in hive_plot_viz
    fig = edge_viz(
          ^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/src/hiveplotlib/viz/holoviews.py", line 713, in edge_viz
    temp_curves = hv.Contours(
                  ^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/accessors.py", line 43, in pipelined_call
    result = __call__(*args, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/accessors.py", line 607, in __call__
    return self._dispatch_opts( *args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/accessors.py", line 611, in _dispatch_opts
    return self._base_opts(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/accessors.py", line 694, in _base_opts
    return self._obj.options(*new_args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/data/__init__.py", line 204, in pipelined_fn
    result = method_fn(*args, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/data/__init__.py", line 1312, in options
    return super().options(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/core/dimension.py", line 1366, in options
    expanded_backends = [(backend, opts._expand_options(options, backend))]
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/util/__init__.py", line 377, in _expand_options
    cls._options_error(opt, objtype, backend, valid_options)
  File "/home/garyk/repos/hiveplotlib/.venv/lib/python3.12/site-packages/holoviews/util/__init__.py", line 418, in _options_error
    raise ValueError(f'Unexpected option {opt!r} for {objtype} type '
ValueError: Unexpected option 'linewidth' for Contours type across all extensions. Similar options for current extension ('bokeh') are: ['line_width', 'min_width', 'muted_line_width'].

Here, however, there is an appropriate equivalent in line_width, which we can use when renaming linewidth:

[11]:

hp.rename_edge_kwargs(linewidth="line_width")

hp.plot()
ⓘ 
[11]:

Note we also could have replaced these edge kwargs in a single call, but it can be helpful to parse the errors one at a time when initially debugging.

[12]:

hp = example_hive_plot(
    all_edge_kwargs={
        "color": "deeppink",  # no conversion necessary
        "zorder": 10,  # no hv-bokeh equivalent
        "linewidth": 2,  # needs name conversion in hv-bokeh
    },
)

hp.set_viz_backend("holoviews-bokeh")

hp.rename_edge_kwargs(
    zorder=None,  # remove `zorder` from edge kwargs
    linewidth="line_width",  # rename `linewidth` -> `line_width`
)

hp.plot()
ⓘ 
[12]: