Matplotlib and Seaborn
Note
For Pythonic plotting in Deephaven, we recommend Deephaven Express, a real-time version of Plotly Express. It plots ticking tables directly, while the Matplotlib plugin copies the table's data and redraws the whole figure on every update. See Limitations of copy-based plotting.
This guide shows you how to use Matplotlib and Seaborn with Deephaven's Matplotlib plugin to create plots in Deephaven, both static plots and plots that redraw each time a ticking table updates.
Caution
All examples in this guide use Matplotlib's explicit interface. They call methods on figure and axes objects, such as ax.plot, instead of plt.plot. Use the explicit interface in your own code too, especially when several plots draw data from ticking tables. The implicit plt functions act on a global current figure, and another plot may have changed it.
Install the Matplotlib plugin and Seaborn
What you need to install depends on how you run Deephaven:
- The
ghcr.io/deephaven/serverDocker image includes Deephaven's Matplotlib plugin but not Seaborn. To use Seaborn, add it as described in Permanently add packages to a custom Docker image. - The machine-learning images (
server-all-ai,server-nltk,server-pytorch,server-sklearn, andserver-tensorflow) include neither, so add both the same way. - In a pip-installed Deephaven environment, install them with
pip3, as shown below.
The server-slim image runs a Groovy console and has no Python, so it can't use this plugin. For other ways to install plugins, see Install and use plugins.
To install the plugin with pip3, run:
To install Seaborn as well, run this command instead. The seaborn extra installs Seaborn 0.13.0 or later along with the plugin:
Matplotlib examples
Static plotting
The plugin displays each Matplotlib figure that you assign to a variable as a PNG image in its own panel in the Deephaven IDE. You don't need to call plt.show. This example plots one line and assigns the figure to m_figure:

Matplotlib's full plotting functionality is available in the Deephaven IDE. For example, a figure with several subplots appears as a single image when you assign it to a variable:

To plot a Deephaven table, convert it to a pandas DataFrame with to_pandas and pass its columns to Matplotlib:

The 3D plots below also pass DataFrame columns to Matplotlib, but they read the DataFrame from a CSV file.
3D plots
To draw a 3D plot, create axes with projection="3d" and assign the figure to a variable. The plugin displays it as an image in its own panel, like any other figure. We adapted the examples below from Five advanced plots in Python Matplotlib. They use the auto85 dataset from Kaggle.
To run them, download the dataset's CSV file and save it as auto_clean.csv in your Deephaven data directory. For more information, see the guide on Docker bind mounts. If you run Deephaven from pip, change /data/auto_clean.csv to the path where you saved the file.
The first example reads the file into a pandas DataFrame, df, and plots each car's length, width, and height as a 3D scatter plot. It colors each point by the car's peak RPM and sizes it by the car's price:

The next two examples reuse df and plt from the previous example. The first one also reuses np and draws a 3D bar graph of the mean peak RPM and mean price for each body style:

The last example draws a triangular surface plot of each car's price over its peak RPM and city MPG:

Real-time plotting with TableAnimation
Deephaven's Matplotlib plugin also lets you visualize real-time data: its TableAnimation class redraws a figure each time a ticking table updates.
TableAnimation needs three inputs:
- The figure to redraw.
- The ticking table that supplies the data.
- The function that updates the figure.
TableAnimationcalls it with two arguments:data: a dictionary that maps each column name to a NumPy array of the table's current values.update: theTableUpdatethat triggered the call.
By default, data holds every column of the table, and TableAnimation copies all of them into NumPy arrays on each update. To copy fewer columns, pass their names in the optional columns argument, for example TableAnimation(line_fig, tt_sin, update_line, columns=["X", "Y"]).
The table must be a refreshing table. TableAnimation first calls the update function on the table's next update, so the figure stays empty until the table ticks.
Assign each TableAnimation to a variable, as the examples below do. If nothing references it, Python garbage-collects it and the animation stops.
Each example below uses its own variable names, such as line_fig and update_line. An update function looks up names like these each time it runs. If a later example reused a name, an earlier animation would start updating the later example's object instead of its own.
Line plot
This example plots a sine wave from a time table that adds a row every second:

Bar plot
This example plots the five largest Y values in a ticking table. Each time the table updates, update_bar sets the bar heights and labels each bar with its X value:

Scatter plot
A scatter plot doesn't store separate x and y arrays like the line plot. It stores each point as an offset, which is an (x, y) pair, and a size. This example's update_scatter keeps one list of offsets and one of sizes. Each time the table updates, it:
- Reads the rows added since the last update with
added. - Appends each row's
XandYto the offsets and itsZto the sizes. - Passes the lists to
set_offsetsandset_sizes.
Because it only appends, this approach works only for an add-only table, which never removes or modifies rows. It also plots only rows added after you create the TableAnimation, because the rows already in the table never reach the update function as added rows. The time table in this example is add-only and starts empty.
update_scatter doesn't use data, so the example passes columns=[] and TableAnimation copies no columns:

If your table can remove or modify rows, rebuild the points from data on every update instead of appending. The next example keeps only the 20 most recent rows with tail. Once the table holds 20 rows, it removes its oldest row each time it adds a new one. Compared with the previous example, it:
- Passes
columns=["X", "Y", "Z"]instead ofcolumns=[], so thatTableAnimationcopies those columns intodata. - Builds the offsets from
data["X"]anddata["Y"]with NumPy'scolumn_stack, and the sizes fromdata["Z"].
Multiple series
A figure can hold more than one kind of series. This example's update_series redraws the lines from data, as in the line plot. It adds the scatter points incrementally, as in the scatter plot.
Because of that, its scatter points have the same limits as the scatter plot's: the table must be add-only, and only rows added after you create the TableAnimation appear. For other tables, rebuild the scatter points from data on each update, as in the example that keeps the 20 most recent rows.
This example draws two line plots and a scatter plot on the same axes:

Seaborn examples
Static plotting with Seaborn
Seaborn's axes-level functions, such as lineplot, scatterplot, and barplot, draw on Matplotlib axes. The Matplotlib plugin therefore displays them the same way it displays a Matplotlib figure. Create a figure and axes with plt.subplots, pass the axes to Seaborn's ax argument, and assign the figure to a variable:

Figure-level functions, such as relplot and catplot, return a FacetGrid instead of a figure. To display one, assign its figure attribute to a variable, for example rel_figure = sns.relplot(...).figure.
Real-time plotting with Seaborn
The real-time Seaborn examples work like the Matplotlib real-time examples. Each one passes a figure, a ticking table, and an update function to TableAnimation, which calls the function each time the table updates. Each example also uses its own variable names, so running a later example doesn't change what an earlier animation updates.
Each update function below clears the axes, builds a pandas DataFrame from data, and redraws the plot. Each example passes columns, so TableAnimation copies only the columns that the plot uses.
Don't call to_pandas on the table inside the update function. TableAnimation runs the update function from a table listener, and to_pandas performs a table operation, which a listener shouldn't do. data already holds a copy of the columns you need.
Seaborn line plot
This example plots a cosine wave from a time table that adds a row every second:

Seaborn bar plot
This example plots the five largest Y values in a ticking table:

Seaborn scatter plot
This example plots random points and sizes each point by its Z value:

Seaborn multiple series
This example draws two line plots and a scatter plot on the same axes:

Related documentation
- Deephaven's table types
- Docker bind mounts
- Plotting overview
- Install and use plugins
- Install and use Python packages
- Use pandas in Deephaven queries
- Create a time table
- Listen to ticking tables
- Deephaven Express
empty_tableheadsorttailtime_tableto_pandasupdateTableUpdatePydocto_pandasPydoc