Interface DataSetXYOptions

Optional flag that can be used to prevent DataSetXY from modifying arrays that user passes to its methods. This can happen when supplying Typed arrays to DataSetXY methods, for example:

 const myArr = new Float32Array([ 0, 1, 2, 3, 4 ])
 DataSetXY.appendSamples({ yValues: myArr })
 DataSetXY.alterSamples(...)
 // values inside `myArr` may be affected by operation!

Utilizing this behavior is under no circumstance recommended. However, this flag is added in case this behavior would result in undesired consequences in an user application. In this case, you can simply disable it:

 // Example, disallow DataSetXY methods from altering any data array supplied by user.
 const dataSet = new DataSetXY({ allowInputModification: false })

This can have some disadvantages to performance, but should not be anything too major.

Controls whether automatic sorting of data according to active dataPattern is enabled or disabled. If dataPattern is any kind of progressive pattern, then input data can be automatically sorted to remain in that progressive order. This can be useful when data is arriving in the application asynchronously and it can't be guaranteed that it arrives in the correct order.

Please note that auto sorting only sorts by BATCH, not by SAMPLE. For example, if you supply batches of for example 10 samples at a time, auto sorting is capable of identifying the scenario where a newer batch arrives before one that should be displayed first. However, auto sorting is not capable of sorting any samples that are in wrong order within a BATCH. This is intentional due to effects on performance, and since its not a realistic need scenario.

Defaults to true.

 // Example, disable auto sorting.
 const dataSet = new DataSetXY({ autoSortingEnabled: false })

 // Example, works same way if using series API directly instead of via DataSetXY
 const series = ChartXY.addPointLineAreaSeries({ autoSortingEnabled: false })

If true, the DataSetXY should allocate for Color property to be included for every sample. This can be used to adjust data visualization to use per sample colors. Usually this requires using a IndividualPointFill.

Defaults to false.

 // Example, enable sample colors
 const dataSet = new DataSetXY({ colors: true })

 // Example, works same way if using series API directly instead of via DataSetXY
 const series = ChartXY.addPointLineAreaSeries({ colors: true })

Using individual colors is a 3-step process:

1. Enable colors in DataSetXY or Series (see documentation above).
2. Use a IndividualPointFill fill style:

 // Example
 PointLineAreaSeries.setPointFillStyle(new IndividualPointFill())

3. Supply colors along with your data. The syntax can vary based on which method you are using to supply data, but the general idea is the same:

 // Example 1
 DataSetXY.appendSamples({
     yValues: [0, 1],
     colors: [ColorRGBA(255, 0, 0, 255), ColorRGBA(0, 255, 0, 255)],
 })

 // Example 2
 DataSetXY.appendSample({ x: 0, y: 0, color: ColorRGBA(255, 0, 0, 255) })

IMPORTANT: LCJS Color objects (created using ColorRGBA, ColorHEX, or any other factory method) are very heavy. You should always avoid creating many of them (can show as loading time delays).

There are two general ways to avoid this:

1. Create color objects just once and reuse them between samples:

 const colorRed = ColorRGBA(255, 0, 0, 255)
 const colorGreen = ColorRGBA(0, 255, 0, 255)
 DataSetXY.appendSamples({
     yValues: [0, 1],
     colors: [colorRed, colorGreen]
 })

2. Use uint32 colors (number) instead.

 const colorRed = uint32ColorFromRGBA(255, 0, 0, 255)
 const colorGreen = 0xff00ff00 // NOTE: leftmost byte = alpha, rightmost byte = red
 DataSetXY.appendSamples({
     yValues: [0, 1],
     colors: [colorRed, colorGreen]
 })

Specify pattern of data, if any.

 // Example, most common use case is data that is progressive on X dimension:
 const dataSet = new DataSetXY({ dataPattern: 'ProgressiveX' })

For best practices, the data pattern should ALWAYS be specified, even if there is no pattern to data (scatter data). If data pattern is not explicitly specified, it may be automatically detected but this will always trigger a console warning as the automatic detection is not intended for production purposes.

 // Example, even if there is no data pattern, it should still be explicitly pointed out
 const dataSet = new DataSetXY({ dataPattern: null })

 // Example, works same way if using series API directly instead of via DataSetXY
 const series = ChartXY.addPointLineAreaSeries({ dataPattern: true })

See DataPatternNew for all possible data patterns apart from null.

IMPORTANT: Currently DataSetXY is in public beta state. The most hefty limitation is that only ProgressiveX and null data patterns are supported currently!

Control format how coordinate data is stored internally.

Defaults to Float64Array. Valid values include:

• Float64Array
• Float32Array
• Uint32Array
• Int32Array
• Int16Array
• Int8Array

See TypedArrayConstructor for all valid options.

