stream-charts 1.0.0 → 1.1.0

package/src/app/charts/plots/plot.ts

@@ -0,0 +1,75 @@
+import {Dimensions} from "../styling/margins";
+import * as d3 from "d3";
+import {GSelection} from "../d3types";
+
+export type Series<D> = Array<D>
+
+/**
+ * Creates the main SVG for holding the plot.
+ * @param chartId A unique value identifying the chart.
+ * @param container The SVG element interface
+ * @param plotDimensions The dimensions of the plot
+ * @param color The SVG `color` attribute used for the axis
+ */
+export function createPlotContainer(
+    chartId: number,
+    container: SVGSVGElement,
+    plotDimensions: Dimensions,
+    color: string
+): GSelection {
+    const {width, height} = plotDimensions
+    return d3.select<SVGSVGElement, any>(container)
+        .attr('width', Math.max(0, width))
+        .attr('height', Math.max(0, height))
+        .attr('color', color)
+        .append<SVGGElement>('g')
+        .attr('id', `main-container-${chartId}`)
+}
+
+/**
+ * Adds a clip area for the chart to the specified SVG element. The clip-area is given
+ * an `id` of `clip-series-<chart_id>`, which because the chart ID should be unique, makes
+ * this unique as well.
+ * @param chartId The ID of the chart to which the clip area is to be added.
+ * @param plotGroup The SVG group element to which the clip area is to be added.
+ * @param plotDimensions The dimensions of the plot.
+ * @return The ID of the clip-path.
+ */
+export function setClipPathG(chartId: number, plotGroup: GSelection, plotDimensions: Dimensions): string {
+    const clipPathId = `chart-clip-path-${chartId}`
+
+    // remove the old clipping region and add a new one with the updated plot dimensions
+    plotGroup.select(`#${clipPathId}-defs`).remove();
+    plotGroup
+        .append('defs')
+            .attr('id', `${clipPathId}-defs`)
+        .append("clipPath")
+            .attr("id", clipPathId)
+        .append("rect")
+            .attr("x", 0)
+            .attr("y", 0)
+            .attr("width", Math.max(0, plotDimensions.width))
+            .attr("height", Math.max(0, plotDimensions.height))
+
+    return clipPathId
+}
+
+/**
+ * Represents the assignment of an x-axis and y-axis to a series. Plots (see, for example,
+ * {@link ScatterPlot} and {@link RasterPlot}) use this interface to manage the assignment
+ * of axes to series
+ */
+export interface AxesAssignment {
+    xAxis: string
+    yAxis: string
+}
+
+/**
+ * Factory function for the assignment of axes to series
+ * @param xAxis The ID of the x-axis
+ * @param yAxis The ID of the y-axis
+ * @return An {@link AxesAssignment}
+ */
+export const assignAxes = (xAxis: string, yAxis: string): AxesAssignment => ({xAxis, yAxis})
+
+

package/src/app/charts/series/baseSeries.ts

@@ -0,0 +1,52 @@
+import {failureResult, Result, successResult} from "result-fn";
+
+/**
+ * A spike series holding an array of spike (time, value) datum, the name and supplemental information
+ * needed by the `RasterChart`
+ */
+export interface BaseSeries<D> {
+    readonly name: string;
+    data: Array<D>;
+    readonly last: () => Result<D, string>;
+    readonly length: () => number;
+    readonly isEmpty: () => boolean;
+}
+
+/**
+ * Creates a series from the name and the optional array of `Datum`.
+ * @param name The name of the series (i.e. neuron)
+ * @param data The array of datum, which could be `(t, f(t))`, or `(f[n](x), f[n+1](x))`
+ * @return A {@link BaseSeries} for object that can be used by in {@link Chart}s
+ * @see seriesFromTuples
+ * @see emptySeries
+ */
+export function seriesFrom<D>(name: string, data: Array<D> = []): BaseSeries<D> {
+    return {
+        name: name,
+        data: data,
+        last: () => data ? (data.length > 0 ? successResult<D, string>(data[data.length - 1]) : failureResult<D, string>("Data is empty")) : failureResult<D, string>("Data is not defined"),
+        length: () => data ? data.length : 0,
+        isEmpty: () => data ? data.length === 0 : true
+    }
+}
+
+/**
+ * Returns an empty series with the specified name
+ * @param name The name of the series
+ * @return The empty series
+ * @see seriesFrom
+ * @see seriesFromTuples
+ */
+export const emptySeries = <D>(name: string): BaseSeries<D> => seriesFrom(name);
+
+/**
+ * Creates an array of empty series, one for each specified name
+ * @param names The names for each of the empty series
+ * @return An array of empty series with the specified names
+ * @see emptySeries
+ * @see seriesFrom
+ * @see seriesFromTuples
+ */
+export const emptySeriesFor = <D>(names: Array<string>): Array<BaseSeries<D>> => names.map(name => seriesFrom(name))
+
+

