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, 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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[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 (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)[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 (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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[source]#

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()[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) – 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)[source]#

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)[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) – 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)[source]#

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)[source]#

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)[source]#

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)[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) – 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 (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)[source]#

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)[source]#

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)[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 x-axis but two different y-axes.

Parameters:: name (str) – name
Return type:: Figure
Returns:: a new Figure
Raises:: DHError –