This can be used to optimize memory usage if data doesn't need full 64 bit precision.

 // Example, store data as 32 bit floats to use less memory.
 const dataSet = new DataSetXY({ dataStorage: Float32Array })

 // Example, works same way if using series API directly instead of via DataSetXY
 const series = ChartXY.addPointLineAreaSeries({ dataStorage: Float32Array })

If true, the DataSetXY should allocate for user supplied ID property to be included for every sample. This can be used together for a few distinct purposes:

• alterSamplesByID - alter sample values after they have been added.
• readBack - readback sample values. In some use cases, you may have extra data properties which the application has to operate with. The ID property allows users to connect samples from data sets to the original application data which may have extra properties.
• SeriesXYFormatterNew - cursor result table formatter. Similarly, like readback you may use the ID property to show additional, external information in the result table.

Defaults to false.

 // Example, enable sample IDs
 const dataSet = new DataSetXY({ ids: true })

 // Example, works same way if using series API directly instead of via DataSetXY
 const series = ChartXY.addPointLineAreaSeries({ ids: true })

The above example simply enables the storage of ID values. The actual ID values must be supplied by the user, like this:

 // Example 1
 DataSetXY.appendSamples({
     yValues: [0, 1],
     ids: [0, 1],
 })

 // Example 2
 DataSetXY.appendSample({ x: 0, y: 0, id: 0 })

ID values are Uint32 numbers, so they are valid in range [0, 4_294_967_295].

Optional flag that can be used to inform that data set will not include NaN values. By default, it is assumed that the data provided might include NaN values. This results in extra processing to properly handle NaN values.

In case where you know that your data points will NOT include NaN values, you can set this to false for slight performance increase.

 const series = ChartXY.addPointLineAreaSeries({ includesNaN: false })

If true, the DataSetXY should allocate for Lookup value property to be included for every sample. Lookup value is a number which can be used to dynamically adjust data visualization coloring per-data point with an associated lookup table LUT. Usually this requires using a PalettedFill

Lookup values are always stored as Float32's.

Defaults to false.

 // Example, enable lookup values
 const dataSet = new DataSetXY({ lookupValues: true })

 // Example, works same way if using series API directly instead of via DataSetXY
 const series = ChartXY.addPointLineAreaSeries({ lookupValues: true })

Using lookup values for dynamic coloring is a 3-step process:

1. Enable lookup values in DataSetXY or Series (see documentation above).
2. Use a PalettedFill style with lookup property set to 'value':

 // Example
 PointLineAreaSeries.setPointFillStyle(new PalettedFill({
     lookUpProperty: 'value',
     lut: new LUT({
         interpolate: true,
         steps: [
             { value: 0, color: ColorRGBA(255, 0, 0) },
             { value: 100, color: ColorRGBA(0, 255, 0) },
         ]
     })
 }))

3. Supply lookup values along with your data. The syntax can vary based on which method you are using to supply data, but the general idea is the same:

 // Example 1
 DataSetXY.appendSamples({
     yValues: [0, 1],
     lookupValues: [0, 100],
 })

 // Example 2
 DataSetXY.appendSample({ x: 0, y: 0, lookupValue: 100 })

Lookup values are 32 bit floats.

If true, the DataSetXY should allocate for user supplied, individual point rotation properties. This means that "points" (present in PointLineAreaSeries) can have individual rotations, rather than each point having same rotation.

Defaults to false.

 // Example, enable individual point rotations
 const dataSet = new DataSetXY({ rotations: true })

 // Example, works same way if using series API directly instead of via DataSetXY
 const series = ChartXY.addPointLineAreaSeries({ rotations: true })

The above example simply enables the storage of rotation values. The actual rotation values must be supplied by the user, like this:

 // Example 1
 DataSetXY.appendSamples({
     yValues: [0, 1],
     rotations: [45, 90],
 })

 // Example 2
 DataSetXY.appendSample({ x: 0, y: 0, rotation: 45 })

When using individual point rotations, the setPointRotation configuration does not do anything.

Point rotations are defined as DEGREES.

If true, the DataSetXY should allocate for user supplied, individual point size properties. This means that "points" (present in PointLineAreaSeries) can have individual sizes, rather than each point having same size.

Defaults to false.

 // Example, enable individual point sizes
 const dataSet = new DataSetXY({ sizes: true })

 // Example, works same way if using series API directly instead of via DataSetXY
 const series = ChartXY.addPointLineAreaSeries({ sizes: true })

The above example simply enables the storage of size values. The actual size values must be supplied by the user, like this:

 // Example 1
 DataSetXY.appendSamples({
     yValues: [0, 1],
     sizes: [5, 10],
 })

 // Example 2
 DataSetXY.appendSample({ x: 0, y: 0, size: 5 })

When using individual point sizes, the setPointSize configuration does not do anything.

Point size values are pixels.