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)

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, optional) – Number of rows in the figure. Defaults to 1.

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

• j_figure (jpy.JType, internal) – Internal use only.

axes(name=None, axes=None, remove_series=None, plot_style=None)

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

Parameters:

• name (str) – name

• axes (int) – identifier

• remove_series (List[str]) – names of series to remove

• plot_style (Union[str, PlotStyle]) – 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)

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

Parameters:

• dim (int) – dimension of the axis

• t (Union[Table, SelectableDataSet]) – table or selectable data set (e.g. OneClick filterable table)

• label (str) – label

• color (Union[str, int, Color]) – color

• font (Font) – font

• format (AxisFormat) – label format

• format_pattern (str) – label format pattern

• min (Union[str, float]) – minimum value to display

• max (Union[str, float]) – maximum value to display

• invert (bool) – invert the axis.

• log (bool) – log axis

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

• calendar (Union[str, BusinessCalendar]) – business time axis using the specified calendar

• transform (AxisTransform) – 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)

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

Parameters:

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

• remove_series (List[str]) – names of series to remove

• index (int) – 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) – row index in the Figure’s grid. The row index starts at 0.

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

• row_span (int) – how many rows high.

• col_span (int) – how many rows wide.

• orientation (str) – plot orientation.

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

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

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

• pie_label_format (str) – 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)

Updates a chart’s legend’s configuration.

Parameters:

• color (Union[str, int, Color]) – color

• font (Font) – font

• visible (int) – 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)

Sets the title of the chart.

Parameters:

• t (Union[Table, SelectableDataSet]) – table or selectable data set (e.g. OneClick filterable table)

• title (str) – title

• columns (List[str]) – columns to include in the title

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

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

• column_names_in_title (bool) – 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 (Union[str, int, Color]) – color

• font (Font) – 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)

Updates the figure’s configuration.

Parameters:

• remove_series (List[str]) – names of series to remove

• remove_chart_index (int) – 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) – row index in this Figure’s grid. The row index starts at 0.

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

• update_millis (int) – update interval in milliseconds.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

figure_title(title=None, color=None, font=None)

Sets the title of the figure.

Parameters:

• title (str) – title

• color (Union[str, int, Color]) – color

• font (Font) – font

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

func(xmin=None, xmax=None, npoints=None)

Updates the configuration for plotting a function.

Parameters:

• xmin (float) – minimum x value to display

• xmax (float) – maximum x value to display

• npoints (int) – 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)

Sets the line color, style, visibility.

Parameters:

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

• color (Union[str, int, Color]) – color

• style (Union[str, LineStyle]) – line style

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

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

new_axes(name=None, dim=None)

Creates new axes.

Parameters:

• name (str) – name

• dim (int) – dimension of the axis

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

new_chart(index=None, row=None, col=None)

Adds a new chart to this figure.

Parameters:

• index (int) – 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) – row index in the Figure’s grid. The row index starts at 0.

• col (int) – 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)

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

Parameters:

• series_name (str) – name of the data series

• t (Union[Table, SelectableDataSet]) – table or selectable data set (e.g. OneClick filterable table)

• category (Union[str, List[str], List[int], List[float]]) – discrete data or column name

• y (Union[str, List[int], List[float], List[Instant]]) – y-values or column name

• y_low (Union[str, List[int], List[float], List[Instant]]) – lower y error bar

• y_high (Union[str, List[int], List[float], List[Instant]]) – upper y error bar

• by (List[str]) – columns that hold grouping data

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

plot_cat_hist(series_name, t=None, category=None)

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 (Union[Table, SelectableDataSet]) – table or selectable data set (e.g. OneClick filterable table)

• category (Union[str, List[str], List[int], List[float]]) – 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)

Creates an open-high-low-close plot.

Parameters:

• series_name (str) – name of the data series

• t (Union[Table, SelectableDataSet]) – table or selectable data set (e.g. OneClick filterable table)

• x (Union[str, List[Instant]]) – x-values or column name

• open (Union[str, List[int], List[float], List[Instant]]) – bar open y-values.

• high (Union[str, List[int], List[float], List[Instant]]) – bar high y-values.

• low (Union[str, List[int], List[float], List[Instant]]) – bar low y-values.

• close (Union[str, List[int], List[float], List[Instant]]) – bar close y-values.

• by (List[str]) – columns that hold grouping data

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

plot_pie(series_name, t=None, category=None, y=None)

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

Parameters:

• series_name (str) – name of the data series

• t (Union[Table, SelectableDataSet]) – table or selectable data set (e.g. OneClick filterable table)

• category (Union[str, List[str], List[int], List[float]]) – discrete data or column name

• y (Union[str, List[int], List[float], List[Instant]]) – 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)

Creates a treemap. Must have only one root.

Parameters:

• series_name (str) – name of the data series

• t (Union[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) – column name containing values

• label (str) – column name containing labels

• hover_text (str) – column name containing hover text

• color (str) – 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)

Creates an XY plot.

Parameters:

• series_name (str) – name of the data series

• t (Union[Table, SelectableDataSet]) – table or selectable data set (e.g. OneClick filterable table)

