Interface DataSetXYAPIBeta

Add data as { x: number, y: number } objects.

This method exists only for backwards compatibility reasons. Using appendJSON is recommended instead.

Returns

Object itself.

Deprecated

Use appendJSON instead

Add data as number[] number[]

This method exists only for backwards compatibility reasons. Using appendSamplesXY is recommended instead.

Returns

Object itself.

Deprecated

Use appendSamplesXY instead

Alter existing samples in the data set. This method also supports automatically appending samples when attempting to alter samples that don't exist in data set.

This method alters existing samples by referencing sample indexes. This simply refers to a incrementing counter of when each sample was first introduced. For example, 0 refers to first sample that was added to data set. When data cleaning is enabled, sample indexes do NOT shift. They always point to unique samples, even if old samples are removed.

 // Example, basic usage - set first sample to { x: 0, y: 0 }
 DataSetXY.alterSamples(0, {
     xValues: [0],
     yValues: [1]
 })

 // Example, alter several samples at once - set first sample to { x: 0, y: 10 }, second sample to { x: 1, y: 11 } and so on.
 DataSetXY.alterSamples(0, {
     xValues: [0, 1, 2],
     yValues: [10, 11, 12]
 })

 // Example, alter last sample to have Y = 0.
 DataSetXY.alterSamples(DataSetXY.getNextSampleIndex() - 1, {
     yValues: [0]
 })

See also alterSamplesByID.

Returns

Object itself.

Alter existing samples in the data set.

This method alters existing samples by referencing their ID properties. The ID property is an optional sample number property, which CAN be specified by the user. They have to be enabled using ids and afterwards can be added alongside other data properties, like x, y, etc.

 // Example, basic usage
 const dataSet = new DataSetXY({ ids: true })
 dataSet.appendSamples({
     ids: [0, 1, 2],
     yValues: [10, 12, 7],
 })
 dataSet.alterSamplesByID([1], {
     yValues: [20]
 })
 // result yValues = [10, 20, 7]

 // Example, apply same value to all altered samples
 dataSet.alterSamplesByID([0, 1, 2], { size: 5 })

See also alterSamples.

Returns

Object itself.

Add several samples from JSON by reading values from instructed property names.

 // Example, read x + y
 const arr = [{ x: 0, y: 0 }]
 DataSetXY.appendJSON(arr, { x: 'x', y: 'y' })

 // Example, read custom property names
 const arr = [{ timestamp: 0, voltage: 0 }]
 DataSetXY.appendJSON(arr, { x: 'timestamp', y: 'voltage' })

 // Example, only Y values
 const arr = [{ price: 0 }]
 DataSetXY.appendJSON(arr, { y: 'price' })

 // Example, color values
 const arr = [{ x: 0, y: 0, color: 0xff0000ff }]
 DataSetXY.appendJSON(arr, { x: 'x', y: 'y', color: 'color' })

Please note that before adding optional values (lookup values, ids or colors), they need to be enabled using colors or equivalent!

Supported sample property types:

• x: number, Date object or Date time string
• y: number, Date object or Date time string
• lookupValue: number
• id: number
• color: either Color object or number which represents a Uint32 RGBA color with Red channel being least significant byte. Note that using Color objects in large quantities should be avoided for performance reasons.
  • See uint32ColorFromRGBA

Returns

Object itself.

Add 1 sample to data set.

 // Example, basic usage
 DataSetXY.appendSample({ x: 0, y: 0 })

 // Example, only Y value with automatic X step
 DataSetXY.appendSample({ y: 0, step: 1 })

 // Example, extra properties (color)
 DataSetXY.appendSample({ x: 0, y: 0, color: 0xff0000ff })

Please note that before adding optional values (lookup values, ids or colors), they need to be enabled using colors or equivalent!

Supported sample property types:

• x: number, Date object or Date time string
• y: number, Date object or Date time string
• lookupValue: number
• id: number
• size: number
• rotation: number
• color: either Color object or number which represents a Uint32 RGBA color with Red channel being least significant byte. Note that using Color objects in large quantities should be avoided for performance reasons.
  • See uint32ColorFromRGBA

Returns

Object itself.

Add a list of samples to data set.

 // Example, basic usage.
 DataSetXY.appendSamples({
     xValues: [0, 1, 2],
     yValues: [100, 101, 102],
 })

 // Example, only Y values with automatic X step
 DataSetXY.appendSamples({
     yValues: [100, 101, 102],
     start: 0,
     step: 1,
 })

 // Example, typed array input.
 DataSetXY.appendSamples({
     yValues: new Float32Array([100, 101, 102]),
 })

 // Example, extra properties (color)
 DataSetXY.appendSamples({
     xValues: [0, 1, 2],
     yValues: [100, 101, 102],
     colors: [0xff0000ff, 0xff00ff00, 0xffff0000]
 })

