SciChart.js features a proprietary DataSeries API, which internally uses the fastest possible data-structures to allow fast manipulation of data bound to charts.

Our DataSeries are highly optimized data-structures for indexing, searching and iterating over data, enabling SciChart to achieve its record performance!

DataSeries Types

The following DataSeries types exist in SciChart.js. All DataSeries types store memory in WebAssembly and implement the IDeletable interface. You must call IDeletable.delete() when discarding a DataSeries to free memory.

Internally the DataSeries wrap the JavaScript number type, which is a double-precision 64-bit floating-point number and expect numeric values. You can also store Dates and render strings on chart axis, more on that below.

Creating, Assigning a DataSeries

A DataSeries can be created with a single line of code, once you have a wasmContext (WebAssembly Context). The WebAssembly Context is created when you call the SciChartSurface.create() function, and the context should be used for elements on that chart only.

// Assuming you have a wasmContext
const { wasmContext, sciChartSurface } = await SciChartSurface.create(divElementId);

// Create a DataSeries
const xyDataSeries = new XyDataSeries(wasmContext, {
        // Optional: pass X,Y values to DataSeries constructor for fast initialization
        xValues: [0,1,2,3,4],
        yValues: [10,11,12,13,14]
});

Once the DataSeries has been created, it can be assigned to a RenderableSeries by setting the BaseRenderableSeries.dataSeries property. More info on this in the section on RenderableSeries.

import {SciChartSurface} from "scichart/Charting/Visuals/SciChartSurface";
import {XyDataSeries} from "scichart/Charting/Model/XyDataSeries";
import {FastLineRenderableSeries} from "scichart/Charting/Visuals/RenderableSeries/FastLineRenderableSeries";

// Create a DataSeries
const xyDataSeries = new XyDataSeries(wasmContext, {
        // Optional: pass X,Y values to DataSeries constructor for fast initialization
        xValues: [0,1,2,3,4],
        yValues: [10,11,12,13,14]
});

// Create a renderableSeries and assign the dataSeries
const lineSeries = new FastLineRenderableSeries(wasmContext);
lineSeries.dataSeries = xyDataSeries;

sciChartSurface.renderableSeries.add(lineSeries);

With a DataSeries assigned, you can now manipulate the data on the series, and the chart will dynamically and automatically update. More on this below.

Setting Data Distribution Flags

For optimal drawing and correct operation, SciChart.js needs to know the distribution of your data, whether sorted in the x-direction and whether the data contains NaN (Not a Number). These flags will be computed automatically, but can be specified for improved performance.

Read more about specifying Data Distribution flags on the Data Resampling page.

Deleting a DataSeries

Once you are finished with the DataSeries, don't forget to call IDeletable.delete(). This frees WebAssembly native memory and releases it back to the operating system:

// Calling delete on a DataSeries releases its webassembly memory. This series is no longer usable
xyDataSeries.delete();

// Calling delete on a RenderableSeries will delete both the RenderableSeries and its dataseries.
// This series is no longer usable
const lineSeries = new FastLineRenderableSeries(wasmContext);
lineSeries.delete();

// Calling delete on a SciChartSurface will delete and free memory on all elements in this chart
// This chart is no longer usable.
const { wasmContext, sciChartSurface } = await SciChartSurface.create(divElementId);
sciChartSurface.delete();

Manipulating DataSeries Data for Dynamic Updates

All DataSeries types include Append, Insert, Update, Remove functions. There are also variations such as AppendRange, InsertRange etc... which accept an array of data:

const xyDataSeries = new XyDataSeries(wasmContext);
xyDataSeries.append(1, 10); // Appends X=1, Y=10
xyDataSeries.append(2, 20); // Appends X=2, Y=20
xyDataSeries.appendRange([3, 4, 5], [30, 40, 50]); // Appends X=3,4,5 and Y=30,40,50
xyDataSeries.removeAt(0); // removes the 0th xy point
xyDataSeries.removeRange(0, 2); // Removes 2 points from index 0 onwards
xyDataSeries.insert(0, 100, 200); // Inserts X=100, Y=200 at index 0
//xyDataSeries.insertRange(...)
xyDataSeries.update(0, 22); // Updates the Y-value at index 0
xyDataSeries.clear(); // Clears the dataseries. NOTE: Does not free memory
xyDataSeries.delete(); // Deletes WebAssembly memory. The series is no longer usable.

Accessing Values from the DataSeries

You can access values on a DataSeries by getting the internal WebAssembly native arrays via getNativeXValues() and getNativeYValues().

const xyDataSeries = new XyDataSeries(wasmContext);
xyDataSeries.appendRange([1,2,3], [10,20,30]);
const xValues = xyDataSeries.getNativeXValues();
const yValues = xyDataSeries.getNativeYValues();
for(let i = 0; i < xyDataSeries.count(); i++) {
    console.log(`i=${i}, xy = ${xValues.get(i)},${yValues.get(i)}`);
}

// Will output to console
// i=0, xy=1,10
// i=1, xy=2,20
// i=2, xy=3,30

Getting the DataSeries XRange and YRange

All DataSeries types expose the XRange and YRange (via getWindowedYRange) of the underlying series. If you need to know the min and max of the DataSeries in the X or Y direction, then call one of these properties:

const xyDataSeries = new XyDataSeries(webAssemblyContext);
xyDataSeries.appendRange([1, 2, 3], [10, 20, 30]);

// XRange will choose the first/last value if isSorted=true, else it will iterate over all values
const xRange = xyDataSeries.xRange; // Type NumberRange
console.log(`XRange: ${xRange.toString()}`);
// yRange requires a window of x-values. To get the entire yRange, pass in xRange
const yRange = xyDataSeries.getWindowedYRange(xRange, true, false);
console.log(`YRange: ${yRange.toString()}`);

// Outputs to console
// XRange: NumberRange (1, 3)
// YRange: NumberRange (10, 30)

Storing Date & String values in DataSeries

All DataSeries store 64-bit double precision numeric values. However, if you want to display a date or a string on an axis, you need to do a small conversion first.

Storing Dates on DataSeries in SciChart

DataSeries don't support dates, but you can store values as a unix timestamp and render them as a date on the axis. The process is:

1. Store Dates as Unix timestamps in the DataSeries.
2. Format the Date using our built-in LabelProvider, or create your own

Examples can be found in the SciChart.js examples suite, or in our documentation on the Label Formatting page.

Storing Strings in DataSeries in SciChart

Similarly, DataSeries don't support strings, but if you want to render strings, then it's advisable to use X values as sequential integers e.g. 0,1,2,3... and use the LabelProvider feature to format labels as strings.