package/src/app/charts/series/datumSeries.test.ts

@@ -0,0 +1,60 @@
+import {emptySeries, seriesFrom} from "./baseSeries";
+
+describe('should be able to create an empty series', () => {
+    test('an empty series should be empty', () => {
+        expect(emptySeries('test1').isEmpty());
+    });
+
+    test('an empty series should not have a last element', () => {
+        expect(emptySeries('test1').last().failed);
+    });
+
+    test('an empty series should have 0 length', () => {
+        expect(emptySeries('test1').length()).toBe(0);
+    });
+
+    test('an empty series should not have any data', () => {
+        expect(emptySeries('test1').data.length).toBe(0);
+    });
+
+    test('an empty series should have the specified name', () => {
+        expect(emptySeries('test1').name).toBe('test1');
+    });
+});
+
+describe('should be able to create a series from data', () => {
+    const data = [
+        {time: 1, value: 10},
+        {time: 2, value: 20},
+        {time: 3, value: 30},
+        {time: 4, value: 40},
+        {time: 5, value: 50},
+        {time: 6, value: 60},
+        {time: 7, value: 70},
+        {time: 8, value: 80},
+        {time: 9, value: 90},
+        {time: 10, value: 100},
+    ];
+    const series = seriesFrom('test2', data);
+
+    test('series should not be empty', () => {
+        expect(!series.isEmpty())
+    });
+
+    test('series name should be test2', () => {
+        expect(series.name).toEqual('test2')
+    });
+
+    test('series should have 10 points', () => {
+        expect(series.length()).toBe(10);
+    });
+
+    test('last value in series should be (10, 100)', () => {
+        const lastElement = series.last().getOrElse({time: NaN, value: NaN});
+        expect(lastElement).toEqual({time: 10, value: 100});
+    });
+
+    test('series data should equal original data', () => {
+        expect(series.data).toEqual(data);
+    });
+});

package/src/app/charts/series/iterateSeries.ts

