feat: Implement zonesToXEquallySpaced (#356)

Author: jobo322

src/__tests__/__snapshots__/index.test.ts.snap

@@ -148,6 +148,7 @@ exports[`existence of exported functions 1`] = `
   "xyObjectToXY",
   "zonesNormalize",
   "zonesWithPoints",
+  "zonesToXEquallySpaced",
   "matrixAbsoluteMedian",
   "matrixApplyNumericalEncoding",
   "matrixAutoCorrelation",

src/zones/__tests__/zonesToXEquallySpaced.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+
+import { zonesToXEquallySpaced } from '../zonesToXEquallySpaced.ts';
+
+describe('zonesToXEquallySpaced', () => {
+  it('should distribute points equally across a single zone', () => {
+    const zones = [{ from: 0, to: 10 }];
+    const result = zonesToXEquallySpaced(zones, 5);
+
+    expect(result).toHaveLength(5);
+    // Edges are excluded: approx [1.6667, 3.3333, 5, 6.6667, 8.3333]
+    expect(result[0]).toBeCloseTo(10 / 6, 5);
+    expect(result[2]).toBeCloseTo(5, 5);
+    expect(result[4]).toBeCloseTo((10 * 5) / 6, 5);
+  });
+
+  it('should distribute points across multiple zones without repeating edges', () => {
+    const zones = [
+      { from: 0, to: 5 },
+      { from: 10, to: 15 },
+    ];
+    const result = zonesToXEquallySpaced(zones, 10);
+
+    expect(result).toHaveLength(10);
+    // Edges excluded: first value ~0.8333, last value ~14.1667
+    expect(result[0]).toBeCloseTo(5 / 6, 5);
+    expect(result[9]).toBeCloseTo(15 - 5 / 6, 5);
+
+    // Check that zone boundary (5) is not in the result
+    const has5 = Array.from(result).some((v) => Math.abs(v - 5) < 0.01);
+
+    expect(has5).toBe(false);
+  });
+
+  it('should handle zones with custom from/to options', () => {
+    const zones = [{ from: 2, to: 8 }];
+    const result = zonesToXEquallySpaced(zones, 3, { from: 0, to: 10 });
+
+    expect(result).toHaveLength(3);
+    // Edges excluded: values are approx [3.5, 5, 6.5]
+    expect(result[0]).toBeCloseTo(3.5, 5);
+    expect(result[1]).toBeCloseTo(5, 5);
+    expect(result[2]).toBeCloseTo(6.5, 5);
+  });
+
+  it('should throw error if zones array is empty', () => {
+    expect(() => zonesToXEquallySpaced([], 10)).toThrow(
+      'zones array must not be empty',
+    );
+  });
+
+  it('should throw error if numberOfPoints is less than 1', () => {
+    const zones = [{ from: 0, to: 10 }];
+
+    expect(() => zonesToXEquallySpaced(zones, 0)).toThrow(
+      "'numberOfPoints' must be greater than 0",
+    );
+  });
+
+  it('should throw error if from is greater than to', () => {
+    const zones = [{ from: 10, to: 0 }];
+
+    expect(() => zonesToXEquallySpaced(zones, 10)).toThrow(
+      'from should be less than or equal to to',
+    );
+  });
+});

src/zones/index.ts

@@ -1,2 +1,3 @@
 export * from './zonesNormalize.ts';
 export * from './zonesWithPoints.ts';
+export * from './zonesToXEquallySpaced.ts';

src/zones/zonesToXEquallySpaced.ts

@@ -0,0 +1,77 @@
+import type { FromTo } from 'cheminfo-types';
+
+import { createFromToArray } from '../utils/createFromToArray.ts';
+
+import { zonesNormalize } from './zonesNormalize.ts';
+import { zonesWithPoints } from './zonesWithPoints.ts';
+
+export interface XZonesEquallySpacedOptions {
+  /**
+   * from - the minimum x value
+   * @default zones[0].from
+   */
+  from?: number;
+
+  /**
+   * to - the maximum x value
+   * @default zones[zones.length-1].to
+   */
+  to?: number;
+}
+
+/**
+ * Function that returns a Number array of equally spaced numberOfPoints x values
+ * distributed across the specified zones.
+ * @param zones - array of from/to zones where x values should be distributed
+ * @param numberOfPoints - total number of points to distribute across all zones
+ * @param options - options
+ * @returns array of equally spaced x values distributed across zones
+ */
+export function zonesToXEquallySpaced(
+  zones: FromTo[],
+  numberOfPoints: number,
+  options: XZonesEquallySpacedOptions = {},
+): Float64Array {
+  if (!zones || zones.length === 0) {
+    throw new RangeError('zones array must not be empty');
+  }
+
+  if (numberOfPoints < 1) {
+    throw new RangeError("'numberOfPoints' must be greater than 0");
+  }
+
+  const from = options.from ?? zones[0].from;
+  //@ts-expect-error zones is tested before
+  const to = options.to ?? zones.at(-1).to;
+
+  if (from > to) {
+    throw new RangeError('from should be less than or equal to to');
+  }
+
+  const normalizedZones = zonesNormalize(zones, { from, to, exclusions: [] });
+  const zonesWithPointsRes = zonesWithPoints(normalizedZones, numberOfPoints, {
+    from,
+    to,
+  }).filter((zone) => zone.numberOfPoints);
+
+  let xResult: number[] = [];
+  for (const zone of zonesWithPointsRes) {
+    if (!zone.numberOfPoints) {
+      zone.numberOfPoints = 0;
+    }
+
+    const zoneXValues = Array.from(
+      createFromToArray({
+        from: zone.from,
+        to: zone.to,
+        length: zone.numberOfPoints,
+        includeFrom: false,
+        includeTo: false,
+      }),
+    );
+
+    xResult = xResult.concat(zoneXValues);
+  }
+
+  return new Float64Array(xResult);
+}

vitest.config.ts

@@ -4,6 +4,7 @@ export default defineConfig({
   test: {
     coverage: {
       include: ['src/**'],
+      exclude: ['**/__tests__/data/**'],
     },
     setupFiles: ['vitest.setup.ts'],
   },