Package io.deephaven.web.client.api.widget.plot

Class JsFigure

java.lang.Object

io.deephaven.web.client.api.event.HasEventHandling

io.deephaven.web.client.api.lifecycle.HasLifecycle

io.deephaven.web.client.api.widget.plot.JsFigure

@JsType(name="Figure",
        namespace="dh.plot")
public class JsFigure
extends HasLifecycle

Provides the details for a figure.

The Deephaven JS API supports automatic lossless downsampling of time-series data, when that data is plotted in one or more line series. Using a scatter plot or a X-axis of some type other than DateTime will prevent this feature from being applied to a series. To enable this feature, invoke Axis.range to specify the length in pixels of the axis on the screen, and the range of values that are visible, and the server will use that width (and range, if any) to reduce the number of points sent to the client.

Downsampling can also be controlled when calling either Figure.subscribe or Series.subscribe - both can be given an optional DownsampleOptions argument. Presently only two valid values exist, DownsampleOptions.DEFAULT and DownsampleOptions.DISABLE, and if no argument is specified, DEFAULT is assumed. If there are more than 30,000 rows in a table, downsampling will be encouraged - data will not load without calling subscribe(DISABLE) or enabling downsampling via Axis.range. If there are more than 200,000 rows, data will refuse to load without downsampling and subscribe(DISABLE) would have no effect.

Downsampled data looks like normal data, except that select items have been removed if they would be redundant in the UI given the current configuration. Individual rows are intact, so that a tooltip or some other UI item is sure to be accurate and consistent, and at least the highest and lowest value for each axis will be retained as well, to ensure that the "important" values are visible.

Four events exist to help with interacting with downsampled data, all fired from the Figure instance itself. First, EVENT_DOWNSAMPLENEEDED indicates that more than 30,000 rows would be fetched, and so specifying downsampling is no longer optional - it must either be enabled (calling Axis.range), or disabled. If the figure is configured for downsampling, when a change takes place that requires that the server perform some downsampling work, the EVENT_DOWNSAMPLESTARTED event will first be fired, which can be used to present a brief loading message, indicating to the user why data is not ready yet - when the server side process is complete, EVENT_DOWNSAMPLEFINISHED will be fired. These events will repeat when the range changes, such as when zooming, panning, or resizing the figure. Finally, EVENT_DOWNSAMPLEFAILED indicates that something went wrong when downsampling, or possibly that downsampling cannot be disabled due to the number of rows in the table.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	JsFigure.AxisRange
static class	JsFigure.DownsampledAxisDetails	Tracks ranges that an axis has registered for.
static class	JsFigure.DownsampleParams
static interface	JsFigure.FigureClose
class	JsFigure.FigureFetchError	Error details for a failed figure fetch.
class	JsFigure.FigureSourceException	Indicates that a series data source could not be resolved or used for this figure.
static interface	JsFigure.FigureTableFetch
static class	JsFigure.FigureTableFetchData

Nested classes/interfaces inherited from class io.deephaven.web.client.api.event.HasEventHandling

HasEventHandling.EventPair<T>

Field Summary

Fields

Modifier and Type	Field	Description
static final String	EVENT_DISCONNECT	This figure has lost its connection to the server.
static final String	EVENT_DOWNSAMPLEFAILED	Downsampling failed for some reason on one or more series.
static final String	EVENT_DOWNSAMPLEFINISHED	Downsampling has finished on the given Series instances, and data will arrive shortly.
static final String	EVENT_DOWNSAMPLENEEDED	There are too many points to be drawn in the table which backs these series, and downsampling should be enabled.
static final String	EVENT_DOWNSAMPLESTARTED	The API is updating how downsampling works on this Figure, probably in response to a call to Axis.range or subscribe.
static final String	EVENT_RECONNECT	This figure has reconnected to the server, and all of its tables are ready to deliver data again.
static final String	EVENT_RECONNECTFAILED	This figure failed to reconnect to the server, and is no longer usable.
static final String	EVENT_SERIES_ADDED	A series used within this figure was added as part of a multi-series in a chart.
static final String	EVENT_UPDATED	The data within this figure was updated.

Fields inherited from class io.deephaven.web.client.api.event.HasEventHandling

INTERNAL_EVENT_RELEASED

