deephaven.plot.figure

This module implements the Figure class for creating plots, charts, line, axis, color, etc.

class Figure(rows=1, cols=1, j_figure=None)[source]

Bases: JObjectWrapper

A Figure represents a graphical figure such as a plot, chart, line, axis, color, etc. A Figure is immutable, and all function calls return a new immutable Figure instance.

Initializes a Figure object that is used for displaying plots

Parameters:
  • rows (int) – Number of rows in the figure. Defaults to 1.

  • cols (int) – Number of columns in the figure. Defaults to 1.

  • j_figure (JType) – Internal use only.

axes(name=None, axes=None, remove_series=None, plot_style=None)[source]

Gets specific axes from the chart and updates the chart’s axes’s configurations.

Parameters:
  • name (str | None) – name

  • axes (int | None) – identifier

  • remove_series (list[str] | None) – names of series to remove

  • plot_style (str | PlotStyle | None) – plot style

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

axis(dim=None, t=None, label=None, color=None, font=None, format=None, format_pattern=None, min=None, max=None, invert=None, log=None, business_time=None, calendar=None, transform=None)[source]

Gets a specific axis from a chart’s axes and updates the axis’s configurations.

Parameters:
  • dim (int | None) – dimension of the axis

  • t (Table | SelectableDataSet | None) – table or selectable data set (e.g. OneClick filterable table)

  • label (str | None) – label

  • color (str | int | Color | None) – color

  • font (Font | None) – font

  • format (AxisFormat | None) – label format

  • format_pattern (str | None) – label format pattern

  • min (str | float | None) – minimum value to display

  • max (str | float | None) – maximum value to display

  • invert (bool | None) – invert the axis.

  • log (bool | None) – log axis

  • business_time (bool | None) – business time axis using the default calendar

  • calendar (str | DType | None) – business time axis using the specified calendar

  • transform (AxisTransform | None) – axis transform.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

chart(multi_series_key=None, remove_series=None, index=None, row=None, col=None, row_span=None, col_span=None, orientation=None, grid_visible=None, x_grid_visible=None, y_grid_visible=None, pie_label_format=None)[source]

Gets a chart from the figure’s grid and updates a chart’s configuration.

Parameters:
  • multi_series_key (list[Any] | None) – multi-series keys or a column name containing keys.

  • remove_series (list[str] | None) – names of series to remove

  • index (int | None) – index from the Figure’s grid. The index starts at 0 in the upper left hand corner of the grid and increases going left to right, top to bottom. E.g. for a 2x2 Figure, the indices would be [0, 1] [2, 3].

  • row (int | None) – row index in the Figure’s grid. The row index starts at 0.

  • col (int | None) – column index in this Figure’s grid. The column index starts at 0.

  • row_span (int | None) – how many rows high.

  • col_span (int | None) – how many rows wide.

  • orientation (str | None) – plot orientation.

  • grid_visible (bool | None) – x-grid and y-grid are visible.

  • x_grid_visible (bool | None) – x-grid is visible.

  • y_grid_visible (bool | None) – y-grid is visible.

  • pie_label_format (str | None) – pie chart format of the percentage point label.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

chart_legend(color=None, font=None, visible=None)[source]

Updates a chart’s legend’s configuration.

Parameters:
  • color (str | int | Color | None) – color

  • font (Font | None) – font

  • visible (int | None) – true to draw the design element; false otherwise.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

chart_title(t=None, title=None, columns=None, format=None, max_rows=None, column_names_in_title=None, color=None, font=None)[source]

Sets the title of the chart.

Parameters:
  • t (Table | SelectableDataSet | None) – table or selectable data set (e.g. OneClick filterable table)

  • title (str | None) – title

  • columns (list[str] | None) – columns to include in the title

  • format (str | None) – a java.text.MessageFormat format string for formatting column values in the title

  • max_rows (int | None) – maximum number of row values to show in title

  • column_names_in_title (bool | None) – whether to show column names in title. If this is true, the title format will include the column name before the comma separated values; otherwise only the comma separated values will be included.

  • color (str | int | Color | None) – color

  • font (Font | None) – font

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

figure(remove_series=None, remove_chart_index=None, remove_chart_row=None, remove_chart_col=None, update_millis=None)[source]

Updates the figure’s configuration.