@@ -0,0 +1,56 @@
+import {BaseSeries, seriesFrom} from "./baseSeries";
+
+/**
+ * An immutable datum object that holds the iterate `(f[n](x), f[n+1](x))` with an
+ * informational time
+ */
+export interface IterateDatum {
+    readonly time: number;
+    readonly iterateN: number;
+    readonly iterateN_1: number
+}
+
+/**
+ * Creates an empty iterate datum
+ */
+export const emptyIterateDatum: IterateDatum = {time: NaN, iterateN: NaN, iterateN_1: NaN}
+
+/**
+ * Creates an iterate datum
+ * @param time The informational time
+ * @param iterateN The n-th iterate (i.e. `f[n](x)`)
+ * @param iterateN_1 The (n+1)-th iterate (i.e. `f[n+1](x)`)
+ * @return An iterate datum
+ */
+export const iterateDatumOf = (time: number, iterateN: number, iterateN_1: number): IterateDatum => ({
+    time,
+    iterateN,
+    iterateN_1
+})
+
+/**
+ * Returns whether the iterate datum is considered empty. An iterate datum is considered
+ * empty when the time, `f[n](x)`, `f[n+1](x)` values are all `NaN`
+ * @param datum The iterate datum to test
+ * @return `true` if the iterate datum is empty; `false` otherwise
+ */
+export const nonEmptyIterateDatum = (datum: IterateDatum): boolean =>
+    !isNaN(datum.time) && !isNaN(datum.iterateN) && !isNaN(datum.iterateN_1)
+
+/**
+ * A series of iterate (i.e. `(f[n](x), f[n+1](x))` pairs)
+ */
+export type IterateSeries = BaseSeries<IterateDatum>
+
+/**
+ * Creates a series from the name and the optional array of (x, y) pairs (tuples)
+ * @param name The name of the series
+ * @param data The optional array of (x, y) pairs (tuples)
+ * @return A `Series` for object that can be used by the `PoincarePlot`
+ * @see seriesFrom
+ * @see emptySeries
+ */
+export const iterateSeriesFromTuples = (name: string, data: Array<[number, number, number]> = []): IterateSeries =>
+    seriesFrom(name, data.map(([t, fn, fn_1]) => iterateDatumOf(t, fn, fn_1)))
+
+

package/src/app/charts/series/ordinalSeries.ts

