Custom Filters

Demonstrates simple and advanced Custom Filters, with realtime updates using SciChart.js, High Performance JavaScript Charts

src/drawExample.ts
import { appTheme } from "./appTheme";

import {
    BaseDataSeries,
    NumericAxis,
    EAutoRange,
    EAxisAlignment,
    ELabelAlignment,
    FastColumnRenderableSeries,
    FastLineRenderableSeries,
    EllipsePointMarker,
    LegendModifier,
    NumberRange,
    SciChartSurface,
    XyCustomFilter,
    XyDataSeries,
    XyFilterBase,
    XyScatterRenderableSeries,
} from "scichart";

// A custom filter which calculates the frequency distribution of the original data
class AggregationFilter extends XyFilterBase {
    private bins: Map<number, number> = new Map<number, number>();
    private binWidthProperty = 1;

    constructor(originalSeries: BaseDataSeries, binWidth: number, dataSeriesName: string) {
        super(originalSeries, { dataSeriesName });
        this.binWidthProperty = binWidth;
        this.filterAll();
    }

    public get binWidth() {
        return this.binWidthProperty;
    }

    public set binWidth(value: number) {
        this.binWidthProperty = value;
        this.filterAll();
    }

    protected filterAll() {
        this.clear();
        this.bins.clear();
        this.filter(0, this.getOriginalCount());
    }

    protected override filterOnAppend(count: number): void {
        // Overriding this so we do not have to reprocess the entire series on append
        this.filter(this.getOriginalCount() - count, count);
    }

    protected filter(start: number, count: number): void {
        const numUtil = this.originalSeries.webAssemblyContext.NumberUtil;
        for (let i = start; i < start + count; i++) {
            const bin = numUtil.RoundDown(this.getOriginalYValues().get(i), this.binWidth);
            if (this.bins.has(bin)) {
                const newVal = this.bins.get(bin) + 1;
                this.bins.set(bin, newVal);
            } else {
                this.bins.set(bin, 1);
            }
        }
        // Map data is unsorted, so we must sort it before recreating the output series
        const keys = Array.from(this.bins.keys()).sort((a, b) => a - b);
        this.clear();
        const yValues: number[] = [];
        for (const key of keys) {
            yValues.push(this.bins.get(key));
        }
        this.appendRange(keys, yValues);
    }

    protected override onClear() {
        this.clear();
        this.bins.clear();
    }
}

let lastX = 0;
// Straight line data
const getData = (n: number) => {
    const xValues: number[] = [];
    const yValues: number[] = [];
    for (let i = 0; i < n; i++) {
        xValues.push(lastX);
        yValues.push(50 + lastX / 1000);
        lastX++;
    }
    return { xValues, yValues };
};

