DataSeries Types in SciChart

SciChart 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!

The following DataSeries types exist in SciChart Android.

Note

Allowable types in SciChart include Date, double, float, long, int, short, byte.

Data Series Type Series Applicable
XyDataSeries<TX,TY> - stores X and Y Data FastLineRenderableSeries, FastMountainRenderableSeries, XyScatterRenderableSeries, FastColumnRenderableSeries, FastImpulseRenderableSeries and FastFixedErrorBarsRenderableSeries
XyyDataSeries<TX,TY> - stores X, Y and Y1 Data FastBandRenderableSeries (required). Can also apply to FastLineRenderableSeries, FastMountainRenderableSeries, XyScatterRenderableSeries, FastColumnRenderableSeries, FastImpulseRenderableSeries and FastFixedErrorBarsRenderableSeries. In this case only the X and Y value are chosen
XyzDataSeries<TX,TY,TZ> - stores X, Y and Z Data FastBubbleRenderableSeries (required). Can also apply to FastLineRenderableSeries, FastMountainRenderableSeries, XyScatterRenderableSeries, FastColumnRenderableSeries, FastImpulseRenderableSeries and FastFixedErrorBarsRenderableSeries. In this case only the X and Z value are chosen
HlDataSeries<TX,TY> - stores X, Y, High and Low Data FastErrorBarsRenderableSeries (required). Can also apply to FastLineRenderableSeries, FastMountainRenderableSeries, XyScatterRenderableSeries, FastColumnRenderableSeries, FastImpulseRenderableSeries and FastFixedErrorBarsRenderableSeries. In this case only the X and Y values are chosen
OhlcDataSeries<TX,TY> - stores X, Open, High, Low and Close Data FastCandlestickRenderableSeries or FastOhlcRenderableSeries (required). Can also apply to FastLineRenderableSeries, FastMountainRenderableSeries, XyScatterRenderableSeries, FastColumnRenderableSeries, FastImpulseRenderableSeries and FastFixedErrorBarsRenderableSeries. In this case only the X and Close values are chosen
UniformHeatmapDataSeries<TX,TY,TZ> - stores TY values as array of TY, and TX, TZ values are computed from cell index, Start and Step values FastUniformHeatmapRenderableSeries (required). This DataSeries type is not applicable to any other RenderableSeries

Manipulating DataSeries Data

Data in IDataSeries<TX,TY> may be manipulated using the Append, Insert, Update, Remove functions.

In addition, xRange and yRange may be accessed as well as any of the underlying data may be directly accessed.

Also, DataSeries feature two modes: standard and FIFO (First in first out). In FIFO mode data may be streamed and old data-points discarded as new arrive.

Finally, you can control Data Distribution using IDataDistributionCalculator<TX>.

The following sections show how you can manipulate data in the DataSeries types in SciChart.

Append, Insert, Update, Remove

All DataSeries types include Append, Insert, Update, Remove methods. Many of these also have overloads which accept a range of data, e.g. the IXyDataSeries<TX,TY> protocol has the following:

Other DataSeries have similar methods appropriate to underlying data which they hold.

Note

It is highly recommended to use set of methods, which works with our IValues<T> data-structures, to achieve better performance and omit boxing/unboxing into Cocoa native types.

X and Y Ranges

All DataSeries types expose the XRange and YRange of the underlying DataSeries as well as corresponding Max and Min values. See the following methods:

Note

These perform a calculation every time the property is accessed, so should be used sparingly.

final IXyDataSeries<Double, Double> dataSeries = new XyDataSeries<>(Double.class, Double.class);
// Append some data here
IRange xRange = dataSeries.getXRange();
IRange yRange = dataSeries.getYRange();
// You can access Min/Max directly as Double
double min = xRange.getMinAsDouble();
double max = xRange.getMaxAsDouble();

Accessing X, Y, [other] Values

All DataSeries types expose the lists of underlying data. There is a set of protocols, which provides an access for the underlying data, which names has a pattern as follows: I[Something]DataSeriesValues, e.g.:

Those are read-only ISciList<T>s. Data can be accessed by casting to the underlying list type, e.g. ISciListDouble.

final IXyDataSeries<Double, Double> dataSeries = new XyDataSeries<>(Double.class, Double.class);
ISciList<Double> xValues = dataSeries.getXValues();

// You can cast each value separately
double value = xValues.getDoubleValue(0);

Fifo (First-In-First-Out) DataSeries

DataSeries allow First-In-First-Out behaviour, where a maximum capacity is set, once reached, old data-points are discarded. To declare a Fifo dataseries, simply set the fifoCapacity property.

final IXyDataSeries<Double, Double> dataSeries = new XyDataSeries<>(Double.class, Double.class);
dataSeries.setFifoCapacity(1000);

Considering the code above, the behaviour will be the following. Once the 1001-st point have been added, the very first point will be discarded. Appending another 5 points, the next oldest 5 points will be discarded. The window continues to scroll no matter how many points are appended and memory never increases beyond 1000 points.

Fifo DataSeries are a very memory and CPU efficient way of scrolling and discarding old data and creating scrolling, streaming charts.

DataSeries Data Distribution

The IDataDistributionCalculator<TX> is a protocol which determines the distribution of your data (sorted in X or not, evenly spaced in X or not) and the flags are used to determine the correct algorithm(s) for resampling, hit-testing and indexing of data.

By default, this all works automatically, however, if you want to save a few CPU cycles and you know in advance the distribution of your data, you can override the flags as follows:

final UserDefinedDistributionCalculator dataDistributionCalculator = new UserDefinedDistributionCalculator();
dataDistributionCalculator.setDataSortedAscending(true);
dataDistributionCalculator.setDataEvenlySpaced(true);

final IXyDataSeries<Double, Double> dataSeries = new XyDataSeries<>(Double.class, Double.class, dataDistributionCalculator);

DataSeries AcceptsUnsortedData

By default, DataSeries are designed to throw an exception if data is appended unsorted in X. This is because unsorted data is detrimental to performance, and many people were unintentionally appending data unsorted in the X-direction.

SciChart can however accept unsorted data, you just need to specify the flag acceptsUnsortedData = true. This will signal to SciChart that your appending of unsorted data was intentional and the chart will then draw it.

final IXyDataSeries<Double, Double> dataSeries = new XyDataSeries<>(Double.class, Double.class);
dataSeries.setAcceptsUnsortedData(true);