Parameters:
  • remove_series (list[str] | None) – names of series to remove

  • remove_chart_index (int | None) – index from the Figure’s grid to remove. The index starts at 0 in the upper left hand corner of the grid and increases going left to right, top to bottom. E.g. for a 2x2 Figure, the indices would be [0, 1][2, 3].

  • remove_chart_row (int | None) – row index in this Figure’s grid. The row index starts at 0.

  • remove_chart_col (int | None) – column index in this Figure’s grid. The row index starts at 0.

  • update_millis (int | None) – update interval in milliseconds.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

figure_title(title=None, color=None, font=None)[source]

Sets the title of the figure.

Parameters:
  • title (str | None) – title

  • color (str | int | Color | None) – color

  • font (Font | None) – font

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

func(xmin=None, xmax=None, npoints=None)[source]

Updates the configuration for plotting a function.

Parameters:
  • xmin (float | None) – minimum x value to display

  • xmax (float | None) – maximum x value to display

  • npoints (int | None) – number of points

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

j_object_type

alias of Figure

line(multi_series_key=None, color=None, style=None, visible=None)[source]

Sets the line color, style, visibility.

Parameters:
  • multi_series_key (list[Any] | None) – multi-series keys or a column name containing keys.

  • color (str | int | Color | None) – color

  • style (str | LineStyle | None) – line style

  • visible (int | None) – true to draw the design element; false otherwise.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

new_axes(name=None, dim=None)[source]

Creates new axes.

Parameters:
  • name (str | None) – name

  • dim (int | None) – dimension of the axis

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

new_chart(index=None, row=None, col=None)[source]

Adds a new chart to this figure.

Parameters:
  • index (int | None) – index from the Figure’s grid. The index starts at 0 in the upper left hand corner of the grid and increases going left to right, top to bottom. E.g. for a 2x2 Figure, the indices would be [0, 1] [2, 3].

  • row (int | None) – row index in the Figure’s grid. The row index starts at 0.

  • col (int | None) – column index in this Figure’s grid. The column index starts at 0.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

plot_cat(series_name, t=None, category=None, y=None, y_low=None, y_high=None, by=None)[source]

Creates a plot with a discrete, categorical axis. Categorical data must not have duplicates.

Parameters:
  • series_name (str) – name of the data series

  • t (Table | SelectableDataSet | None) – table or selectable data set (e.g. OneClick filterable table)

  • category (str | list[str] | list[int] | list[float] | None) – discrete data or column name

  • y (str | list[int] | list[float] | list[DType] | None) – y-values or column name

  • y_low (str | list[int] | list[float] | list[DType] | None) – lower y error bar

  • y_high (str | list[int] | list[float] | list[DType] | None) – upper y error bar

  • by (list[str] | None) – columns that hold grouping data

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

plot_cat_hist(series_name, t=None, category=None)[source]

Creates a histogram with a discrete axis. Charts the frequency of each unique element in the input data.

Parameters:
  • series_name (str) – name of the data series

  • t (Table | SelectableDataSet | None) – table or selectable data set (e.g. OneClick filterable table)

  • category (str | list[str] | list[int] | list[float] | None) – discrete data or column name

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

plot_ohlc(series_name, t=None, x=None, open=None, high=None, low=None, close=None, by=None)[source]

Creates an open-high-low-close plot.

Parameters:
  • series_name (str) – name of the data series

  • t (Table | SelectableDataSet | None) – table or selectable data set (e.g. OneClick filterable table)

  • x (str | list[DType] | None) – x-values or column name

  • open (str | list[int] | list[float] | list[DType] | None) – bar open y-values.

  • high (str | list[int] | list[float] | list[DType] | None) – bar high y-values.

  • low (str | list[int] | list[float] | list[DType] | None) – bar low y-values.

  • close (str | list[int] | list[float] | list[DType] | None) – bar close y-values.

  • by (list[str] | None) – columns that hold grouping data

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

plot_pie(series_name, t=None, category=None, y=None)[source]

Creates a pie plot. Categorical data must not have duplicates.

Parameters:
  • series_name (str) – name of the data series

  • t (Table | SelectableDataSet | None) – table or selectable data set (e.g. OneClick filterable table)

  • category (str | list[str] | list[int] | list[float] | None) – discrete data or column name

  • y (str | list[int] | list[float] | list[DType] | None) – y-values or column name

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

plot_treemap(series_name, t, id, parent, value=None, label=None, hover_text=None, color=None)[source]

Creates a treemap. Must have only one root.

