feat: add xyMedianY and xyMedianYAtXs methods

closes: #352

Author: lpatiny

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

@@ -108,6 +108,8 @@ exports[`existence of exported functions 1`] = `
   "xyMaxY",
   "xyMaxYPoint",
   "xyMedian",
+  "xyMedianY",
+  "xyMedianYAtXs",
   "xyMergeByCentroids",
   "xyMinClosestYPoint",
   "xyMinimaY",

src/xy/__tests__/xyMedianY.test.ts

@@ -0,0 +1,95 @@
+import { expect, test } from 'vitest';
+
+import { xyMedianY } from '../xyMedianY.ts';
+
+test('default window size of 5', () => {
+  const data = {
+    x: [1, 2, 3, 4, 5, 6, 7],
+    y: [1, 3, 2, 100, 4, 5, 6],
+  };
+
+  const result = xyMedianY(data);
+
+  expect(result.x).toBe(data.x);
+  expect(result.y).toStrictEqual(new Float64Array([2, 2, 3, 4, 5, 5, 5]));
+});
+
+test('window size of 3', () => {
+  const data = {
+    x: [1, 2, 3, 4, 5],
+    y: [10, 1, 5, 3, 8],
+  };
+
+  const result = xyMedianY(data, { windowSize: 3 });
+
+  expect(result.y).toStrictEqual(new Float64Array([1, 5, 3, 5, 3]));
+});
+
+test('window size of 1 returns original values', () => {
+  const data = {
+    x: [1, 2, 3],
+    y: [10, 20, 30],
+  };
+
+  const result = xyMedianY(data, { windowSize: 1 });
+
+  expect(result.y).toStrictEqual(new Float64Array([10, 20, 30]));
+});
+
+test('single point', () => {
+  const data = {
+    x: [5],
+    y: [42],
+  };
+
+  const result = xyMedianY(data);
+
+  expect(result.y).toStrictEqual(new Float64Array([42]));
+});
+
+test('even number of elements in window returns average of middle two', () => {
+  const data = {
+    x: [1, 2, 3, 4],
+    y: [1, 4, 2, 3],
+  };
+
+  // window size 3, at edges the window has 2 elements (even)
+  const result = xyMedianY(data, { windowSize: 3 });
+
+  // i=0: [1,4] -> median 1 (lower middle, exact: false)
+  // i=1: [1,4,2] -> median 2
+  // i=2: [4,2,3] -> median 3
+  // i=3: [2,3] -> median 2 (lower middle, exact: false)
+  expect(result.y).toStrictEqual(new Float64Array([1, 2, 3, 2]));
+});
+
+test('empty data', () => {
+  const data = {
+    x: [],
+    y: [],
+  };
+
+  const result = xyMedianY(data);
+
+  expect(result.y).toStrictEqual(new Float64Array([]));
+});
+
+test('does not mutate original Float64Array y data', () => {
+  const y = new Float64Array([10, 1, 5, 3, 8]);
+  const yOriginal = new Float64Array(y);
+  const data = { x: [1, 2, 3, 4, 5], y };
+
+  xyMedianY(data, { windowSize: 3 });
+
+  expect(y).toStrictEqual(yOriginal);
+});
+
+test('does not mutate original plain array y data', () => {
+  const y = [10, 1, 5, 3, 8];
+  const yOriginal = [...y];
+  const data = { x: [1, 2, 3, 4, 5], y };
+
+  xyMedianY(data, { windowSize: 3 });
+
+  expect(y).toStrictEqual(yOriginal);
+});

src/xy/__tests__/xyMedianYAtXs.test.ts

@@ -0,0 +1,72 @@
+import { expect, test } from 'vitest';
+
+import { xyMedianYAtXs } from '../xyMedianYAtXs.ts';
+
+test('median at specific x values with window size 5', () => {
+  const data = {
+    x: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    y: [2, 8, 3, 100, 5, 6, 1, 9, 4, 7],
+  };
+
+  const result = xyMedianYAtXs(data, [3, 7]);
+
+  expect(result.x).toStrictEqual([3, 7]);
+  expect(result.y).toStrictEqual(new Float64Array([5, 5]));
+});
+
+test('median at x values not exactly in data uses closest index', () => {
+  const data = {
+    x: [1, 2, 3, 4, 5],
+    y: [10, 1, 5, 3, 8],
+  };
+
+  // 2.8 is closest to x=3 (index 2)
+  const result = xyMedianYAtXs(data, [2.8], { windowSize: 3 });
+
+  expect(result.y).toStrictEqual(new Float64Array([3]));
+});
+
+test('window size of 1 returns the y value at the closest x', () => {
+  const data = {
+    x: [1, 2, 3, 4, 5],
+    y: [10, 20, 30, 40, 50],
+  };
+
+  const result = xyMedianYAtXs(data, [2, 4], { windowSize: 1 });
+
+  expect(result.y).toStrictEqual(new Float64Array([20, 40]));
+});
+
+test('window at edges is truncated', () => {
+  const data = {
+    x: [1, 2, 3, 4, 5],
+    y: [10, 1, 5, 3, 8],
+  };
+
+  const result = xyMedianYAtXs(data, [1, 5], { windowSize: 5 });
+
+  // index 0: window [10,1,5] -> median 5
+  // index 4: window [5,3,8] -> median 5
+  expect(result.y).toStrictEqual(new Float64Array([5, 5]));
+});
+
+test('does not mutate original Float64Array y data', () => {
+  const y = new Float64Array([10, 1, 5, 3, 8]);
+  const yOriginal = new Float64Array(y);
+  const data = { x: [1, 2, 3, 4, 5], y };
+
+  xyMedianYAtXs(data, [2, 4], { windowSize: 3 });
+
+  expect(y).toStrictEqual(yOriginal);
+});
+
+test('empty xValues returns empty result', () => {
+  const data = {
+    x: [1, 2, 3],
+    y: [10, 20, 30],
+  };
+
+  const result = xyMedianYAtXs(data, []);
+
+  expect(result.y).toStrictEqual(new Float64Array([]));
+});

src/xy/index.ts

@@ -25,6 +25,8 @@ export * from './xyMaxMerge.ts';
 export * from './xyMaxY.ts';
 export * from './xyMaxYPoint.ts';
 export * from './xyMedian.ts';
+export * from './xyMedianY.ts';
+export * from './xyMedianYAtXs.ts';
 export * from './xyMergeByCentroids.ts';
 export * from './xyMinClosestYPoint.ts';
 export * from './xyMinimaY.ts';

src/xy/xyMedian.ts

@@ -1,9 +1,11 @@
 import type { DataXY } from 'cheminfo-types';
 
 /**
- * Finds the median x value for an object with properties x and y (arrays of the same length)
- * @param data - x should be sorted in increasing order
- * @returns - the median of x values
+ * Computes the weighted median of the x values, using the y values as weights.
+ * This is the x value that splits the total weight (sum of y) into two equal halves.
+ * If the cumulative weight lands exactly at 50%, the result is the average of the two surrounding x values.
+ * @param data - x should be sorted in increasing order, y values are used as weights and should be non-negative.
+ * @returns The weighted median x value, or NaN if the data is empty.
  */
 export function xyMedian(data: DataXY): number {
   const { x, y } = data;

src/xy/xyMedianY.ts

@@ -0,0 +1,36 @@
+import type { DataXY } from 'cheminfo-types';
+
+import { xMedian } from '../x/xMedian.ts';
+
+export interface XYMedianYOptions {
+  /** Number of points in the sliding window. Must be odd. Defaults to `5`. */
+  windowSize?: number;
+}
+
+/**
+ * Computes the median of Y values in a sliding window around each point.
+ * @param data - Object with x and y arrays of the same length.
+ * @param options - Options for the median computation.
+ * @returns A new DataXY with the same x values and smoothed y values.
+ */
+export function xyMedianY(
+  data: DataXY,
+  options: XYMedianYOptions = {},
+): DataXY {
+  const { windowSize = 5 } = options;
+  const { x, y } = data;
+
+  const halfWindow = Math.floor(windowSize / 2);
+  const result = new Float64Array(y.length);
+
+  for (let i = 0; i < y.length; i++) {
+    const fromIndex = Math.max(0, i - halfWindow);
+    const toIndex = Math.min(y.length, i + halfWindow + 1);
+    const window = ArrayBuffer.isView(y)
+      ? y.subarray(fromIndex, toIndex)
+      : y.slice(fromIndex, toIndex);
+    result[i] = xMedian(window, { exact: false });
+  }
+
+  return { x, y: result };
+}

src/xy/xyMedianYAtXs.ts

@@ -0,0 +1,42 @@
+import type { DataXY, NumberArray } from 'cheminfo-types';
+
+import { xFindClosestIndex } from '../x/xFindClosestIndex.ts';
+import { xMedian } from '../x/xMedian.ts';
+
+export interface XYMedianYAtXsOptions {
+  /** Number of points in the sliding window. Must be odd. Defaults to `5`. */
+  windowSize?: number;
+}
+
+/**
+ * Computes the median of Y values in a sliding window around each target x position.
+ * For each value in xValues, the closest index in data.x is found and the median
+ * of the surrounding y values (within the window) is returned.
+ * @param data - Object with x (sorted in increasing order) and y arrays of the same length.
+ * @param xValues - Array of x positions at which to compute the median.
+ * @param options - Options for the median computation.
+ * @returns A new DataXY with x = xValues and y = computed medians.
+ */
+export function xyMedianYAtXs(
+  data: DataXY,
+  xValues: NumberArray,
+  options: XYMedianYAtXsOptions = {},
+): DataXY {
+  const { windowSize = 5 } = options;
+  const { x, y } = data;
+
+  const halfWindow = Math.floor(windowSize / 2);
+  const result = new Float64Array(xValues.length);
+
+  for (let i = 0; i < xValues.length; i++) {
+    const centerIndex = xFindClosestIndex(x, xValues[i]);
+    const fromIndex = Math.max(0, centerIndex - halfWindow);
+    const toIndex = Math.min(y.length, centerIndex + halfWindow + 1);
+    const window = ArrayBuffer.isView(y)
+      ? y.subarray(fromIndex, toIndex)
+      : y.slice(fromIndex, toIndex);
+    result[i] = xMedian(window, { exact: false });
+  }
+
+  return { x: xValues, y: result };
+}