export const drawExample = async (rootElement: string | HTMLDivElement) => {
    // Define some constants
    const numberOfPointsPerTimerTick = 500; // 1,000 points every timer tick
    const timerInterval = 10; // timer tick every 10 milliseconds
    const maxPoints = 100_000; // max points for a single series before the demo stops

    const { sciChartSurface, wasmContext } = await SciChartSurface.create(rootElement, {
        theme: appTheme.SciChartJsTheme,
    });
    const rawXAxis = new NumericAxis(wasmContext, { id: "rawX", isVisible: false, autoRange: EAutoRange.Always });
    const aggXAxis = new NumericAxis(wasmContext, {
        id: "aggX",
        axisTitle: "Value",
        autoRange: EAutoRange.Always,
        labelPrecision: 0,
    });
    sciChartSurface.xAxes.add(rawXAxis, aggXAxis);

    const rawYAxis = new NumericAxis(wasmContext, {
        autoRange: EAutoRange.Always,
        axisTitle: "Raw Data",
        id: "rawY",
        labelPrecision: 0,
        labelStyle: { alignment: ELabelAlignment.Right },
    });
    const aggYAxis = new NumericAxis(wasmContext, {
        axisTitle: "Frequency (Aggregated)",
        id: "aggY",
        autoRange: EAutoRange.Always,
        axisAlignment: EAxisAlignment.Left,
        growBy: new NumberRange(0, 0.5),
        labelPrecision: 0,
    });
    sciChartSurface.yAxes.add(aggYAxis, rawYAxis);

    const dataSeries = new XyDataSeries(wasmContext, { dataSeriesName: "Original Data" });

    // Create a simple custom filter.  We just have to specify the filter function and this will be applied efficiently to data changes
    const gaussFilter = new XyCustomFilter(dataSeries, { dataSeriesName: "Custom Filter: Original x Gaussian Random" });
    // This function exploits the central limit theorem to approximate a normal distribution
    const gaussianRand = () => {
        let rand = 0;
        for (let i = 0; i < 6; i += 1) {
            rand += Math.random() + 0.5;
        }
        return rand / 6;
    };
    gaussFilter.filterFunction = (i, y) => y * gaussianRand();

    // Add the randomised data using a custom filter which takes original data * random value
    sciChartSurface.renderableSeries.add(
        new XyScatterRenderableSeries(wasmContext, {
            pointMarker: new EllipsePointMarker(wasmContext, {
                width: 3,
                height: 3,
                strokeThickness: 0,
                fill: appTheme.VividOrange,
                opacity: 0.77,
            }),
            stroke: appTheme.VividOrange,
            dataSeries: gaussFilter,
            xAxisId: "rawX",
            yAxisId: "rawY",
        })
    );

    // Add the original data to the chart
    sciChartSurface.renderableSeries.add(
        new FastLineRenderableSeries(wasmContext, {
            dataSeries,
            stroke: appTheme.VividTeal,
            strokeThickness: 3,
            xAxisId: "rawX",
            yAxisId: "rawY",
        })
    );

    // Pass the randomised data into the aggregation filter.
    const aggFilter = new AggregationFilter(gaussFilter, 5, "Custom Filter: Aggregation");

    // Plot the aggregation filter as a column chart
    sciChartSurface.renderableSeries.add(
        new FastColumnRenderableSeries(wasmContext, {
            id: "col",
            fill: appTheme.VividSkyBlue + "33",
            stroke: appTheme.MutedSkyBlue,
            dataSeries: aggFilter,
            xAxisId: "aggX",
            yAxisId: "aggY",
            cornerRadius: 10,
        })
    );

    let timerId: NodeJS.Timeout;

    // Function called when the user clicks stopUpdate button
    const stopUpdate = () => {
        clearTimeout(timerId);
        timerId = undefined;
        lastX = 0;
    };

    // Function called when the user clicks startUpdate button
    const startUpdate = () => {
        if (timerId) {
            stopUpdate();
            dataSeries.clear();
        }
        const updateFunc = () => {
            if (dataSeries.count() >= maxPoints) {
                stopUpdate();
                return;
            }

            // Get the next N random walk x,y values
            const { xValues, yValues } = getData(numberOfPointsPerTimerTick);
            // Append these to the dataSeries. This will cause the chart to redraw
            dataSeries.appendRange(xValues, yValues);

            timerId = setTimeout(updateFunc, timerInterval);
        };

        dataSeries.clear();

        timerId = setTimeout(updateFunc, timerInterval);
    };

    sciChartSurface.chartModifiers.add(new LegendModifier());

    return { wasmContext, sciChartSurface, controls: { startUpdate, stopUpdate } };
};

Custom Filters - JavaScript

Overview

This example demonstrates advanced custom filters within the SciChart.js library using JavaScript. The implementation showcases real-time data transformations by applying a Gaussian randomization filter and a bespoke aggregation filter that extends the XyFilterBase class to compute frequency distributions.

Technical Implementation

The custom filtering mechanism is implemented by subclassing XyFilterBase to create an aggregation filter, and by applying a transformation function via XyCustomFilter that utilizes a Gaussian random function. Real-time updates are executed using a timer-based approach with setTimeout, as detailed in the Adding Realtime Updates guide. The example also leverages WebAssembly acceleration for high-frequency data processing, a key aspect for performance optimization as described in the Performance Tips & Tricks.

Features and Capabilities

Key features include real-time updates with efficient batch data appending and advanced data transformation techniques. The Gaussian randomization modifies the incoming data series before it is aggregated, while the custom aggregation filter bins the data to produce a frequency distribution. This dual filtering approach enables developers to visualize both raw and processed data concurrently, ensuring a high level of interactivity and responsiveness.

Integration and Best Practices

Focusing solely on JavaScript, the example adheres to robust object-oriented design patterns by extending base filtering classes without relying on framework-specific hooks or builder APIs. The implementation follows best practices outlined in the SciChart.js JavaScript Charts User Manual to build high-performance, real-time charting applications. Developers are encouraged to explore these techniques further to optimize large-scale data visualization solutions.