Parameters:
  • series_name (str) – name of the data series

  • t (Table | SelectableDataSet) – table or selectable data set (e.g. OneClick filterable table)

  • id (str) – column name containing IDs

  • parent (str) – column name containing parent IDs

  • value (str | None) – column name containing values

  • label (str | None) – column name containing labels

  • hover_text (str | None) – column name containing hover text

  • color (str | None) – column name containing color

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

plot_xy(series_name, t=None, x=None, x_low=None, x_high=None, y=None, y_low=None, y_high=None, function=None, by=None, x_time_axis=None, y_time_axis=None)[source]

Creates an XY plot.

Parameters:
  • series_name (str) – name of the data series

  • t (Table | SelectableDataSet | None) – table or selectable data set (e.g. OneClick filterable table)

  • x (str | list[int] | list[float] | list[DType] | None) – x-values or column name

  • x_low (str | list[int] | list[float] | list[DType] | None) – lower x error bar

  • x_high (str | list[int] | list[float] | list[DType] | None) – upper x error bar

  • y (str | list[int] | list[float] | list[DType] | None) – y-values or column name

  • y_low (str | list[int] | list[float] | list[DType] | None) – lower y error bar

  • y_high (str | list[int] | list[float] | list[DType] | None) – upper y error bar

  • function (Callable | None) – function

  • by (list[str] | None) – columns that hold grouping data

  • x_time_axis (bool | None) – whether to treat the x-values as times

  • y_time_axis (bool | None) – whether to treat the y-values as times

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

plot_xy_hist(series_name, t=None, x=None, xmin=None, xmax=None, nbins=None)[source]

Creates an XY histogram.

Parameters:
  • series_name (str) – name of the data series

  • t (Table | SelectableDataSet | None) – table or selectable data set (e.g. OneClick filterable table)

  • x (str | list[int] | list[float] | list[DType] | None) – x-values or column name

  • xmin (float | None) – minimum x value to display

  • xmax (float | None) – maximum x value to display

  • nbins (int | None) – number of bins

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

point(t=None, category=None, multi_series_key=None, color=None, label=None, shape=None, size=None, label_format=None, visible=None)[source]

Sets the point color, label, size, visibility, etc.

Parameters:
  • t (Table | SelectableDataSet | None) – table or selectable data set (e.g. OneClick filterable table)

  • category (str | list[str] | list[int] | list[float] | None) – discrete data or column name

  • multi_series_key (list[Any] | None) – multi-series keys or a column name containing keys.

  • color (str | int | Color | list[str] | list[int] | list[Color] | Callable | dict[Any, str] | dict[Any, int] | dict[Any, Color] | None) – colors or a column name containing colors

  • label (str | list[str] | Callable | dict[Any, str] | None) – labels or a column name containing labels

  • shape (str | Shape | list[str] | list[Shape] | Callable | dict[Any, str] | dict[Any, Shape] | None) – shapes or a column name containing shapes

  • size (int | float | list[int] | list[float] | Callable | dict[Any, int] | dict[Any, float] | None) – sizes or a column name containing sizes

  • label_format (str | None) – point label format.

  • visible (int | None) – true to draw the design element; false otherwise.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

save(path, height=None, width=None, wait=None, timeout_seconds=None)[source]

Saves the Figure as an image.

Parameters:
  • path (str) – output path.

  • height (int | None) – figure height.

  • width (int | None) – figure width.

  • wait (bool | None) – whether to hold the calling thread until the file is written.

  • timeout_seconds (int | None) – timeout in seconds to wait for the file to be written.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

series(name=None, axes=None, group=None, multi_series_key=None, color=None, tool_tip_pattern=None, x_tool_tip_pattern=None, y_tool_tip_pattern=None, error_bar_color=None, gradient_visible=None, naming_function=None)[source]

Gets a specific data series and updates the data series’s configurations.

Parameters:
  • name (str | None) – name

  • axes (int | None) – identifier

  • group (int | None) – group for the data series.

  • multi_series_key (list[Any] | None) – multi-series keys or a column name containing keys.

  • color (str | int | Color | None) – color

  • tool_tip_pattern (str | None) – x and y tool tip format pattern

  • x_tool_tip_pattern (str | None) – x tool tip format pattern

  • y_tool_tip_pattern (str | None) – y tool tip format pattern

  • error_bar_color (str | int | Color | None) – error bar color.

  • gradient_visible (bool | None) – bar gradient visibility.

  • naming_function (Callable | None) – series naming function

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

show()[source]

Creates a displayable version of the figure and returns it.

Args:

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