@@ -0,0 +1,164 @@
+import {BaseSeries, seriesFrom} from "./baseSeries";
+import {
+    initialMaxTimeDatum,
+    initialMaxValueDatum, initialMinTimeDatum,
+    initialMinValueDatum,
+    OrdinalChartData,
+    OrdinalStats,
+    OrdinalValueStats
+} from "../observables/ordinals";
+
+/**
+ * An immutable datum object for series with a category and value.
+ * This could be a series of (ordinal, value) where the category runs
+ * along the x-axis. Or, it could be a series of (value, ordinal) where
+ * the categories run along the y-axis.
+ */
+export interface OrdinalDatum {
+    readonly time: number
+    readonly ordinal: string
+    readonly value: number
+}
+
+
+/**
+ * Creates an empty ordinal datum
+ */
+export const emptyOrdinalDatum: OrdinalDatum = {
+    time: NaN,
+    ordinal: "",
+    value: NaN,
+}
+
+export const copyOrdinalDatum = (datum: OrdinalDatum): OrdinalDatum => ({
+    time: datum.time,
+    ordinal: datum.ordinal,
+    value: datum.value,
+})
+
+/**
+ * Creates an iterate datum
+ * @param time The datum time, which is mostly informational
+ * @param ordinal The category name or identifier
+ * @param value The value
+ * @return An iterate datum
+ */
+export const ordinalDatumOf = (time: number, ordinal: string, value: number): OrdinalDatum => ({
+    time,
+    ordinal,
+    value,
+})
+
+
+/**
+ * Returns whether the ordinal datum is empty. An ordinal datum is considered empty
+ * when the time is NaN, the ordinal is blank (empty or only whitespace), and the value
+ * is NaN.
+ * @param datum The iterate datum to test
+ * @return `true` if the iterate datum is empty; `false` otherwise
+ */
+export const nonEmptyOrdinalDatum = (datum: OrdinalDatum): boolean =>
+    !isNaN(datum.time) && datum.ordinal.replace(/\s/g, "").length > 0 && !isNaN(datum.value)
+
+/**
+ * A series of ordinal datum
+ */
+export type OrdinalSeries = BaseSeries<OrdinalDatum>
+
+/**
+ * Creates a series from the name and the optional array of (time, ordinal, value) tuples
+ * @param name The name of the series
+ * @param data The optional array of (time, ordinal, value) tuples
+ * @return An {@link OrdinalSeries} for charts where one axis is the category, and the other a value
+ * @see seriesFrom
+ * @see emptySeries
+ */
+export function ordinateSeriesFromTuples(
+    name: string,
+    data: Array<[time: number, ordinal: string, value: number]> = []
+): OrdinalSeries {
+    return seriesFrom(
+        name,
+        data.map(([t, ordinal, value]) => ordinalDatumOf(t, ordinal, value))
+    )
+}
+
+/**
+ * Creates an empty chart data object with all the values set to 0
+ * @param seriesList The list of series names (identifiers) to update
+ * @return An empty chart data object
+ */
+export function initialOrdinalChartData(seriesList: Array<OrdinalSeries>): OrdinalChartData {
+    return {
+        seriesNames: new Set(seriesList.map(series => series.name)),
+        stats: calculateOrdinalStats(seriesList),
+        newPoints: new Map<string, Array<OrdinalDatum>>(seriesList.map(series => [
+            series.name,
+            series.data.map(datum => ({
+                time: datum.time,
+                ordinal: datum.ordinal,
+                value: datum.value,
+            }))
+        ]))
+    }
+}
+
+export function calculateOrdinalStats(seriesList: Array<OrdinalSeries>): OrdinalStats {
+    const ordinalValueStats = new Map<string, OrdinalValueStats>(seriesList.map(
+        (series: OrdinalSeries) => {
+            const seriesMin = series.data.reduce(
+                (min, datum) => datum.value < min.value ? datum : min,
+                initialMinValueDatum()
+            )
+            const seriesMax = series.data.reduce(
+                (max, datum) => datum.value > max.value ? datum : max,
+                initialMaxValueDatum()
+            )
+            const seriesSum = series.data.reduce((sum, datum) => sum + datum.value, 0)
+            const seriesSumSquared = series.data.reduce((sumSquared, datum) => sumSquared + datum.value * datum.value, 0)
+            const seriesMean = series.data.length > 0 ? seriesSum / series.data.length : NaN
+            return [series.name, {
+                max: seriesMax,
+                min: seriesMin,
+                count: series.data.length,
+                sum: seriesSum,
+                sumSquared: seriesSumSquared,
+                mean: seriesMean,
+            }]
+        }
+    ))
+    const minValueDatum: OrdinalDatum = Array.from(ordinalValueStats.values()).reduce(
+        (min: OrdinalDatum, value: OrdinalValueStats) => value.min.value < min.value ? value.min : min,
+        initialMinValueDatum()
+    )
+    const maxValueDatum: OrdinalDatum = Array.from(ordinalValueStats.values()).reduce(
+        (max: OrdinalDatum, value: OrdinalValueStats) => value.max.value > max.value ? value.max : max,
+        initialMaxValueDatum()
+    )
+    const minTimeDatum: OrdinalDatum = seriesList.reduce(
+        (globalMin: OrdinalDatum, series: OrdinalSeries) => {
+            const seriesMin = series.data.reduce(
+                (min, datum) =>  datum.value < min.value ? datum : min,
+                globalMin
+            )
+            return seriesMin.value < globalMin.value ? seriesMin : globalMin
+        },
+        initialMinTimeDatum()
+    )
+    const maxTimeDatum: OrdinalDatum = seriesList.reduce(
+        (globalMax: OrdinalDatum, series: OrdinalSeries) => {
+            const seriesMax = series.data.reduce(
+                (max, datum) =>  datum.value > max.value ? datum : max,
+                globalMax
+            )
+            return seriesMax.value > globalMax.value ? seriesMax : globalMax
+        },
+        initialMaxTimeDatum()
+    )
+    return {
+        maxDatum: {time: maxTimeDatum, value: maxValueDatum},
+        minDatum: {time: minTimeDatum, value: minValueDatum},
+        valueStatsForSeries: ordinalValueStats
+    }
+}
+

package/src/app/charts/series/timeSeries.ts

