deephaven.ui

Now that you're more familiar with the table API and visualizing data, it's time to consider how to present your work. The deephaven.ui package provides a rich set of tools for building interactive user experiences that show off the tables, plots, and other widgets your queries created.

What is deephaven.ui?

deephaven.ui is a React-like framework for building user experiences in Python. You don't need any front-end development, JavaScript, or CSS experience to hit the ground running. Key features include:

• Components: You build user interfaces from components defined entirely in Python.
• Live dataframe integration: Components are live dataframe aware and use Deephaven tables as a data source, including ticking tables that update as new data arrives.
• Reactive UI updates: Components update automatically when a user interacts with them or when their source data changes.
• Declarative UI framework: You describe the UI as a function of the data, and the framework renders it.
• Composability: You combine and reuse components to build complex interfaces.
• Wide range of components: The library includes everything from simple text fields to complex tables and plots.

deephaven.ui exposes many React Spectrum components to Python. React Spectrum is Adobe's implementation of the Spectrum design system. Component names and arguments generally match React Spectrum's, except that Python uses snake_case instead of camelCase. For example, onPress becomes on_press, and defaultValue becomes default_value.

Components

At the core of deephaven.ui are components, which are reusable building blocks for your user interface. Take, for instance, a simple heading:

This component isn't very exciting. What about a component that handles events, such as a button click?

In this example, the on_press handler takes the press event as an argument. If you don't need the event, the handler can take no arguments, as in the examples that follow.

Custom components

With deephaven.ui, you can decorate functions with @ui.component to define your own components that combine several built-in components and have custom behavior. The following example is a simple component that builds off the button example.

State and hooks

To make components more useful, deephaven.ui offers hooks. A hook is a function whose name starts with use_, and you call it inside a component.

The use_state hook manages state, a value the component keeps from one call of the component function to the next:

• use_state returns the current value and a function that sets a new one.
• When the state changes, deephaven.ui re-renders the component. It calls the component function again, so the UI shows the new value.

For instance, you can count how many times someone clicks a button. Each instance of a component has its own state. Click c1 and c2 separately to see that each one keeps its own count:

More components

Headings and buttons are only two of the many components available in deephaven.ui, and you can combine any of them with custom components and state. The following code shows off a few more components, including a picker, a combo box, and a slider. It also uses ui.flex, which lays out its children in a row, or in a column with direction="column":

For a full list of available components, see the Components overview.

Table-backed components

Things get a lot more interesting when you use Deephaven tables as the data source for components. When a source table is ticking, components built from it tick in lockstep with it. The examples in this section use a static CSV file to keep things simple, and the Dashboards section shows components fed by ticking data.

You can pass a table to a component to display its data. Take the picker example above. What if you want to choose from the available values in a column of a table?

You can take this a step further and use the selected value to filter a table. The following example:

• Stores the selected species in component state, starting with Iris-setosa.
• Filters the table to that species.
• Plots a density heatmap from Deephaven Express, which shows how many observations fall in each sepal length and sepal width bin.
• Returns the picker and heatmap together in a ui.panel, a titled container that the Dashboards section builds on.

The example also uses the use_memo hook, which caches the result of a function and calls it again only when one of the listed dependencies changes. Because the component re-renders every time its state changes, the example uses use_memo three times:

• To read the CSV file once, not on every re-render.
• To compute the distinct species once.
• To filter the table again only when the selected species changes.

Dashboards

A dashboard arranges panels into a layout. Dashboards are a great way to present data and visualizations in a single view. You build the layout from these elements:

• ui.panel is a titled container for a component, like the panel the species explorer above returns.
• ui.row arranges panels side by side, and ui.column arranges them top to bottom. Rows and columns nest inside each other.
• ui.stack groups panels as tabs.

The following example creates a 2x2 dashboard of placeholder panels to show how you build a dashboard's grid layout in code.

A 2x2 grid doesn't suit many applications, but you can customize the layout to fit your needs. What if you need a header and footer around a row of panels of different widths? You size layout elements with percentages relative to their siblings:

• A row takes an optional height.
• A column takes an optional width.
• A stack takes either one.
• A panel doesn't take a size, so to size a single panel, wrap it in a ui.stack.

The following example puts a header and footer above and below a row of three panels, and makes the middle one wider:

Dashboards are much more interesting when their panels hold real data, plots, and widgets. The next example uses dx.data.iris, a ticking version of the Iris dataset that ships with Deephaven Express. It adds simulated rows every second, so the table and plots in the dashboard update as new rows arrive. Its column names differ from those in the CSV file used above. For example, it has SepalLength instead of SepalLengthCM.

The dashboard holds a table, a scatter plot, two histograms, and a Markdown panel describing the dataset. The example wraps the table in ui.table, which adds display options such as row order and which columns appear first or are hidden:

This crash course page only scratches the surface of what you can do with deephaven.ui. For more components, hooks, and examples, see the deephaven.ui documentation.