feat: Histogram should honour "buckets" option (#4485)

Signed-off-by: Gordon Smith <GordonJSmith@gmail.com>

Author: GordonSmith

packages/dataflow/src/activities/histogram.ts

@@ -5,6 +5,11 @@ import { scalar } from "../observers/observer.ts";
 export type HistogramFn<T> = (row: T) => number;
 export type HistogramRow<T> = { from: number, to: number, value: T[] };
 export type OptionA = { buckets: number };
+/** 
+ * Histogram options specifying the minimum value and bucket range (size).
+ * @property min - The minimum value for the first bucket's lower bound
+ * @property range - The size/width of each bucket (distance between bucket boundaries)
+ */
 export type OptionB = { min: number, range: number };
 export type Options = OptionA | OptionB;
 
@@ -21,8 +26,17 @@ function histogramGen<T = any>(callbackFn: HistogramFn<T>, options: Options): It
         if (isOptionA(options)) {
             source = Array.isArray(_source) ? _source : [..._source];
             const minMax = scalar(extent(callbackFn))(source);
-            if (minMax === undefined) {
-                return undefined;
+            if (minMax === undefined || minMax[0] === undefined || minMax[1] === undefined) {
+                // For empty sources with buckets option, generate empty buckets with NaN bounds
+                const buckets = options.buckets;
+                for (let i = 0; i < buckets; ++i) {
+                    yield {
+                        from: NaN,
+                        to: NaN,
+                        value: []
+                    };
+                }
+                return;
             }
             min = minMax[0];
             const max = minMax[1];
@@ -37,7 +51,9 @@ function histogramGen<T = any>(callbackFn: HistogramFn<T>, options: Options): It
         const histogram: { [key: number]: T[] } = {};
 
         let maxBucketID = 0;
+        let hasData = false;
         for (const row of source) {
+            hasData = true;
             const value = callbackFn(row);
             const bucketID = Math.floor((value - min) / bucketSize);
             if (maxBucketID < bucketID) {
@@ -49,6 +65,11 @@ function histogramGen<T = any>(callbackFn: HistogramFn<T>, options: Options): It
             histogram[bucketID].push(row);
         }
 
+        // If no data, return empty for OptionB (min/range)
+        if (!hasData) {
+            return;
+        }
+
         const lastBucket = histogram[maxBucketID];
         const from = min + maxBucketID * bucketSize;
 

packages/dataflow/tests/histogram.spec.ts

@@ -41,7 +41,84 @@ describe("histogram", () => {
         const data = [1, 12, 13, 13, 3, 14, 19, 6];
         const h = [...histogram(data, n => n, { buckets: 3 })];
         expect(h).to.have.length;
+        expect(h.length).to.equal(3);
         const h2 = [...histogram(data, n => n, { min: 0, range: 5 })];
         expect(h2).to.have.length;
+        expect(h2.length).to.equal(4);
+    });
+
+
+    it("sparse buckets", () => {
+        const data = [1, 6, 13, 13, 3, 14, 19, 4];
+        const h = [...histogram(data, n => n, { buckets: 3 })];
+        expect(h).to.have.length;
+        expect(h.length).to.equal(3);
+        for (let i = 0; i < h.length; i++) {
+            switch (i) {
+                case 0:
+                    expect(h[i].from).to.equal(1);
+                    expect(h[i].to).to.equal(7);
+                    expect(h[i].value).to.deep.equal([1, 6, 3, 4]);
+                    break;
+                case 1:
+                    expect(h[i].from).to.equal(7);
+                    expect(h[i].to).to.equal(13);
+                    expect(h[i].value).to.deep.equal([]);
+                    break;
+                case 2:
+                    expect(h[i].from).to.be.equal(13);
+                    expect(h[i].to).to.be.equal(19);
+                    expect(h[i].value).to.deep.equal([13, 13, 14, 19]);
+                    break;
+            }
+        }
+        const data2 = [1, 13, 12, 13, 3, 14, 19, 4];
+        const h2 = [...histogram(data2, n => n, { min: 0, range: 5 })];
+        expect(h2).to.have.length;
+        expect(h2.length).to.equal(4);
+        for (let i = 0; i < h.length; i++) {
+            switch (i) {
+                case 0:
+                    expect(h2[i].from).to.equal(0);
+                    expect(h2[i].to).to.equal(5);
+                    expect(h2[i].value).to.deep.equal([1, 3, 4]);
+                    break;
+                case 1:
+                    expect(h2[i].from).to.equal(5);
+                    expect(h2[i].to).to.equal(10);
+                    expect(h2[i].value).to.deep.equal([]);
+                    break;
+                case 2:
+                    expect(h2[i].from).to.be.equal(10);
+                    expect(h2[i].to).to.be.equal(15);
+                    expect(h2[i].value).to.deep.equal([13, 12, 13, 14]);
+                    break;
+                case 3:
+                    expect(h2[i].from).to.be.equal(15);
+                    expect(h2[i].to).to.be.equal(20);
+                    expect(h2[i].value).to.deep.equal([19]);
+                    break;
+            }
+        }
+    });
+
+    it("empty source with buckets", () => {
+        const h = [...histogram<number>(n => n, { buckets: 10 })([])];
+        expect(h.length).to.equal(10);
+        for (const b of h) {
+            expect(b.from).to.be.NaN;
+            expect(b.to).to.be.NaN;
+            expect(b.value).to.deep.equal([]);
+        }
+    });
+
+    it("empty source with buckets 2", () => {
+        const data: number[] = [];
+        const h = [...histogram(data, n => n, { buckets: 3 })];
+        expect(h).to.have.length;
+        expect(h.length).to.equal(3);
+        const h2 = [...histogram(data, n => n, { min: 0, range: 5 })];
+        expect(h2).to.have.length;
+        expect(h2.length).to.equal(0);
     });
 });