Class DataSet

Read back the values of a single sample from the dataset by referring to a sample index.

Read back the values of a single sample from the dataset by referring to a sample index.

Add callback function to be triggered when specified event is fired.

 // Example syntax
 object.addEventListener('click', (event) => {
     console.log(event)
 })

Some classes also report extra information about the interacted object with the second parameter:

 // Most series share information about interacted data point
 series.addEventListener('click', (event, info) => {
     console.log(info)
 })

Optional third parameter allows registering event handlers that will automatically remove themselves after first trigger:

 // Example this listener will only fire once
 object.addEventListener('click', (event) => {})

Each class has its own list of supported events. Some events are from HTML standard (click, pointerdown, etc.), while others are own events from LightningChart JS (dispose, resize, etc.)

To find what events are available, you can try following:

• If your development environment has TypeScript enabled, just write addEventListener and see what possible event types the IDE suggests. These APIs are strongly typed, and even the callback event will be correctly typed.
• Otherwise, open the class section in API documentation and check out which interface K type parameter extends.

Alter existing samples in the data set by identifying them with their sample index.

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, alter by sample index
 dataSet.alterSamplesByIndex([0, 10], {
     yValues: [20, 30]
 })

See also:

• alterSamplesByMatch.
• alterSamplesStartingFrom.

Returns

Object itself.

Alter existing samples in the data set.

This method alters existing samples after selecting them based on:

1. the property key (e.g. "x", "id")
2. that properties values (e.g. x=10).

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

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

See also:

• alterSamplesStartingFrom.
• alterSamplesByIndex.

Returns

Object itself.