Constructor Summary

Constructors

Constructor	Description
JsFigure(WorkerConnection connection, Supplier<elemental2.promise.Promise<FetchObjectResponse>> fetch)
JsFigure(Supplier<elemental2.promise.Promise<FetchObjectResponse>> fetch, JsFigure.FigureTableFetch tableFetch)

Method Summary

Modifier and Type	Method	Description
void	close()	Close the figure, and clean up subscriptions.
void	downsampleFailed(String message, Set<JsSeries> series, double tableSize)
void	downsampleNeeded(String message, Set<JsSeries> series, double tableSize)
void	enqueueSubscriptionCheck()
JsChart[]	getCharts()	The charts to draw.
int	getCols()	The number of columns in this figure's chart layout.
elemental2.core.JsArray<String>	getErrors()	Any errors that the server reported while building this figure.
int	getRows()	The number of rows in this figure's chart layout.
@JsNullable String	getTitle()	The title of the figure, or null if no title was set.
String	getTitleColor()	The color to use when drawing the figure's title.
String	getTitleFont()	The font to use when drawing the figure's title.
double	getUpdateInterval()	The update interval of this figure, in milliseconds.
void	reconnect()	Asks the figure to fire a reconnect event after its tables are ready.
elemental2.promise.Promise<JsFigure>	refetch()	Indicate that a new session has been created on the server, and this object should re-create its corresponding server-side object if possible.
int	registerTable(JsTable table)
void	subscribe()	Enable updates for all series in this figure.
void	subscribe(@JsNullable DownsampleOptions forceDisableDownsample)	Subscribe to the underlying tables to receive updates for all series in this figure.
void	unsubscribe()	Disable updates for all series in this figure.
void	updateDownsampleRange(FigureDescriptor.AxisDescriptor axis, Integer pixels, Long min, Long max)
void	verifyTables()	Verifies that the underlying tables have the columns the series are expected.

Methods inherited from class io.deephaven.web.client.api.lifecycle.HasLifecycle

die, disconnected, nextReconnect

Methods inherited from class io.deephaven.web.client.api.event.HasEventHandling

addEventListener, addEventListenerOneShot, addEventListenerOneShot, failureHandled, fireCriticalEvent, fireCriticalEvent, fireEvent, fireEvent, fireEvent, hasListener, hasListeners, isSuppress, logPrefix, nextEvent, removeEventListener, suppressEvents, unsuppressEvents

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

EVENT_UPDATED

@JsProperty(namespace="dh.plot.Figure")
public static final String EVENT_UPDATED

The data within this figure was updated. event.detail is FigureUpdateEventData.

See Also:

• Constant Field Values

EVENT_SERIES_ADDED

@JsProperty(namespace="dh.plot.Figure")
public static final String EVENT_SERIES_ADDED

A series used within this figure was added as part of a multi-series in a chart. The series instance is the detail for this event.

See Also:

• Constant Field Values

EVENT_DISCONNECT

@JsProperty(namespace="dh.plot.Figure")
public static final String EVENT_DISCONNECT

This figure has lost its connection to the server. No further events will be fired, and no data will update, until either the connection is reestablished and EVENT_RECONNECT is fired, or EVENT_RECONNECTFAILED fires, indicating that it wasn't possible to reconnect and the figure should be recreated/refetched.

See Also:

• Constant Field Values

EVENT_RECONNECT

@JsProperty(namespace="dh.plot.Figure")
public static final String EVENT_RECONNECT

This figure has reconnected to the server, and all of its tables are ready to deliver data again. Any subscriptions that were active before the disconnect are restored.

See Also:

• Constant Field Values

EVENT_RECONNECTFAILED

@JsProperty(namespace="dh.plot.Figure")
public static final String EVENT_RECONNECTFAILED

This figure failed to reconnect to the server, and is no longer usable. The event.detail value is a FigureFetchError describing what went wrong.

See Also:

• Constant Field Values

EVENT_DOWNSAMPLESTARTED

@JsProperty(namespace="dh.plot.Figure")
public static final String EVENT_DOWNSAMPLESTARTED

The API is updating how downsampling works on this Figure, probably in response to a call to Axis.range or subscribe. The event.detail value is an array of Series instances which are affected by this.

See Also:

• Constant Field Values

