feat: add aggregation methods (mode, std, variance)

Author: a3ka

src/methods/aggregation/mode.js

@@ -0,0 +1,51 @@
+/**
+ * Finds the most frequent value in a column.
+ * If multiple values have the same highest frequency, returns the first one encountered.
+ *
+ * @param {{ validateColumn(frame, column): void }} deps
+ * @returns {(frame: TinyFrame, column: string) => any|null}
+ */
+export const mode =
+  ({ validateColumn }) =>
+  (frame, column) => {
+    validateColumn(frame, column);
+
+    const values = frame.columns[column];
+    const length = values.length;
+
+    if (length === 0) {
+      return null;
+    }
+
+    // Count frequency of each value
+    const counts = new Map();
+    let maxCount = 0;
+    let modeValue = null;
+    let hasValidValue = false;
+
+    for (let i = 0; i < length; i++) {
+      const value = values[i];
+
+      // Skip NaN, null, and undefined values
+      if (value === null || value === undefined || Number.isNaN(value)) {
+        continue;
+      }
+
+      hasValidValue = true;
+
+      // Get current count or initialize to 0
+      const count = counts.get(value) || 0;
+      const newCount = count + 1;
+
+      // Update the map with new count
+      counts.set(value, newCount);
+
+      // Update mode if this value has a higher frequency
+      if (newCount > maxCount) {
+        maxCount = newCount;
+        modeValue = value;
+      }
+    }
+
+    return hasValidValue ? modeValue : null;
+  };

src/methods/aggregation/std.js

@@ -0,0 +1,61 @@
+/**
+ * Calculates the standard deviation of values in a column.
+ * By default, calculates the population standard deviation.
+ * Set 'sample' parameter to true for sample standard deviation.
+ *
+ * @param {{ validateColumn(frame, column): void }} deps
+ * @returns {(frame: TinyFrame, column: string, options?: { sample?: boolean }) => number|null}
+ */
+export const std =
+  ({ validateColumn }) =>
+  (frame, column, options = {}) => {
+    validateColumn(frame, column);
+
+    const values = frame.columns[column];
+    const sample = options.sample || false;
+
+    // Filter out non-numeric values and convert to numbers
+    const numericValues = [];
+    for (let i = 0; i < values.length; i++) {
+      const value = values[i];
+      if (value === null || value === undefined || Number.isNaN(value)) {
+        continue;
+      }
+
+      const numValue = Number(value);
+      if (!Number.isNaN(numValue)) {
+        numericValues.push(numValue);
+      }
+    }
+
+    const length = numericValues.length;
+    if (length === 0) {
+      return null;
+    }
+
+    // Calculate mean
+    let sum = 0;
+    for (let i = 0; i < length; i++) {
+      sum += numericValues[i];
+    }
+    const mean = sum / length;
+
+    // Calculate sum of squared differences from the mean
+    let sumSquaredDiff = 0;
+    for (let i = 0; i < length; i++) {
+      const diff = numericValues[i] - mean;
+      sumSquaredDiff += diff * diff;
+    }
+
+    // For population standard deviation, divide by n
+    // For sample standard deviation, divide by (n-1)
+    const divisor = sample ? length - 1 : length;
+
+    // Handle edge case: if sample=true and there's only one value
+    if (divisor === 0) {
+      return null;
+    }
+
+    // Calculate standard deviation
+    return Math.sqrt(sumSquaredDiff / divisor);
+  };

src/methods/aggregation/variance.js

@@ -0,0 +1,61 @@
+/**
+ * Calculates the variance of values in a column.
+ * By default, calculates the population variance.
+ * Set 'sample' parameter to true for sample variance.
+ *
+ * @param {{ validateColumn(frame, column): void }} deps
+ * @returns {(frame: TinyFrame, column: string, options?: { sample?: boolean }) => number|null}
+ */
+export const variance =
+  ({ validateColumn }) =>
+  (frame, column, options = {}) => {
+    validateColumn(frame, column);
+
+    const values = frame.columns[column];
+    const sample = options.sample || false;
+
+    // Filter out non-numeric values and convert to numbers
+    const numericValues = [];
+    for (let i = 0; i < values.length; i++) {
+      const value = values[i];
+      if (value === null || value === undefined || Number.isNaN(value)) {
+        continue;
+      }
+
+      const numValue = Number(value);
+      if (!Number.isNaN(numValue)) {
+        numericValues.push(numValue);
+      }
+    }
+
+    const length = numericValues.length;
+    if (length === 0) {
+      return null;
+    }
+
+    // Calculate mean
+    let sum = 0;
+    for (let i = 0; i < length; i++) {
+      sum += numericValues[i];
+    }
+    const mean = sum / length;
+
+    // Calculate sum of squared differences from the mean
+    let sumSquaredDiff = 0;
+    for (let i = 0; i < length; i++) {
+      const diff = numericValues[i] - mean;
+      sumSquaredDiff += diff * diff;
+    }
+
+    // For population variance, divide by n
+    // For sample variance, divide by (n-1)
+    const divisor = sample ? length - 1 : length;
+
+    // Handle edge case: if sample=true and there's only one value
+    if (divisor === 0) {
+      return null;
+    }
+
+    // Calculate variance
+    return sumSquaredDiff / divisor;
+  };