Please note that before adding optional values (lookup values, ids or colors), they need to be enabled using colors or equivalent!

Supported sample property types:

• x: number, Date object or Date time string
• y: number, Date object or Date time string
• lookupValue: number
• id: number
• size: number
• rotation: number
• color: either Color object or number which represents a Uint32 RGBA color with Red channel being least significant byte. Note that using Color objects in large quantities should be avoided for performance reasons.
  • See uint32ColorFromRGBA

offset properties can optionally be used to start reading values from middle of input array. Can be situationally useful.

Returns

Object itself.

Clear all samples in the data set.

Returns

Object itself.

Load same value or many values to all samples that currently exist in the data set.

 // Example, set point size of all samples to 5 pixels
 DataSetXY.fill({ size: 5 })

Returns

Object itself.

Get current configured maximum sample count. See setMaxSampleCount for more information.

Returns

Number of undefined.

Get next new sample index. This also counts old samples that have been dropped out by data cleaning logic.

Returns

Number.

Get number of samples currently existing in the data set. This does NOT count any samples that have been dropped out by data cleaning logic.

Returns

Number.

Unsubscribe from event when configured max sample count is exceeded.

 // Example
 const token = DataSetXY.onMaxSampleCountExceeded((dataSet, currentSampleCount, currentMaxSampleCount, newTotalSampleCount) => {})
 DataSetXY.offMaxSampleCountExceeded(token)

Subscribe to event when configured max sample count is exceeded. This can be used to add custom logic to increase max sample count or not.

 DataSetXY.onMaxSampleCountExceeded((dataSet, currentSampleCount, currentMaxSampleCount, newTotalSampleCount) => {
     // Example, double max sample count
     dataSet.setMaxSampleCount(Math.max(currentMaxSampleCount * 2, newTotalSampleCount))
 })

Returns

Token that can be used to unsubscribe from event.

Read back the current contents of the data set.

 // Read back data
 const data = DataSetXY.readBack()
 console.log(data)

If data cleaning (max sample count) is enabled, this can result in allocating new memory (and thus be expensive). Otherwise, a very efficient operation.

The returned values should NOT be modified.

Optionally, you can include the flag onlyInRange to find return only samples that are in specified range. This is only supported if the data set has a "data pattern" (e.g. { dataPattern: 'ProgressiveX' }). The range is always considered to be in the same dimension as this data pattern (e.g. X Axis).

 // Example, read back data that is visible
 ChartXY.getDefaultAxisX().onIntervalChange((axis, start, end) => {
     const data = DataSetXY.readBack({ onlyInRange: { start, end } })
     console.log(data)
 })

This operation is not "pixel perfect", meaning it can often return 1 extra sample that is not visible (the next and/or previous ones).

Returns

Object with lists of separate data channels, like x coordinates, y coordinates, look up values, colors, etc.

All real-time use cases (where data points are pushed in periodically) must define a "max sample count".

 // Example, keep maximum 1 million samples
 PointLineAreaSeries.setMaxSampleCount(1_000_000)

This allocates the required amount of memory beforehand, which is crucial to get the best performance. After 1 million samples are reached, the oldest samples will start dropping out.

Alternatively, if you are uncertain what value to use and don't want to allocate too much memory up-front, you can start small and automatically increase the buffer size as samples flow in:

 PointLineAreaSeries.setMaxSampleCount({ mode: 'auto', max: 10_000_000 })

This would first allocate only small amount of memory, progressively increase memory allocation as samples come in until eventually limiting sample count to 10 million.

Returns

Object itself.

All real-time use cases (where data points are pushed in periodically) must define a "max sample count".

 // Example, keep maximum 1 million samples
 PointLineAreaSeries.setMaxSampleCount(1_000_000)

This allocates the required amount of memory beforehand, which is crucial to get the best performance. After 1 million samples are reached, the oldest samples will start dropping out.

Alternatively, if you are uncertain what value to use and don't want to allocate too much memory up-front, you can start small and automatically increase the buffer size as samples flow in:

 PointLineAreaSeries.setMaxSampleCount({ mode: 'auto', max: 10_000_000 })

This would first allocate only small amount of memory, progressively increase memory allocation as samples come in until eventually limiting sample count to 10 million.

Returns

Object itself.

Re-specify all values in the data set. This is a convenience method that is fundamentally equal to:

 DataSetXY.clear().appendSamples({ ... })

There are currently no performance differences between using "setSamples" versus "clear + append". However, in future it is possible that setSamples can receive optimizations which would make it recommended over "clear + append". In the mean-time, setSamples is recommended for simplicity and clarity in end user applications.

For parameters documentation, refer to appendSamples method.

Returns

Object itself.