Class DataSetXY

Deprecated

Use appendJSON instead

Deprecated

Use appendSamples instead

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

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.

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:

 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.