• x (Union[str, List[int], List[float], List[Instant]]) – x-values or column name

• x_low (Union[str, List[int], List[float], List[Instant]]) – lower x error bar

• x_high (Union[str, List[int], List[float], List[Instant]]) – upper x error bar

• y (Union[str, List[int], List[float], List[Instant]]) – y-values or column name

• y_low (Union[str, List[int], List[float], List[Instant]]) – lower y error bar

• y_high (Union[str, List[int], List[float], List[Instant]]) – upper y error bar

• function (Callable) – function

• by (List[str]) – columns that hold grouping data

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

• y_time_axis (bool) – 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)

Creates an XY histogram.

Parameters:

• series_name (str) – name of the data series

• t (Union[Table, SelectableDataSet]) – table or selectable data set (e.g. OneClick filterable table)

• x (Union[str, List[int], List[float], List[Instant]]) – x-values or column name

• xmin (float) – minimum x value to display

• xmax (float) – maximum x value to display

• nbins (int) – 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)

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

Parameters:

• t (Union[Table, SelectableDataSet]) – table or selectable data set (e.g. OneClick filterable table)

• category (Union[str, List[str], List[int], List[float]]) – discrete data or column name

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

• color (Union[str, int, Color, List[str], List[int], List[Color], Callable, Dict[Any,str], Dict[Any,int], Dict[Any,Color]]) – colors or a column name containing colors

• label (Union[str, List[str], Callable, Dict[Any,str]]) – labels or a column name containing labels

• shape (Union[str, Shape, List[str], List[Shape], Callable, Dict[Any,str], Dict[Any,Shape]]) – shapes or a column name containing shapes

• size (Union[int, float, List[int], List[float], Callable, Dict[Any,int], Dict[Any,float]]) – sizes or a column name containing sizes

• label_format (str) – point label format.

• visible (int) – 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)

Saves the Figure as an image.

Parameters:

• path (str) – output path.

• height (int) – figure height.

• width (int) – figure width.

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

• timeout_seconds (int) – 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)

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

Parameters:

• name (str) – name

• axes (int) – identifier

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

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

• color (Union[str, int, Color]) – color

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

• x_tool_tip_pattern (str) – x tool tip format pattern

• y_tool_tip_pattern (str) – y tool tip format pattern

• error_bar_color (Union[str, int, Color]) – error bar color.

• gradient_visible (bool) – bar gradient visibility.

• naming_function (Callable) – series naming function

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

show()

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)

Updates the configuration for major ticks of an axis.

Parameters:

• font (Font) – font

• gap (float) – distance between ticks.

• loc (List[float]) – coordinates of the tick locations.

• angle (int) – angle in degrees.

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

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

ticks_minor(nminor=None, visible=None)

Updates the configuration for minor ticks of an axis.

Parameters:

• nminor (int) – number of minor ticks between consecutive major ticks.

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

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

twin(name=None, dim=None)

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) – name

• dim (int) – 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)

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

Parameters:

• t (Union[Table, SelectableDataSet]) – table or selectable data set (e.g. OneClick filterable table)

• label (str) – label

• color (Union[str, int, Color]) – color

• font (Font) – font

• format (AxisFormat) – label format

• format_pattern (str) – label format pattern

• min (Union[str, float]) – minimum value to display

• max (Union[str, float]) – maximum value to display

• invert (bool) – invert the axis.

• log (bool) – log axis

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

• calendar (Union[str, BusinessCalendar]) – business time axis using the specified calendar

• transform (AxisTransform) – axis transform.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

x_ticks(font=None, gap=None, loc=None, angle=None, visible=None)

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

Parameters:

• font (Font) – font

• gap (float) – distance between ticks.

• loc (List[float]) – coordinates of the tick locations.

• angle (int) – angle in degrees.

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

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

x_ticks_minor(nminor=None, visible=None)

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

Parameters:

• nminor (int) – number of minor ticks between consecutive major ticks.

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

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

x_twin(name=None)

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) – 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)

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

Parameters:

• t (Union[Table, SelectableDataSet]) – table or selectable data set (e.g. OneClick filterable table)

• label (str) – label

• color (Union[str, int, Color]) – color

• font (Font) – font

• format (AxisFormat) – label format

• format_pattern (str) – label format pattern

• min (Union[str, float]) – minimum value to display

• max (Union[str, float]) – maximum value to display

• invert (bool) – invert the axis.

• log (bool) – log axis

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

• calendar (Union[str, BusinessCalendar]) – business time axis using the specified calendar

• transform (AxisTransform) – axis transform.

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

y_ticks(font=None, gap=None, loc=None, angle=None, visible=None)

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

Parameters:

• font (Font) – font

• gap (float) – distance between ticks.

• loc (List[float]) – coordinates of the tick locations.

• angle (int) – angle in degrees.

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

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

y_ticks_minor(nminor=None, visible=None)

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

Parameters:

• nminor (int) – number of minor ticks between consecutive major ticks.

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

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –

y_twin(name=None)

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) – name

Return type:

Figure

Returns:

a new Figure

Raises:

DHError –