ticks(font=None, gap=None, loc=None, angle=None, visible=None)[source]

Updates the configuration for major ticks of an axis.

Parameters:
  • font (Font | None) – font

  • gap (float | None) – distance between ticks.

  • loc (list[float] | None) – coordinates of the tick locations.

  • angle (int | None) – angle in degrees.

  • visible (int | None) – true to draw the design element; false otherwise.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

ticks_minor(nminor=None, visible=None)[source]

Updates the configuration for minor ticks of an axis.

Parameters:
  • nminor (int | None) – number of minor ticks between consecutive major ticks.

  • visible (int | None) – true to draw the design element; false otherwise.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

twin(name=None, dim=None)[source]

Creates a new Axes which shares one Axis with the current Axes. For example, this is used for creating plots with a common x-axis but two different y-axes.

Parameters:
  • name (str | None) – name

  • dim (int | None) – dimension of the axis

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

x_axis(t=None, label=None, color=None, font=None, format=None, format_pattern=None, min=None, max=None, invert=None, log=None, business_time=None, calendar=None, transform=None)[source]

Gets the x-Axis from a chart’s axes and updates the x-Axis’s configurations.

Parameters:
  • t (Table | SelectableDataSet | None) – table or selectable data set (e.g. OneClick filterable table)

  • label (str | None) – label

  • color (str | int | Color | None) – color

  • font (Font | None) – font

  • format (AxisFormat | None) – label format

  • format_pattern (str | None) – label format pattern

  • min (str | float | None) – minimum value to display

  • max (str | float | None) – maximum value to display

  • invert (bool | None) – invert the axis.

  • log (bool | None) – log axis

  • business_time (bool | None) – business time axis using the default calendar

  • calendar (str | DType | None) – business time axis using the specified calendar

  • transform (AxisTransform | None) – axis transform.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

x_ticks(font=None, gap=None, loc=None, angle=None, visible=None)[source]

Updates the configuration for major ticks of the x-Axis.

Parameters:
  • font (Font | None) – font

  • gap (float | None) – distance between ticks.

  • loc (list[float] | None) – coordinates of the tick locations.

  • angle (int | None) – angle in degrees.

  • visible (int | None) – true to draw the design element; false otherwise.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

x_ticks_minor(nminor=None, visible=None)[source]

Updates the configuration for minor ticks of the x-Axis.

Parameters:
  • nminor (int | None) – number of minor ticks between consecutive major ticks.

  • visible (int | None) – true to draw the design element; false otherwise.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

x_twin(name=None)[source]

Creates a new Axes which shares the x-Axis with the current Axes. For example, this is used for creating plots with a common x-axis but two different y-axes.

Parameters:

name (str | None) – name

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

y_axis(t=None, label=None, color=None, font=None, format=None, format_pattern=None, min=None, max=None, invert=None, log=None, business_time=None, calendar=None, transform=None)[source]

Gets the y-Axis from a chart’s axes and updates the y-Axis’s configurations.

Parameters:
  • t (Table | SelectableDataSet | None) – table or selectable data set (e.g. OneClick filterable table)

  • label (str | None) – label

  • color (str | int | Color | None) – color

  • font (Font | None) – font

  • format (AxisFormat | None) – label format

  • format_pattern (str | None) – label format pattern

  • min (str | float | None) – minimum value to display

  • max (str | float | None) – maximum value to display

  • invert (bool | None) – invert the axis.

  • log (bool | None) – log axis

  • business_time (bool | None) – business time axis using the default calendar

  • calendar (str | DType | None) – business time axis using the specified calendar

  • transform (AxisTransform | None) – axis transform.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

y_ticks(font=None, gap=None, loc=None, angle=None, visible=None)[source]

Updates the configuration for major ticks of the y-Axis.

Parameters:
  • font (Font | None) – font

  • gap (float | None) – distance between ticks.

  • loc (list[float] | None) – coordinates of the tick locations.

  • angle (int | None) – angle in degrees.

  • visible (int | None) – true to draw the design element; false otherwise.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

y_ticks_minor(nminor=None, visible=None)[source]

Updates the configuration for minor ticks of the y-Axis.

Parameters:
  • nminor (int | None) – number of minor ticks between consecutive major ticks.

  • visible (int | None) – true to draw the design element; false otherwise.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

y_twin(name=None)[source]

Creates a new Axes which shares the y-Axis with the current Axes. For example, this is used for creating plots with a common y-axis but two different x-axes.

Parameters:

name (str | None) – name

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –