feat: add options in xBinning

Author: lpatiny

src/x/__tests__/xBinning.test.ts

@@ -5,40 +5,129 @@ import { xBinning } from '../xBinning.ts';
 test('binSize 1 returns a copy', () => {
   const array = [1, 2, 3, 4];
 
-  expect(xBinning(array, 1)).toStrictEqual(Float64Array.from([1, 2, 3, 4]));
+  expect(xBinning(array, { binSize: 1 })).toStrictEqual(
+    Float64Array.from([1, 2, 3, 4]),
+  );
 });
 
-test('even division', () => {
+test('default keepFirstAndLast with even division', () => {
   const array = [1, 2, 3, 4, 5, 6];
 
-  expect(xBinning(array, 2)).toStrictEqual(Float64Array.from([1.5, 3.5, 5.5]));
-  expect(xBinning(array, 3)).toStrictEqual(Float64Array.from([2, 5]));
+  expect(xBinning(array, { binSize: 2 })).toStrictEqual(
+    Float64Array.from([1, 2.5, 4.5, 6]),
+  );
+  expect(xBinning(array, { binSize: 3 })).toStrictEqual(
+    Float64Array.from([1, 3, 5, 6]),
+  );
 });
 
-test('uneven division averages remaining points', () => {
+test('default keepFirstAndLast with uneven division', () => {
   const array = [1, 2, 3, 4, 5, 6, 7];
 
-  expect(xBinning(array, 3)).toStrictEqual(Float64Array.from([2, 5, 7]));
+  expect(xBinning(array, { binSize: 3 })).toStrictEqual(
+    Float64Array.from([1, 3, 5.5, 7]),
+  );
 });
 
 test('accepts Float64Array input', () => {
   const array = Float64Array.from([2, 4, 6, 8]);
 
-  expect(xBinning(array, 2)).toStrictEqual(Float64Array.from([3, 7]));
+  expect(xBinning(array, { binSize: 2 })).toStrictEqual(
+    Float64Array.from([2, 5, 8]),
+  );
+});
+
+test('default binSize is 10', () => {
+  const array = Array.from({ length: 25 }, (_, i) => i + 1);
+
+  expect(xBinning(array)).toStrictEqual(
+    Float64Array.from([1, 6.5, 16.5, 23, 25]),
+  );
+});
+
+test('keepFirstAndLast=false restores pure binning', () => {
+  const array = [1, 2, 3, 4, 5, 6];
+
+  expect(
+    xBinning(array, { binSize: 2, keepFirstAndLast: false }),
+  ).toStrictEqual(Float64Array.from([1.5, 3.5, 5.5]));
+  expect(
+    xBinning(array, { binSize: 3, keepFirstAndLast: false }),
+  ).toStrictEqual(Float64Array.from([2, 5]));
+});
+
+test('keepFirstAndLast=false with uneven division', () => {
+  const array = [1, 2, 3, 4, 5, 6, 7];
+
+  expect(
+    xBinning(array, { binSize: 3, keepFirstAndLast: false }),
+  ).toStrictEqual(Float64Array.from([2, 5, 7]));
 });
 
 test('throws on invalid binSize', () => {
-  expect(() => xBinning([1, 2, 3], 0)).toThrow(
+  expect(() => xBinning([1, 2, 3], { binSize: 0 })).toThrow(
     /binSize must be a positive integer/,
   );
-  expect(() => xBinning([1, 2, 3], 1.5)).toThrow(
+  expect(() => xBinning([1, 2, 3], { binSize: 1.5 })).toThrow(
     /binSize must be a positive integer/,
   );
-  expect(() => xBinning([1, 2, 3], -2)).toThrow(
+  expect(() => xBinning([1, 2, 3], { binSize: -2 })).toThrow(
     /binSize must be a positive integer/,
   );
 });
 
 test('throws on empty input', () => {
-  expect(() => xBinning([], 2)).toThrow(/input must not be empty/);
+  expect(() => xBinning([], { binSize: 2 })).toThrow(/input must not be empty/);
+});
+
+test('length <= 2 returns a copy', () => {
+  expect(xBinning([1, 2], { binSize: 2 })).toStrictEqual(
+    Float64Array.from([1, 2]),
+  );
+  expect(xBinning([5], { binSize: 2 })).toStrictEqual(Float64Array.from([5]));
+});
+
+test('numberOfPoints splits into N bins', () => {
+  const array = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+
+  expect(
+    xBinning(array, { numberOfPoints: 5, keepFirstAndLast: false }),
+  ).toStrictEqual(Float64Array.from([1.5, 3.5, 5.5, 7.5, 9.5]));
+});
+
+test('numberOfPoints with uneven split', () => {
+  const array = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+
+  expect(
+    xBinning(array, { numberOfPoints: 3, keepFirstAndLast: false }),
+  ).toStrictEqual(Float64Array.from([2, 5, 8.5]));
+});
+
+test('numberOfPoints with keepFirstAndLast', () => {
+  const array = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+
+  expect(xBinning(array, { numberOfPoints: 5 })).toStrictEqual(
+    Float64Array.from([1, 2.5, 5, 8, 10]),
+  );
+});
+
+test('numberOfPoints throws when > length', () => {
+  expect(() => xBinning([1, 2, 3], { numberOfPoints: 4 })).toThrow(
+    /numberOfPoints must be <= array.length/,
+  );
+});
+
+test('numberOfPoints throws when not a positive integer', () => {
+  expect(() => xBinning([1, 2, 3], { numberOfPoints: 0 })).toThrow(
+    /numberOfPoints must be a positive integer/,
+  );
+  expect(() => xBinning([1, 2, 3], { numberOfPoints: 2.5 })).toThrow(
+    /numberOfPoints must be a positive integer/,
+  );
+});
+
+test('binSize and numberOfPoints are mutually exclusive', () => {
+  expect(() =>
+    xBinning([1, 2, 3, 4], { binSize: 2, numberOfPoints: 2 }),
+  ).toThrow(/mutually exclusive/);
 });

src/x/xBinning.ts

@@ -2,30 +2,91 @@ import type { NumberArray } from 'cheminfo-types';
 
 import { xCheck } from './xCheck.ts';
 
+export interface XBinningOptions {
+  /**
+   * Number of consecutive points to average per bin. Must be a positive integer.
+   * Ignored when `numberOfPoints` is provided.
+   * @default 10
+   */
+  binSize?: number;
+  /**
+   * Target number of points in the output. When provided, the input is split
+   * into `numberOfPoints` contiguous bins of as-equal-as-possible size, and
+   * takes precedence over `binSize`. Must be a positive integer and
+   * `<= array.length`.
+   */
+  numberOfPoints?: number;
+  /**
+   * If `true`, the first and last points of the input are preserved unchanged
+   * in the output (useful to keep the exact domain endpoints of a spectrum).
+   * The intermediate points (indices `1` to `length - 2`) are binned.
+   * @default true
+   */
+  keepFirstAndLast?: boolean;
+}
+
 /**
  * Downsample an array by averaging consecutive non-overlapping points (binning).
+ * Either specify a fixed `binSize` or a target `numberOfPoints`.
  * @param array - Input array.
- * @param binSize - Number of consecutive points to average per bin. Must be a positive integer.
- * @returns Downsampled array of length `ceil(array.length / binSize)`.
+ * @param options - Options.
+ * @returns Downsampled array.
  */
 export function xBinning(
   array: NumberArray,
-  binSize: number,
+  options: XBinningOptions = {},
 ): Float64Array<ArrayBuffer> {
   xCheck(array);
-  if (!Number.isInteger(binSize) || binSize <= 0) {
+  const { binSize, numberOfPoints, keepFirstAndLast = true } = options;
+  const { length } = array;
+
+  if (numberOfPoints !== undefined) {
+    if (binSize !== undefined) {
+      throw new RangeError('binSize and numberOfPoints are mutually exclusive');
+    }
+    if (!Number.isInteger(numberOfPoints) || numberOfPoints <= 0) {
+      throw new RangeError('numberOfPoints must be a positive integer');
+    }
+    if (numberOfPoints > length) {
+      throw new RangeError('numberOfPoints must be <= array.length');
+    }
+    return binByNumberOfPoints(array, numberOfPoints, keepFirstAndLast);
+  }
+
+  const effectiveBinSize = binSize ?? 10;
+  if (!Number.isInteger(effectiveBinSize) || effectiveBinSize <= 0) {
     throw new RangeError('binSize must be a positive integer');
   }
-  if (binSize === 1) {
+  if (effectiveBinSize === 1) {
     return Float64Array.from(array);
   }
 
-  const { length } = array;
-  const outputLength = Math.ceil(length / binSize);
+  if (keepFirstAndLast) {
+    if (length <= 2) {
+      return Float64Array.from(array);
+    }
+    const innerLength = length - 2;
+    const innerBinCount = Math.ceil(innerLength / effectiveBinSize);
+    const output = new Float64Array(innerBinCount + 2);
+    output[0] = array[0];
+    output[output.length - 1] = array[length - 1];
+    for (let i = 0, j = 1; i < innerLength; i += effectiveBinSize, j++) {
+      const start = i + 1;
+      const end = Math.min(start + effectiveBinSize, length - 1);
+      let sum = 0;
+      for (let k = start; k < end; k++) {
+        sum += array[k];
+      }
+      output[j] = sum / (end - start);
+    }
+    return output;
+  }
+
+  const outputLength = Math.ceil(length / effectiveBinSize);
   const output = new Float64Array(outputLength);
 
-  for (let i = 0, j = 0; i < length; i += binSize, j++) {
-    const end = Math.min(i + binSize, length);
+  for (let i = 0, j = 0; i < length; i += effectiveBinSize, j++) {
+    const end = Math.min(i + effectiveBinSize, length);
     let sum = 0;
     for (let k = i; k < end; k++) {
       sum += array[k];
@@ -35,3 +96,53 @@ export function xBinning(
 
   return output;
 }
+
+function binByNumberOfPoints(
+  array: NumberArray,
+  numberOfPoints: number,
+  keepFirstAndLast: boolean,
+): Float64Array<ArrayBuffer> {
+  const { length } = array;
+  const output = new Float64Array(numberOfPoints);
+
+  if (keepFirstAndLast) {
+    if (numberOfPoints < 2) {
+      throw new RangeError(
+        'numberOfPoints must be >= 2 when keepFirstAndLast is true',
+      );
+    }
+    output[0] = array[0];
+    output[numberOfPoints - 1] = array[length - 1];
+    if (numberOfPoints === 2) {
+      return output;
+    }
+    const innerLength = length - 2;
+    const innerBins = numberOfPoints - 2;
+    if (innerBins > innerLength) {
+      throw new RangeError(
+        'numberOfPoints is too large for the given array length with keepFirstAndLast',
+      );
+    }
+    for (let j = 0; j < innerBins; j++) {
+      const start = 1 + Math.floor((j * innerLength) / innerBins);
+      const end = 1 + Math.floor(((j + 1) * innerLength) / innerBins);
+      let sum = 0;
+      for (let k = start; k < end; k++) {
+        sum += array[k];
+      }
+      output[j + 1] = sum / (end - start);
+    }
+    return output;
+  }
+
+  for (let j = 0; j < numberOfPoints; j++) {
+    const start = Math.floor((j * length) / numberOfPoints);
+    const end = Math.floor(((j + 1) * length) / numberOfPoints);
+    let sum = 0;
+    for (let k = start; k < end; k++) {
+      sum += array[k];
+    }
+    output[j] = sum / (end - start);
+  }
+  return output;
+}