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.
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:
- append(TX x, TY y)
- append(TX[] xValues, TY[] yValues)
- append(IValues<TX> xValues, IValues<TY> yValues)
- append(Iterable<TX> xValues, Iterable<TY> yValues)
- insert(int index, TX x, TY y)
- insertRange(int startIndex, TX[] xValues, TY[] yValues)
- insertRange(int startIndex, IValues<TX> xValues, IValues<TY> yValues)
- insertRange(int startIndex, Iterable<TX> xValues, Iterable<TY> yValues)
- updateRangeXAt(int index, TX[] xValues)
- updateRangeXAt(int index, IValues<TX> xValues)
- updateRangeXAt(int index, Iterable<TX> xValues)
- updateRangeXyAt(int index, TX[] xValues, TY[] yValues)
- updateRangeXyAt(int index, IValues<TX> xValues, IValues<TY> yValues)
- updateRangeXyAt(int index, Iterable<TX> xValues, Iterable<TY> yValues)
- updateRangeYAt(int index, TY[] yValues)
- updateRangeYAt(int index, IValues<TY> yValues)
- updateRangeYAt(int index, Iterable<TY> yValues)
- updateXAt(int index, TX x)
- updateXyAt(int index, TX x, TY y)
- updateYAt(int index, TY y)
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.:
- IXDataSeriesValues<TX,TY> - provides an access to the
xValues
. - IXyDataSeriesValues<TX,TY> - provides an access to the
yValues
(in addition toxValues
).
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);