@@ -0,0 +1,40 @@
+import {BaseSeries, seriesFrom} from "./baseSeries";
+
+/**
+ * An immutable datum object that holds the spike (time, value) representing a neuron spike
+ */
+export interface Datum {
+    readonly time: number;
+    readonly value: number;
+}
+
+/**
+ * Creates a datum from a (time, value) pair
+ * @param time The time
+ * @param value The value
+ * @return A {@link Datum} instance with the specified (time, value)
+ */
+export const datumOf = (time: number, value: number): Datum => ({time, value})
+
+export const emptyDatum = (): Datum => ({time: NaN, value: NaN})
+
+export type TimeSeries = BaseSeries<Datum>
+
+
+/**
+ * Creates a series from the name and the optional array of (x, y) pairs (tuples)
+ * @param name The name of the series
+ * @param data The optional array of (x, y) pairs (tuples)
+ * @return A `Series` for object that can be used by the `RasterChart`
+ * @see seriesFrom
+ * @see emptySeries
+ */
+export const timeSeriesFromTuples = (name: string, data: Array<[number, number]> = []): TimeSeries =>
+    seriesFrom(name, data.map(([t, y]) => datumOf(t, y)))
+
+export interface PixelDatum extends Datum {
+    x: number;
+    y: number;
+}
+
+

package/src/app/charts/series/timeSeriesChartData.ts

@@ -0,0 +1,68 @@
+import {Datum, TimeSeries} from "./timeSeries";
+import {ChartData, defaultChartData} from "../observables/ChartData";
+
+/**
+ * The spike-chart data produced by the rxjs observable that is pushed to a streaming chart
+ */
+export interface TimeSeriesChartData extends ChartData {
+    /**
+     * The max (latest) time for the data in the newPoints map
+     */
+    maxTime: number
+
+    /**
+     * Holds the association of the series name to the current max time for that series
+     */
+    maxTimes: Map<string, number>
+
+    /**
+     * Map holding the name of the series (the time-series identifier) and the associated
+     * data points for that time-series (`map(series_name -> array(datum))`)
+     */
+    newPoints: Map<string, Array<Datum>>
+
+    /**
+     * The current time (for example, when used with cadence)
+     */
+    currentTime?: number
+}
+
+/**
+ * Creates an empty chart data object with all the values set to 0
+ * @param {Array<string>} series The list of series names (identifiers) to update
+ * @return {TimeSeriesChartData} An empty chart data object
+ */
+export function emptyTimeSeriesChartData(series: Array<string>): TimeSeriesChartData {
+    return {
+        ...defaultChartData(),
+        maxTime: 0,
+        maxTimes: new Map(series.map(name => [name, 0])),
+        newPoints: new Map<string, Array<Datum>>(series.map(name => [name, [{time: 0, value: 0}]]))
+    }
+}
+
+/**
+ * Creates an empty chart data object with all the values set to 0
+ * @param seriesList The list of series names (identifiers) to update
+ * @param [currentTime=0] The current time
+ * @return An empty chart data object
+ */
+export function initialTimeSeriesChartData(seriesList: Array<TimeSeries>, currentTime: number = 0): TimeSeriesChartData {
+    const maxTime = seriesList.reduce(
+        (tMax, series) => Math.max(tMax, series.last().map(datum => datum.time).getOrElse(-Infinity)),
+        -Infinity
+    )
+    return {
+        seriesNames: new Set(seriesList.map(series => series.name)),
+        maxTime,
+        maxTimes: new Map(seriesList.map(series => [series.name, series.last().map(datum => datum.time).getOrElse(0)])),
+        newPoints: new Map<string, Array<Datum>>(seriesList.map(series => [
+            series.name,
+            [{
+                time: series.last().map(datum => datum.time).getOrElse(0),
+                value: series.last().map(datum => datum.value).getOrElse(0)
+            }]
+        ])),
+        currentTime: currentTime
+    }
+}

package/src/app/charts/styling/barPlotStyle.ts

