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/server Docker 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, and server-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:

A line plot of y values against x values

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:

Four plots in a two-by-two grid

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

A line plot of Y against X from a Deephaven table

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:

A 3D scatter plot

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:

A 3D bar graph

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

A 3D triangular surface plot

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:

  1. The figure to redraw.
  2. The ticking table that supplies the data.
  3. The function that updates the figure. TableAnimation calls it with two arguments:
    • data: a dictionary that maps each column name to a NumPy array of the table's current values.
    • update: the TableUpdate that 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:

A real-time line chart

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:

A bar chart updating in real time

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:

  1. Reads the rows added since the last update with added.
  2. Appends each row's X and Y to the offsets and its Z to the sizes.
  3. Passes the lists to set_offsets and set_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:

A real-time scatter plot

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 of columns=[], so that TableAnimation copies those columns into data.
  • Builds the offsets from data["X"] and data["Y"] with NumPy's column_stack, and the sizes from data["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:

Multiple series on the same plot

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:

A line plot created with Seaborn

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:

A real-time line plot created with Seaborn

Seaborn bar plot

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

A real-time bar plot created with Seaborn

Seaborn scatter plot

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

A real-time scatter plot created with Seaborn

Seaborn multiple series

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

A multi-series line plot created with Seaborn