Class Figure

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 dh.plot.DownsampleOptions argument. Presently only two valid values exist, DEFAULT, and 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, 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 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, downsamplefinished will be fired. These events will repeat when the range changes, such as when zooming, panning, or resizing the figure. Finally, downsamplefailed indicates that something when wrong when downsampling, or possibly that downsampling cannot be disabled due to the number of rows in the table.

At this time, not marked as a ServerObject, due to internal implementation issues which leave the door open to client-created figures.