@@ -0,0 +1,126 @@
+import {SeriesStyle} from "../axes/axes";
+import {SvgFillStyle, SvgStrokeStyle} from "./svgStyle";
+import * as d3 from "d3";
+
+export interface BarSeriesStyle extends SeriesStyle {
+    /**
+     * The bar style for the lifetime min/max range bar. The style is for the width, fill,
+     * and stroke.
+     */
+    minMaxBar: BarStyle
+    /**
+     * The bar style for the windowed min/max range bar. The style is for the width, fill,
+     * and stroke.
+     */
+    windowedMinMaxBar: BarStyle
+    /**
+     * The line style for the current value.
+     */
+    valueLine: LineStyle
+    /**
+     * The line style for the mean value.
+     */
+    meanValueLine: LineStyle
+    /**
+     * The line style for the windowed-mean value.
+     */
+    windowedMeanValueLine: LineStyle
+}
+
+export interface BarStyle {
+    widthFraction: number
+    fill: SvgFillStyle
+    stroke: SvgStrokeStyle
+}
+
+export interface LineStyle {
+    regular: SvgStrokeStyle
+    highlight: SvgStrokeStyle
+}
+
+export function defaultMinMaxBarStyle(color: string = "#008aad"): BarStyle {
+    return {
+        widthFraction: 0.65,
+        fill: {
+            color,
+            opacity: 0.4
+        },
+        stroke: {
+            width: 1,
+            opacity: 0.6,
+            color,
+        }
+    }
+}
+
+export function defaultWindowedMinMaxBarStyle(color: string = "#008aad"): BarStyle {
+    return {
+        widthFraction: 0.25,
+        fill: {
+            color: d3.color(color)?.darker(0.3).toString() ?? color,
+            opacity: 0.6
+        },
+        stroke: {
+            width: 0,
+            opacity: 0,
+            color: d3.color(color)?.darker(0.3).toString() ?? color,
+        }
+    }
+}
+
+export function defaultValueLineStyle(color: string = "#008aad"): LineStyle {
+    return {
+        regular: {
+            color,
+            opacity: 0.6,
+            width: 3
+        },
+        highlight: {
+            color,
+            opacity: 1,
+            width: 5
+        }
+    }
+}
+
+export function defaultMeanValueLineStyle(color: string = "#008aad"): LineStyle {
+    return {
+        regular: {
+            color,
+            opacity: 0.6,
+            width: 1
+        },
+        highlight: {
+            color,
+            opacity: 1,
+            width: 3
+        }
+    }
+}
+
+export function defaultWindowedMeanValueLineStyle(color: string = "#008aad"): LineStyle {
+    return {
+        regular: {
+            color: 'red',
+            opacity: 0.6,
+            width: 1
+        },
+        highlight: {
+            color: 'red',
+            opacity: 1,
+            width: 3
+        }
+    }
+}
+
+export function defaultBarSeriesStyle(color: string = "#008aad"): BarSeriesStyle {
+    return {
+        color,
+        highlightColor: color,
+        minMaxBar: defaultMinMaxBarStyle(color),
+        windowedMinMaxBar: defaultWindowedMinMaxBarStyle(color),
+        valueLine: defaultValueLineStyle(color),
+        meanValueLine: defaultMeanValueLineStyle(color),
+        windowedMeanValueLine: defaultWindowedMeanValueLineStyle(color),
+    }
+}

package/src/app/charts/styling/margins.test.ts

@@ -0,0 +1,22 @@
+import {plotDimensionsFrom, Margin, containerDimensionsFrom} from "./margins";
+
+describe('adjusted dimension should correct for margins', () => {
+    const margins: Margin = {top: 11, bottom: 12, left: 13, right: 14};
+    const width = 100;
+    const height = 200;
+    const dimensions = plotDimensionsFrom(width, height, margins);
+
+    test('adjusted width should have the left and right margins removed', () => {
+        expect(dimensions.width).toBe(width - margins.right - margins.left);
+    });
+
+    test('adjusted height should have the top and bottom margins removed', () => {
+        expect(dimensions.height).toBe(height - margins.top - margins.bottom);
+    });
+
+    test('should be able to get back the container dimensions after calculate the plot dimensions', () => {
+        const {width: containerWidth, height: containerHeight} = containerDimensionsFrom(plotDimensionsFrom(width, height, margins), margins);
+        expect(containerWidth).toBe(width);
+        expect(containerHeight).toBe(height);
+    })
+})