EVENT_DOWNSAMPLEFINISHED

@JsProperty(namespace="dh.plot.Figure")
public static final String EVENT_DOWNSAMPLEFINISHED

Downsampling has finished on the given Series instances, and data will arrive shortly. The event.detail value is the array of Series instances.

See Also:

• Constant Field Values

EVENT_DOWNSAMPLEFAILED

@JsProperty(namespace="dh.plot.Figure")
public static final String EVENT_DOWNSAMPLEFAILED

Downsampling failed for some reason on one or more series. The event.detail object has three properties: the message string describing what went wrong, the size number showing the full size of the table, and the series property, an array of Series instances affected.

See Also:

• Constant Field Values

EVENT_DOWNSAMPLENEEDED

@JsProperty(namespace="dh.plot.Figure")
public static final String EVENT_DOWNSAMPLENEEDED

There are too many points to be drawn in the table which backs these series, and downsampling should be enabled. As an alternative, downsampling can be explicitly disabled, provided there are less than 200,000 rows in the table. The event.detail object has the same properties as EVENT_DOWNSAMPLEFAILED.

See Also:

• Constant Field Values

Constructor Details

JsFigure

@JsIgnore
public JsFigure(WorkerConnection connection,
 Supplier<elemental2.promise.Promise<FetchObjectResponse>> fetch)

JsFigure

@JsIgnore
public JsFigure(Supplier<elemental2.promise.Promise<FetchObjectResponse>> fetch,
 JsFigure.FigureTableFetch tableFetch)

Method Details

refetch

@JsIgnore
public elemental2.promise.Promise<JsFigure> refetch()

Description copied from class: HasLifecycle

Indicate that a new session has been created on the server, and this object should re-create its corresponding server-side object if possible. Override this to implement custom behavior, being sure to call reconnect() when finished.

Overrides:

refetch in class HasLifecycle

Returns:

a promise that will resolve when this object is reconnected

reconnect

@JsIgnore
public void reconnect()

Asks the figure to fire a reconnect event after its tables are ready.

Overrides:

reconnect in class HasLifecycle

getTitle

@JsProperty
public @JsNullable String getTitle()

The title of the figure, or null if no title was set.

getTitleFont

@JsProperty
public String getTitleFont()

The font to use when drawing the figure's title.

getTitleColor

@JsProperty
public String getTitleColor()

The color to use when drawing the figure's title.

getUpdateInterval

@JsProperty
public double getUpdateInterval()

The update interval of this figure, in milliseconds.

getCols

@JsProperty
public int getCols()

The number of columns in this figure's chart layout.

getRows

@JsProperty
public int getRows()

The number of rows in this figure's chart layout.

getCharts

@JsProperty
public JsChart[] getCharts()

The charts to draw.

getErrors

@JsProperty
public elemental2.core.JsArray<String> getErrors()

Any errors that the server reported while building this figure.

subscribe

@JsIgnore
public void subscribe()

Enable updates for all series in this figure.

subscribe

public void subscribe(@JsOptional
 @JsNullable DownsampleOptions forceDisableDownsample)

Subscribe to the underlying tables to receive updates for all series in this figure.

Parameters:

forceDisableDownsample - the downsampling behavior to use for every series in this figure. Pass DownsampleOptions.DISABLE to load all data without downsampling, or omit the argument to use DownsampleOptions.DEFAULT.

unsubscribe

public void unsubscribe()

Disable updates for all series in this figure.

downsampleNeeded

@JsIgnore
public void downsampleNeeded(String message,
 Set<JsSeries> series,
 double tableSize)

downsampleFailed

@JsIgnore
public void downsampleFailed(String message,
 Set<JsSeries> series,
 double tableSize)

enqueueSubscriptionCheck

@JsIgnore
public void enqueueSubscriptionCheck()

verifyTables

@JsIgnore
public void verifyTables()

Verifies that the underlying tables have the columns the series are expected. Throws an FigureSourceException if not found

close

public void close()

Close the figure, and clean up subscriptions.

registerTable

@JsIgnore
public int registerTable(JsTable table)

updateDownsampleRange

@JsIgnore
public void updateDownsampleRange(FigureDescriptor.AxisDescriptor axis,
 Integer pixels,
 Long min,
 Long max)