SciChart.js JavaScript 2D Charts API > DataSeries API > The DataSeries API
The DataSeries API

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!

Note: A full list of available DataSeries, their public API / functions and TypeDoc documentation with description of each function can be found over at our TypeDoc page.

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.

DataSeries type Series Applicable

XyDataseries

Stores X,Y Data

FastLineRenderableSeriesFastMountainRenderableSeries
XyScatterRenderableSeriesFastColumnRenderableSeries

XyyDataSeries

Stores X,Y1,Y2 data

FastBandRenderableSeries (required). 

Can also apply to FastLineRenderableSeriesFastMountainRenderableSeries
XyScatterRenderableSeriesFastColumnRenderableSeries. In this case only the X,Y1 value is chosen

XyzDataSeries

Stores X,Y,Z data

FastBubbleRenderableSeries (required).

Can also apply to FastLineRenderableSeriesFastMountainRenderableSeriesXyScatterRenderableSeries
FastColumnRenderableSeries.
In this case only the X,Y value is chosen

OhlcDataseries

Stores X, Open, High, Low, Close data

FastCandlestickRenderableSeries or FastOhlcRenderableSeries (required)

Can also apply to FastLineRenderableSeriesFastMountainRenderableSeriesXyScatterRenderableSeries
FastColumnRenderableSeries.
In this case only the X,Y (Close) value is chosen

UniformHeatmapDataSeries

Stores Z-values as 2-dimensional array numbers. The Y,X positions of heatmap cells are computed from the Start and Step values

UniformHeatmapRenderableSeries (required)

This DataSeries type is not applicable to any other RenderableSeries

 

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.

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

// Create a DataSeries
const xyDataSeries = new XyDataSeries(wasmContext);

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.

Assigning a DataSeries to a RenderableSeries
Copy Code
// Create a DataSeries
const xyDataSeries = new XyDataSeries(wasmContext);

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

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:

Deleting a DataSeries
Copy Code
// 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();
Failing to call IDeletable.delete() on a DataSeries when it is no longer needed can result in a memory leak.

Manipulating DataSeries Data for Dynamic Updates

All DataSeries types include AppendInsertUpdateRemove functions. There are also variations such as AppendRangeInsertRange etc... which accept an array of data:

Append, Update, Insert, Remove
Copy Code
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.
Note: For the best possible performance, when modifying large datasets, use the appendRangeinsertRangeremoveRange functions. These accept an array of values and are considerably faster than appending point-by-point.
Failing to call IDeletable.delete() on a DataSeries when it is no longer needed can result in a memory leak.

Telling SciChart the Data Distribution

For the best performance internally, the DataSeries need to know if your data is sorted ascending in X by setting the isSorted property. By default this property is true.

If you are dealing with X-Y scatter data which is not increasing in X, then set the flag dataSeries.isSorted = false, otherwise you can get incorrect rendering. Likewise, setting isSorted = true when the data is unsorted will result in poorer performance.

Setting the isSorted flag
Copy Code
const xyDataSeries = new XyDataSeries(wasmContext);
xyDataSeries.isSorted = false;

Accessing Values from the DataSeries

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

Accessing Values from DataSeries
Copy Code
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
Note: point by point access to the DataSeries native values is slow when you're dealing with millions of points.

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:

Example Title
Copy Code
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.