src/methods/raw.js

@@ -10,3 +10,6 @@ export { min } from './aggregation/min.js';
 export { max } from './aggregation/max.js';
 export { last } from './aggregation/last.js';
 export { median } from './aggregation/median.js';
+export { mode } from './aggregation/mode.js';
+export { std } from './aggregation/std.js';
+export { variance } from './aggregation/variance.js';

test/methods/aggregation/mode.test.js

@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest';
+import { DataFrame } from '../../../src/core/DataFrame.js';
+import { mode } from '../../../src/methods/aggregation/mode.js';
+
+describe('mode method', () => {
+  // Create test data
+  const testData = [
+    { value: 30, category: 'A', mixed: '20' },
+    { value: 10, category: 'B', mixed: 30 },
+    { value: 30, category: 'A', mixed: null },
+    { value: 40, category: 'C', mixed: undefined },
+    { value: 30, category: 'B', mixed: NaN },
+    { value: 20, category: 'B', mixed: '20' },
+  ];
+
+  const df = DataFrame.create(testData);
+
+  it('should find the most frequent value in a column', () => {
+    // Call mode function directly
+    const modeFn = mode({ validateColumn: () => {} });
+    const result = modeFn(df._frame, 'value');
+
+    // Check that the mode is correct
+    expect(result).toBe(30); // 30 appears 3 times, more than any other value
+  });
+
+  it('should handle mixed data types by treating them as distinct', () => {
+    // Call mode function directly
+    const modeFn = mode({ validateColumn: () => {} });
+    const result = modeFn(df._frame, 'mixed');
+
+    // Check that the mode is correct (only valid values are considered)
+    expect(result).toBe('20'); // '20' appears twice (string '20', not number 20)
+  });
+
+  it('should return null for a column with no valid values', () => {
+    // Create data with only invalid values
+    const invalidData = [
+      { invalid: null },
+      { invalid: undefined },
+      { invalid: NaN },
+    ];
+
+    const invalidDf = DataFrame.create(invalidData);
+
+    // Call mode function directly
+    const modeFn = mode({ validateColumn: () => {} });
+    const result = modeFn(invalidDf._frame, 'invalid');
+
+    // Check that the result is null (no valid values)
+    expect(result).toBe(null);
+  });
+
+  it('should return the first encountered value if multiple values have the same highest frequency', () => {
+    // Create data with multiple modes
+    const multiModeData = [
+      { value: 10 },
+      { value: 20 },
+      { value: 10 },
+      { value: 30 },
+      { value: 20 },
+      { value: 30 },
+    ];
+
+    const multiModeDf = DataFrame.create(multiModeData);
+
+    // Call mode function directly
+    const modeFn = mode({ validateColumn: () => {} });
+    const result = modeFn(multiModeDf._frame, 'value');
+
+    // Check that one of the modes is returned (all appear twice)
+    expect([10, 20, 30]).toContain(result);
+  });
+
+  it('should throw an error for non-existent column', () => {
+    // Create a validator that throws an error for non-existent column
+    const validateColumn = (frame, column) => {
+      if (!(column in frame.columns)) {
+        throw new Error(`Column '${column}' not found`);
+      }
+    };
+
+    // Call mode function with validator
+    const modeFn = mode({ validateColumn });
+
+    // Check that it throws an error for non-existent column
+    expect(() => modeFn(df._frame, 'nonexistent')).toThrow(
+      "Column 'nonexistent' not found",
+    );
+  });
+
+  it('should handle empty frames', () => {
+    // Create an empty DataFrame
+    const emptyDf = DataFrame.create([]);
+
+    // Add an empty column
+    emptyDf._frame.columns.value = [];
+
+    // Call mode function directly
+    const modeFn = mode({ validateColumn: () => {} });
+    const result = modeFn(emptyDf._frame, 'value');
+
+    // Check that the result is null for empty column
+    expect(result).toBe(null);
+  });
+});