Alter a continuous range of 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 }
 DataSet.alterSamples(0, {
     x: [0],
     y: [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.
 DataSet.alterSamples(0, {
     x: [0, 1, 2],
     y: [10, 11, 12]
 })

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

See also:

• alterSamplesByMatch.
• alterSamplesByIndex.

Returns

Object itself.

Add several samples by reading from an Array of JavaScript objects.

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

 // Example, property names can be anything
 const arr = [{ timestamp: 0, voltage: 0 }]
 DataSet.appendJSON(arr)

 // Input type can also be list of tuples
 const arr = [
     [0, 100],
     [1, 110]
 ]
 DataSet.appendJSON(arr)

appendJSON will by default store all supplied data properties. If you only want to load specific properties into the data set, then you should whitelist them:

DataSet.appendJSON(data, { whitelist: ['index', 'value'] })

Important: the supplied objects' keys refer to keys of the data sets schema. If schema is not defined, then this operation will set it according to supplied keys with default values.

This operation will push data to a DataSet object (either directly or via series). By default, series will connect to data properties that seem logical. It is, however, recommended to explicitly connect X and Y (etc.) to the correct, specific data properties using data mapping:

 // Data mapping is specified on a series
 series.setDataMapping({ x: 'timestamp', y: 'voltage' })

Supported data property types:

• number
• Date object
• ISO8601 Date time string
  • "2023-09-06T14:30:00.000Z"
  • "2023-09-06"
  • "2023-09-06T14:30:00.000+02:00"
• Color object
  • Colors can also be loaded as single number (uint32, least significant byte = red). Using Color objects in large quantities should be avoided for performance reasons.
• If nonNumeric: true; any value (string, boolean, etc.)

For more detailed documentation, please see Developer documentation.

Returns

Object itself.

Add 1 sample to data set.

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

 // Example, only 1 value
 DataSet.appendSample({ temperature: 0 })

appendSample will by default store all supplied data properties. If you only want to load specific properties into the data set, then you should whitelist them:

DataSet.appendSample(sample, { whitelist: ['index', 'value'] })

Important: the supplied objects keys refer to keys of the data sets schema. If schema is not defined, then this operation will set it according to supplied keys with default values.

This operation will push data to a DataSet object (either directly or via series). By default, series will connect to data properties that seem logical. It is, however, recommended to explicitly connect X and Y (etc.) to the correct, specific data properties using data mapping:

 // Data mapping is specified on a series
 series.setDataMapping({ x: 'index', y: 'value' })

Supported data property types:

• number
• Date object
• ISO8601 Date time string
  • "2023-09-06T14:30:00.000Z"
  • "2023-09-06"
  • "2023-09-06T14:30:00.000+02:00"
• Color object
  • Colors can also be loaded as single number (uint32, least significant byte = red). Using Color objects in large quantities should be avoided for performance reasons.
• If nonNumeric: true; any value (string, boolean, etc.)

For more detailed documentation, please see Developer documentation.

Returns

Object itself.

Add a list of samples to data set.

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

Important: the object keys ("xValues" in above example) refer to keys of the data sets schema. If schema is not defined, then this operation will set it according to supplied keys with default values.

This operation will push data to a DataSet object (either directly or via series). By default, series will connect to data properties that seem logical. It is, however, recommended to explicitly connect X and Y (etc.) to the correct, specific data properties using data mapping:

 // Data mapping is specified on a series
 series.setDataMapping({ x: 'xValues', y: 'yValues' })

More examples:

 // Example, only 1 value
 DataSet.appendSamples({
     temperatures: [100, 101, 102],
 })

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

 // Example, uint32 colors
 DataSet.appendSamples({
     x: [0, 1, 2],
     y: [100, 101, 102],
     colors: [0xff0000ff, 0xff00ff00, 0xffff0000]
 })

Passing arrays or single values can be freely alternated between, as long as at least one Array-like argument is supplied. Single value means using same argument for every new sample defined in the method call.

 // Example, use same color for every sample
 DataSet.appendSamples({
     yValues: [0, 10, 5],
     color: ColorRGBA(255, 0, 0)
 })

Supported data property types:

• Typed array
• number[]
• Single number
• Date[]
• ISO8601 Date time string array
  • "2023-09-06T14:30:00.000Z"
  • "2023-09-06"
  • "2023-09-06T14:30:00.000+02:00"
• Color object or Color[]
  • Colors can also be loaded as single number (uint32, least significant byte = red). Using Color objects in large quantities should be avoided for performance reasons.
• If nonNumeric: true; any value (string, boolean, etc.)

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

For more detailed documentation, please see Developer documentation.

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 "size" of all samples to 5
 DataSet.fill({ size: 5 })

Supported data property types:

• number
• Date object
• ISO8601 Date time string
  • "2023-09-06T14:30:00.000Z"
  • "2023-09-06"
  • "2023-09-06T14:30:00.000+02:00"
• Color object
  • Colors can also be loaded as single number (uint32, least significant byte = red). Using Color objects in large quantities should be avoided for performance reasons.
• If nonNumeric: true; any value (string, boolean, etc.)

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.

Iterator for looping over the underlying data ring buffers in chronological order (oldest to newest). Can be used in conjunction with ringBuffers

This variant returns segments of contiguous data in the ring buffer, which can be more efficient for processing larger amounts of data at once.

 // Example syntax
 const ringBuffers = dataSet.ringBuffers
 for (const range of dataSet.iterateOverRingBufferSegments()) {
     const ys = ringBuffers.y.subarray(range.iStart, range.iStart + range.length)
 }

Iterator for looping over the underlying data ring buffers in chronological order (oldest to newest). Can be used in conjunction with ringBuffers

 // Example syntax
 const ringBuffers = dataSet.ringBuffers
 for (const i of dataSet.iterateOverRingBuffers()) {
     const y = ringBuffers.y[i]
 }

Read back the current contents of the data set.

 // Read back data
 const data = dataSet.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 specified data property has a progressive pattern.

 // Example, read back data that is visible
 chart.axisX.addEventListener('intervalchange', event => {
     const data = dataSet.readBack({ onlyInRange: { key: 'timestamps', start: event.start, end: event.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 each data property.

Read back the values of a single sample from the dataset by referring to a sample index.

Returns

Object with all data properties of that sample

Remove event listener added using addEventListener. The expected argument should be the exact same callback function that was supplied using addEventListener:

 // Basic example syntax
 const listener = () => {}
 obj.addEventListener('click', listener)
 obj.removeEventListener('click', listener)

 // Basic boilerplate of custom interaction when user drags on an object
 obj.addEventListener('pointerdown', (eventDown) => {
     let prevCoord = eventDown
     const handlePointerMove: LCJSInteractionEventListener<'pointermove'> = (eventMove) => {
         const delta = { x: eventMove.clientX - prevCoord.clientX, y: eventMove.clientY - prevCoord.clientY }
         prevCoord = eventMove
         console.log(delta, eventMove.clientX, eventMove.clientY)
     }
     const handlePointerUp: LCJSInteractionEventListener<'pointerup'> = (eventUp) => {
         window.removeEventListener('pointermove', handlePointerMove)
         window.removeEventListener('pointerup', handlePointerUp)
     }
     window.addEventListener('pointermove', handlePointerMove)
     window.addEventListener('pointerup', handlePointerUp)
 })

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:

 DataSet.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.