hypertools.set_interactive_backend

class hypertools.set_interactive_backend(backend)

Set the plotting backend hypertools uses.

Accepts two kinds of values:

1. A render backend – 'matplotlib' or 'plotly' (case-insensitive) – selecting which library draws hypertools plots. By default, hypertools auto-detects: it renders with plotly on Google Colab and Kaggle (where plotly is preinstalled and matplotlib figures are static) and with matplotlib everywhere else. Passing 'auto' (or None) restores this default auto-detection after a render backend has been set.

2. A matplotlib backend name (e.g., 'TkAgg', 'QtAgg', 'MacOSX') – the matplotlib GUI backend used for interactive and animated plots when rendering with matplotlib.

Whereas hypertools.plot’s backend and mpl_backend keyword arguments can be used to specify these for a single plot, hypertools.set_interactive_backend is useful for doing so for multiple (or all) plots at once, and can be used in two different ways:

1. directly, to change the backend for all subsequent plots:

   import hypertools as hyp
   data = hyp.load('weights_avg')
   
   hyp.plot(data)                        # rendered with matplotlib
   
   hyp.set_interactive_backend('plotly')
   hyp.plot(data)                        # rendered with plotly
   hyp.plot(data, animate=True)          # animated plotly figure
   
   hyp.set_interactive_backend('auto')   # restore auto-detection
   

2. as a context manager with the with statement, to temporarily change the backend:

   import hypertools as hyp
   data = hyp.load('weights_avg')
   
   with hyp.set_interactive_backend('plotly'):
       hyp.plot(data, interactive=True)  # rendered with plotly
   
   hyp.plot(data, animate=True)          # default backend again
   

Parameters:

backendstr or None

Either a render backend ('matplotlib' or 'plotly'), 'auto'/None to restore render-backend auto-detection, or the matplotlib backend to use for interactive plots (e.g., 'TkAgg'). Applies temporarily when used as a context manager with with, or for the life of the interpreter when called as a function.

Raises:

TypeError

If backend is not a string (or None).

ValueError

If backend is not 'auto', a render backend, or a recognized matplotlib backend name. The error message lists the valid choices.

HypertoolsBackendError

When entering the context manager with a matplotlib backend that cannot be switched to on the current system (e.g., 'TkAgg' without a working Tk installation). In that case, the pre-existing backend settings are left unchanged.

Notes

1. set_interactive_backend is technically a class, but it shouldn’t typically be used as one and is only designed this way to enable it to work as both a regular function and a context manager.

2. Calling this directly does not immediately change the plotting backend; it changes the backend hypertools will use to create interactive plots going forward.

3. However, when used as a context manager with a matplotlib backend name, the backend passed to hypertools.set_interactive_backend will be used for all plots created inside the context block, regardless of whether:

   • they are interactive/animated or static

   • the mpl_backend keyword argument is passed to hypertools.plot

   • they were created with hypertools, matplotlib, or a different matplotlib-based library (e.g., seaborn, quail, umap-learn)

   There are a few reasons for this behavior:

   • being able to skip inspecting the arguments passed to each hypertools.plot call means almost no overhead is added for calls after the first, and makes wrapping multiple calls much more efficient

   • the plotting backend is an attribute of matplotlib itself and matplotlib doesn’t support running multiple backends simultaneously in the same namespace, so it’s impossible to avoid it affecting other matplotlib-based plotting libraries

   • it’s reasonable to assume this was the desired outcome when multiple plots are generated inside a context block, since A) the context block will always have been created manually by the user, and B) the API provides multiple other ways to set the backend without this effect

4. The manage_backend decorator for hypertools.plot determines whether it’s being called inside the hypertools.set_interactive_backend context manager by checking the value of a global variable (IN_SET_CONTEXT), which is backed by a nesting-depth counter (_SET_CONTEXT_DEPTH) so it remains True until the outermost context block exits. This global-flag approach is used instead of the alternatives – A) using something like inspect.getframeinfo or traceback.extract_stack to look for the context manager every time hypertools.plot is called, or B) re-running the same runtime argument checks every time – either of which would be much less efficient.

5. The $HYPERTOOLS_BACKEND environment variable provides a third way of setting the backend: if set before hypertools is imported, it overrides the default matplotlib backend used for interactive/animated matplotlib plots. It accepts matplotlib backend names only – to prefer the plotly renderer, use hypertools.set_interactive_backend(‘plotly’) or hypertools.plot’s backend=’plotly’ keyword argument instead.

__init__(backend)

Methods

__init__(backend)