stream-charts 1.2.0 → 2.0.0

package/src/app/charts/legends/constants.ts

@@ -0,0 +1,37 @@
+import type {LegendStyle} from "./Legend";
+
+/**
+ * The location of the legend, either in the plot or in an external container
+ * Note: replaces enums to support `erasableSyntaxOnly`
+ *  TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled.
+ */
+export const LegendLocation = {
+    // noinspection JSUnusedGlobalSymbols
+    TOP_LEFT: "top-left",
+    TOP_RIGHT: "top-right",
+    BOTTOM_LEFT: "bottom-left",
+    BOTTOM_RIGHT: "bottom-right",
+    EXTERNAL_CONTAINER: "external-container"
+} as const
+export type LegendLocation = (typeof LegendLocation)[keyof typeof LegendLocation];
+
+/**
+ * The legend's default style
+ */
+export const defaultLegendStyle: LegendStyle = {
+    fontSize: 12,
+    fontFamily: "sans-serif",
+    fontColor: "#d2933f",
+    backgroundColor: "#202020",
+    backgroundOpacity: 0.85,
+    borderColor: "#d2933f",
+    borderWidth: 1,
+    borderOpacity: 0.7,
+    borderRadius: 4,
+    padding: 8,
+    rowGap: 6,
+    swatchWidth: 16,
+    swatchHeight: 3,
+    swatchLabelGap: 6,
+    transitionDuration: 350,
+}

package/src/app/charts/observables/iterates.ts

@@ -8,11 +8,11 @@
  * 2. Accepts that chart-data observable and converts that observable to an iterate-chart-data observable
  */
 import {Observable} from "rxjs";
-import {TimeSeriesChartData} from "../series/timeSeriesChartData";
+import type {TimeSeriesChartData} from "../series/timeSeriesChartData";
 import {filter, map, scan} from "rxjs/operators";
