Adding data

With the new XY features, the main ways of adding data are: appendSamples and appendSample methods. These respectively either add an Array of samples, or just 1 sample.

It's worth noting that while previously it was very bad to add many samples in short succession one at a time, this performs significantly better with the new appendSample method. It is still more performant to push all samples in at once, but sometimes it is impractical to do so.

Here's the basic syntax of adding samples:

PointLineAreaSeries.appendSamples({
    xValues: [0, 1, 2, 3],
    yValues: [10, 12, 15, 13]
})

Before, the main method of adding data was to feed JavaScript objects ({ x: number, y: number }). This is also still possible, and more performant than before by using appendJSON.

Now, the different channels of data (X, Y, ...) are added as separate Arrays. These Arrays can also be Typed arrays (Float32Array, Float64Array), which is very common when the data originates from a real-time transfer protocol, like WebSocket.

Only Y data or vice versa

If your use case uses a shifting index on either X or Y dimension (so coordinates just count 0, 1, 2, ...), you can omit either xValues or yValues, like this:

PointLineAreaSeries.appendSamples({
    // xValues will automatically start counting from last X (defaults to 0), with step 1.
    yValues: [10, 12, 15, 13]
})

You can also specify a start and step value for this:

PointLineAreaSeries.appendSamples({
    yValues: [10, 12, 15, 13],
    start: 1000,
    step: 10,
    // xValues -> [1000, 1010, 1020, 1030]
})

Max sample count

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.

If you forget to do this, there is a console warning which will remind you.

Using offsets

A new interesting feature with the XY features rewamp is offsets when dealing with data. What this lets you do is share a large data array which may contain some old data that you already have in your chart, and then some new data which you have previously pushed to this application side data array, and now want to also put to the charts.

By using offsets, you can tell the charts to append new samples by only from a specific range of a larger data array:

const allData = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
PointLineAreaSeries.appendSamples({
    yValues: allData,
    offset: 5,
    count: 3,
    // Will append [5, 6, 7]
})

This is very situational, but can yield some great performance benefits especially in applications where you also need an application side data context, with some parts of it being duplicated over in the charts.