-import {Datum, emptyDatum} from "../series/timeSeries";
-import {emptyIterateDatum, IterateDatum, iterateDatumOf, nonEmptyIterateDatum} from "../series/iterateSeries";
-import {ChartData, copyChartData, defaultChartData} from "./ChartData";
+import {type Datum, emptyDatum} from "../series/timeSeries";
+import {emptyIterateDatum, type IterateDatum, iterateDatumOf, nonEmptyIterateDatum} from "../series/iterateSeries";
+import {type ChartData, copyChartData, defaultChartData} from "./ChartData";
 
 
 export interface IterateChartData extends ChartData {
@@ -27,12 +27,14 @@ export interface IterateChartData extends ChartData {
     maxIterate: IterateDatum
 
     /**
-     * Holds the association of the series name to the current min time for that series
+     * Holds the association of the series name to the min values for (time, iterate n, and
+     * iterate n+1) for that series
      */
     minIterates: Map<string, IterateDatum>
 
     /**
-     * Holds the association of the series name to the current max time for that series
+     * Holds the association of the series name to the max values for (time, iterate n, and
+     * iterate n+1) for that series
      */
     maxIterates: Map<string, IterateDatum>
 
@@ -43,6 +45,9 @@ export interface IterateChartData extends ChartData {
     newPoints: Map<string, Array<IterateDatum>>
 }
 
+/**
+ * @return Iterate chart data without any series or points, and with empty min and max iterates
+ */
 const emptyIterateData = (): IterateChartData => ({
     ...defaultChartData(),
     minIterate: emptyIterateDatum,
@@ -53,8 +58,10 @@ const emptyIterateData = (): IterateChartData => ({
 })
 
 /**
- * Makes a deep copy of the iterate chart data
+ * Makes a copy of the iterate chart data: new sets, maps, and arrays of points (the points
+ * themselves are shared)
  * @param data The iterate chart data to copy
+ * @return The copy
  */
 export const copyIterateDataFrom = (data: IterateChartData): IterateChartData => ({
     ...copyChartData(data),
@@ -65,12 +72,19 @@ export const copyIterateDataFrom = (data: IterateChartData): IterateChartData =>
     newPoints: new Map<string, Array<IterateDatum>>(Array.from(data.newPoints.entries()).map(([name, points]) => [name, points.slice()])),
 })
 
+// the state accumulated, from one chunk of time-series chart data to the next, while calculating
+// the iterates: the iterate distance, the points not yet paired up (by series), and the iterates
 type Accumulator = {
     n: number
     previous: Map<string, Array<Datum>>
     accumulated: IterateChartData
 }
 
+/**
+ * The accumulator to start calculating the n-iterates from
+ * @param n The iterate distance
+ * @return An accumulator with no points and no iterates
+ */
 const initialAccumulate = (n: number): Accumulator => ({n, previous: new Map(), accumulated: emptyIterateData()})
 
 /**
@@ -81,7 +95,8 @@ const initialAccumulate = (n: number): Accumulator => ({n, previous: new Map(),
  * points `(f[m](x), f[m+n](x))` are n-iterates.
  * @param dataObservable The observable over {@link TimeSeriesChartData}
  * @param [n=1] The iterate distance
- * @return An over {@link IterateChartData} holding the n-iterate for the incoming chart data
+ * @return An observable over {@link IterateChartData} holding the n-iterate for the incoming chart
+ * data (nothing is emitted until the first iterate has been calculated)
  */
 export function iteratesObservable(dataObservable: Observable<TimeSeriesChartData>, n: number = 1): Observable<IterateChartData> {
     return dataObservable
@@ -117,7 +132,7 @@ export function iteratesObservable(dataObservable: Observable<TimeSeriesChartDat
                             previous.set(name, updated)
 
                             // create the new iterate
-                            const iterate: IterateDatum = iterateDatumOf(first.time, first.value, last.value);
+                            const iterate: IterateDatum = iterateDatumOf(first.x, first.y, last.y);
 
                             // update the min, max values for all the series
                             accum.minIterate = minIterateFor(iterate, accum.minIterate)
@@ -128,8 +143,7 @@ export function iteratesObservable(dataObservable: Observable<TimeSeriesChartDat
                             accum.maxIterates.set(name, maxIterateFor(iterate, accum.maxIterates.get(name)))
 
                             // add the newly calculated iterate, and then trim from the
-                            // head of the array to a size n. For the iterates, we only need
-                            // to keep enough to create points (x(j), x(j+n))
+                            // head of the array to the number of points in this chunk
                             const updatedPoints = accum.newPoints.get(name) || []
                             if (updatedPoints.length === 0) {
                                 accum.newPoints.set(name, updatedPoints)
@@ -143,7 +157,8 @@ export function iteratesObservable(dataObservable: Observable<TimeSeriesChartDat
                 return {n, previous, accumulated: accum}
             }, initialAccumulate(n)),
 
-            // remove new points from the map that are empty
+            // skip the chunks until the first iterate has been calculated, and remove the empty
+            // new points
             filter(accum => !isNaN(accum.accumulated.minIterate.iterateN) && !isNaN(accum.accumulated.minIterate.iterateN_1)),
             map(accum => removeEmptyNewPoints(accum)),
             map(accum => accum.accumulated === undefined ? emptyIterateData() : accum.accumulated)
@@ -186,6 +201,11 @@ function maxIterateFor(iterate: IterateDatum, maxIterate: IterateDatum = emptyIt
     }
 }
 
+/**
+ * Removes the empty iterates from the accumulated new points
+ * @param accum The accumulator
+ * @return A new accumulator, whose accumulated new points are the non-empty ones
+ */
 function removeEmptyNewPoints(accum: Accumulator): Accumulator {
     const newPoints = new Map(
         Array

package/src/app/charts/observables/ordinals.ts

@@ -5,16 +5,18 @@
  * 2. Accepts that chart-data observable and converts that observable to an ordinal-chart-data observable
  */
 import {Observable} from "rxjs";
-import {TimeSeriesChartData} from "../series/timeSeriesChartData";
+import type {TimeSeriesChartData} from "../series/timeSeriesChartData";
 import {map, scan} from "rxjs/operators";
-import {Datum} from "../series/timeSeries";
-import {copyOrdinalDatum, nonEmptyOrdinalDatum, OrdinalDatum, ordinalDatumOf} from "../series/ordinalSeries";
-import {ChartData, copyChartData, defaultChartData} from "./ChartData";
+import type {Datum} from "../series/timeSeries";
+import {copyOrdinalDatum, nonEmptyOrdinalDatum, type OrdinalDatum, ordinalDatumOf} from "../series/ordinalSeries";
+import {type ChartData, copyChartData, defaultChartData} from "./ChartData";
+import {FastShiftArray} from "fast-shift-array";
+import {DEFAULT_COMPACTING_SIZE} from "../series/baseSeries";
 
 export interface OrdinalChartData extends ChartData {
     /**
      * Statistics for the chart. Holds the overall minimum and maximum (across all
-     * the series), and statistics for each individual series.
+     * the series), and statistics for each series.
      */
     stats: OrdinalStats
 
@@ -22,7 +24,8 @@ export interface OrdinalChartData extends ChartData {
      * 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<OrdinalDatum>>
+    // newPoints: Map<string, Array<OrdinalDatum>>
+    newPoints: Map<string, FastShiftArray<OrdinalDatum>>
 }
 
 /**
@@ -31,12 +34,12 @@ export interface OrdinalChartData extends ChartData {
  */
 export interface OrdinalStats {
     /**
-     * The min values for (time, value) for the data in the newPoints map
+     * The data with the min time, and with the min value, over all the data so far
      */
     minDatum: OrdinalDatumExtremum
 
     /**
-     * The max values for (time, iterate n, and iterate n+1) for the data in the newPoints map
+     * The data with the max time, and with the max value, over all the data so far
      */
     maxDatum: OrdinalDatumExtremum
 
@@ -46,6 +49,10 @@ export interface OrdinalStats {
     valueStatsForSeries: Map<string, OrdinalValueStats>
 }
 
+/**
+ * Statistics about the values of a series: the data with the min and max values, the number of
+ * values, their sum, the sum of their squares, and their mean
+ */
 export type OrdinalValueStats = {
     min: OrdinalDatum
     max: OrdinalDatum
@@ -55,6 +62,9 @@ export type OrdinalValueStats = {
     mean: number
 }
 
+/**
+ * The data with the extreme (min or max) time, and with the extreme value
+ */
 export type OrdinalDatumExtremum = {
     // holds the ordinal datum with the minimum or maximum time
     time: OrdinalDatum
@@ -62,30 +72,49 @@ export type OrdinalDatumExtremum = {
     value: OrdinalDatum
 }
 
+/**
+ * @return The datum to start a search for the min value from: its value (`Infinity`) is larger
+ * than any other
+ */
 export const initialMinValueDatum = (): OrdinalDatum => ordinalDatumOf(NaN, "", Infinity)
+/**
+ * @return The datum to start a search for the max value from: its value (`-Infinity`) is smaller
+ * than any other
+ */
 export const initialMaxValueDatum = (): OrdinalDatum => ordinalDatumOf(NaN, "", -Infinity)
 
+/**
+ * @return The datum to start a search for the min time from: its time (`Infinity`) is later than
+ * any other
+ */
 export const initialMinTimeDatum = (): OrdinalDatum => ordinalDatumOf(Infinity, "", NaN)
+/**
+ * @return The datum to start a search for the max time from: its time (`-Infinity`) is earlier
+ * than any other
+ */
 export const initialMaxTimeDatum = (): OrdinalDatum => ordinalDatumOf(-Infinity, "", NaN)
 
-export function valueStatusDatumOfDefault(datum: OrdinalDatum | undefined): OrdinalDatum {
-    return (datum === undefined) ? ordinalDatumOf(NaN, "", NaN) : datum
-}
-
-export function isDefaultValueStatsDatum(datum: OrdinalDatum): boolean {
-    return isNaN(datum.time) && datum.ordinal === "" && isNaN(datum.value)
-}
-
+/**
+ * @return The extremum to start a search for the min time and value from
+ */
 const initialMinOrdinalDatum = (): OrdinalDatumExtremum => ({
     time: ordinalDatumOf(Infinity, "", NaN),
     value: initialMinValueDatum()
 })
 
+/**
+ * @return The extremum to start a search for the max time and value from
+ */
 const initialMaxOrdinalDatum = (): OrdinalDatumExtremum => ({
     time: ordinalDatumOf(-Infinity, "", NaN),
     value: initialMaxValueDatum()
 })
 
+/**
+ * Copies an extremum (and its data)
+ * @param datum The extremum to copy
+ * @return The copy
+ */
 export function copyOrdinalDatumExtremum(datum: OrdinalDatumExtremum): OrdinalDatumExtremum {
     return {
         time: copyOrdinalDatum(datum.time),
@@ -93,12 +122,19 @@ export function copyOrdinalDatumExtremum(datum: OrdinalDatumExtremum): OrdinalDa
     }
 }
 
+/**
+ * @return Stats for no data: extremes to start the searches from, and no series' stats
+ */
 export const defaultOrdinalStats = (): OrdinalStats => ({
     minDatum: initialMinOrdinalDatum(),
     maxDatum: initialMaxOrdinalDatum(),
     valueStatsForSeries: new Map<string, OrdinalValueStats>()
 })
 
+/**
+ * @return Value stats for no data: a count, sum, and sum of squares of 0, a `NaN` mean, and min
+ * and max data to start the searches from
+ */
 export const defaultOrdinalValueStats = (): OrdinalValueStats => ({
     min: initialMinValueDatum(),
     max: initialMaxValueDatum(),
@@ -108,6 +144,11 @@ export const defaultOrdinalValueStats = (): OrdinalValueStats => ({
     sumSquared: 0,
 })
 
+/**
+ * Copies a series' value stats (and their min and max data)
+ * @param data The value stats to copy
+ * @return The copy
+ */
 export function copyOrdinalValueStats(data: OrdinalValueStats): OrdinalValueStats {
     return {
         ...data,
@@ -116,51 +157,89 @@ export function copyOrdinalValueStats(data: OrdinalValueStats): OrdinalValueStat
     }
 }
 
+/**
+ * Copies the map of each series' value stats (and the stats)
+ * @param valueStats The value stats, by series name
+ * @return The copy
+ */
 export function copyValueStatsForSeries(valueStats: Map<string, OrdinalValueStats>): Map<string, OrdinalValueStats> {
     return new Map<string, OrdinalValueStats>(Array.from(valueStats.entries())
         .map(([seriesName, valueStats]) => [seriesName, copyOrdinalValueStats(valueStats)])
     )
 }
 
+/**
+ * Copies the stats (the extremes, and each series' value stats)
+ * @param data The stats to copy
+ * @return The copy
+ */
 export const copyOrdinalStats = (data: OrdinalStats): OrdinalStats => ({
     minDatum: copyOrdinalDatumExtremum(data.minDatum),
     maxDatum: copyOrdinalDatumExtremum(data.maxDatum),
     valueStatsForSeries: copyValueStatsForSeries(data.valueStatsForSeries),
 })
 
+/**
+ * @return Ordinal chart data without any series or points, and with the default stats
+ */
 const emptyOrdinalData = (): OrdinalChartData => ({
     ...defaultChartData(),
     stats: defaultOrdinalStats(),
-    newPoints: new Map<string, Array<OrdinalDatum>>()
+    newPoints: new Map<string, FastShiftArray<OrdinalDatum>>()
+    // newPoints: new Map<string, Array<OrdinalDatum>>()
 })
 
 /**
- * Makes a deep copy of the ordinal chart data
+ * Makes a copy of the ordinal chart data: a new set of series names, copies of the stats, and new
+ * arrays of points (the points themselves are shared)
  * @param data The ordinal chart data to copy
+ * @return The copy
  */
 export const copyOrdinalDataFrom = (data: OrdinalChartData): OrdinalChartData => ({
     ...copyChartData(data),
     stats: copyOrdinalStats(data.stats),
-    newPoints: new Map<string, Array<OrdinalDatum>>(Array.from(data.newPoints.entries()).map(([name, points]) => [name, points.slice()])),
+    newPoints: new Map<string, FastShiftArray<OrdinalDatum>>(Array.from(data.newPoints.entries()).map(([name, points]) => [name, points.slice()])),
+    // newPoints: new Map<string, Array<OrdinalDatum>>(Array.from(data.newPoints.entries()).map(([name, points]) => [name, points.slice()])),
 })
 
-type Accumulator = {
-    previous: Map<string, Array<Datum>>
-    accumulated: OrdinalChartData
-}
-
-const initialAccumulate = (): Accumulator => ({previous: new Map(), accumulated: emptyOrdinalData()})
+/**
+ * @param initialStats Optional stats to start the accumulation from (see {@link ordinalsObservable})
+ * @return The initial accumulated chart data
+ */
+const initialAccumulate = (initialStats?: OrdinalStats): OrdinalChartData =>
+    initialStats === undefined ?
+        emptyOrdinalData() :
+        {
+            ...emptyOrdinalData(),
+            seriesNames: new Set(initialStats.valueStatsForSeries.keys()),
+            stats: copyOrdinalStats(initialStats)
+        }
 
 /**
- * Accepts a {@link TimeSeriesChartData} observable and converts it to an observable of {@link OrdinalChartData}.
+ * Accepts a {@link TimeSeriesChartData} observable and converts it to an observable of {@link OrdinalChartData}:
+ * each emission holds the incoming chunk's points (as ordinal data), and the stats accumulated over
+ * all the data so far.
  * @param dataObservable The observable over {@link TimeSeriesChartData}
+ * @param [compactingSize=DEFAULT_COMPACTING_SIZE] The number of shifts a series' backing array accumulates before it's compacted
+ * @param initialStats Optional stats of the data that already exists (e.g. a chart's accumulated
+ * series, see `calculateOrdinalStats`), from which the stats accumulate -- so that the stats cover
+ * that data without the data having to be re-emitted through `dataObservable`
  * @return An observable of {@link OrdinalChartData} holding the series for the incoming chart data
  */
-export function ordinalsObservable(dataObservable: Observable<TimeSeriesChartData>): Observable<OrdinalChartData> {
+export function ordinalsObservable(
+    dataObservable: Observable<TimeSeriesChartData>,
+    compactingSize: number = DEFAULT_COMPACTING_SIZE,
+    initialStats?: OrdinalStats,
+): Observable<OrdinalChartData> {
     return dataObservable
         .pipe(
-            // calculate the iterates for each series in the chart data
-            scan(({previous, accumulated}: Accumulator, current: TimeSeriesChartData) => {
+            // calculate the stats for each series in the chart data
+            //
+            // note: only the stats and the latest new points are accumulated -- the incoming points
+            // themselves aren't kept (the data source holds the series). A previous version also
+            // appended every incoming point to a map that nothing ever read, which grew without bound
+            // for as long as the stream ran (one point per series per tick).
+            scan((accumulated: OrdinalChartData, current: TimeSeriesChartData) => {
                 // make a deep copy of the accumulated data (because the accumulated data object
                 // holds references to maps)
                 const accum = copyOrdinalDataFrom(accumulated)
@@ -169,51 +248,44 @@ export function ordinalsObservable(dataObservable: Observable<TimeSeriesChartDat
                 Array
                     .from(current.newPoints.entries())
                     .forEach(([name, series]) => {
-                        // grab the points from the previous incoming data and add the new
-                        // data to the end  of the previous data (when the updated data
-                        // didn't yet exist, add it to the map holding the previous series)
-                        const updated = (previous.get(name) || [])
-                        if (updated.length === 0) {
-                            previous.set(name, updated)
-                        }
-                        updated.push(...series)
-
                         // add the series name to the list of all
                         accum.seriesNames.add(name)
 
                         // calculate the max-time, min-time, max-value, and min-value for
                         // all the data series
-                        series.forEach(({time, value}: Datum, ) => {
+                        series.forEach(({x, y}: Datum, ) => {
                             // calculate the min and max times over all series
-                            if (time < accum.stats.minDatum.time.time) {
-                                accum.stats.minDatum.time = ordinalDatumOf(time, name, value)
-                            } else if (time > accum.stats.maxDatum.time.time) {
-                                accum.stats.maxDatum.time = ordinalDatumOf(time, name, value)
+                            if (x < accum.stats.minDatum.time.time) {
+                                accum.stats.minDatum.time = ordinalDatumOf(x, name, y)
+                            }
+                            if (x > accum.stats.maxDatum.time.time) {
+                                accum.stats.maxDatum.time = ordinalDatumOf(x, name, y)
                             }
                             // calculate the min and max values over all series
-                            if (value < accum.stats.minDatum.value.value) {
-                                accum.stats.minDatum.value = ordinalDatumOf(time, name, value)
-                            } else if (value > accum.stats.maxDatum.value.value) {
-                                accum.stats.maxDatum.value = ordinalDatumOf(time, name, value)
+                            if (y < accum.stats.minDatum.value.value) {
+                                accum.stats.minDatum.value = ordinalDatumOf(x, name, y)
+                            }
+                            if (y > accum.stats.maxDatum.value.value) {
+                                accum.stats.maxDatum.value = ordinalDatumOf(x, name, y)
                             }
 
                             // calculate the min, max of the time and value for each series
                             let valueStats: OrdinalValueStats = accum.stats.valueStatsForSeries.get(name) || defaultOrdinalValueStats()
 
-                            const minValue = (value < valueStats.min.value) ?
-                                ordinalDatumOf(time, name, value) :
+                            const minValue = (y < valueStats.min.value) ?
+                                ordinalDatumOf(x, name, y) :
                                 copyOrdinalDatum(valueStats.min)
-                            const maxValue = (value > valueStats.max.value) ?
-                                ordinalDatumOf(time, name, value) :
+                            const maxValue = (y > valueStats.max.value) ?
+                                ordinalDatumOf(x, name, y) :
                                 copyOrdinalDatum(valueStats.max)
                             const count = valueStats.count + 1
-                            const sum = valueStats.sum + value
+                            const sum = valueStats.sum + y
                             valueStats = {
                                 min: minValue,
                                 max: maxValue,
                                 count,
                                 sum,
-                                sumSquared: isNaN(valueStats.sumSquared) ? value * value : valueStats.sumSquared + value * value,
+                                sumSquared: isNaN(valueStats.sumSquared) ? y * y : valueStats.sumSquared + y * y,
                                 mean: sum / count
                             }
 
@@ -221,28 +293,30 @@ export function ordinalsObservable(dataObservable: Observable<TimeSeriesChartDat
                         })
 
                         // convert the new points to ordinal datum
-                        accum.newPoints.set(name, series.map(({time, value}: Datum) => ordinalDatumOf(time, name, value)))
+                        accum.newPoints.set(name, FastShiftArray.fromArray(
+                            series.map(({x, y}: Datum) => ordinalDatumOf(x, name, y)),
+                            true,
+                            compactingSize
+                        ))
+                        // accum.newPoints.set(name, series.map(({x, y}: Datum) => ordinalDatumOf(x, name, y)))
                     })
-                return {previous, accumulated: accum}
-            }, initialAccumulate()),
+                return accum
+            }, initialAccumulate(initialStats)),
 
             // remove new points from the map that are empty
-            map(accum => removeEmptyNewPoints(accum)),
-            map(accum => accum.accumulated === undefined ? emptyOrdinalData() : accum.accumulated)
+            map(accumulated => removeEmptyNewPoints(accumulated))
         )
 }
 
-function removeEmptyNewPoints(accum: Accumulator): Accumulator {
+/**
+ * @param data The ordinal chart data
+ * @return A copy of the chart data, without any empty new points
+ */
+function removeEmptyNewPoints(data: OrdinalChartData): OrdinalChartData {
     const newPoints = new Map(
         Array
-            .from(accum.accumulated.newPoints.entries())
+            .from(data.newPoints.entries())
             .map(([name, points]) => [name, points.filter(point => nonEmptyOrdinalDatum(point))])
     )
-    return {
-        previous: accum.previous,
-        accumulated: {
-            ...accum.accumulated,
-            newPoints
-        }
-    }
+    return {...data, newPoints}
 }

package/src/app/charts/observables/outliers.ts

@@ -0,0 +1,20 @@
+import type {ChartData} from "./ChartData";
+import type {OutlierDatum} from "../series/outlierSeries";
+
+/**
+ * The chart data for outlier charts: each series' new {@link OutlierDatum}s (each a value, with
+ * the bands it may fall outside of)
+ */
+export interface OutlierChartData<M extends readonly number[]> extends ChartData {
+
+    /**
+     * Maps the series name to the new outlier datum for that series
+     */
+    newPoints: Map<string, Array<OutlierDatum<M>>>
+
+    /**
+     * The current time (used with cadence, when the axes should continue to scroll even when no
+     * new data has arrived)
+     */
+    currentTime?: number
+}