bun-scikit 0.1.1

package/src/model_selection/GridSearchCV.ts

@@ -0,0 +1,244 @@
+import type { Matrix, Vector } from "../types";
+import { accuracyScore, f1Score, precisionScore, recallScore } from "../metrics/classification";
+import { meanSquaredError, r2Score } from "../metrics/regression";
+import {
+  crossValScore,
+  type BuiltInScoring,
+  type CrossValEstimator,
+  type CrossValSplitter,
+  type ScoringFn,
+} from "./crossValScore";
+
+export type ParamGrid = Record<string, readonly unknown[]>;
+
+export interface GridSearchCVOptions {
+  cv?: number | CrossValSplitter;
+  scoring?: BuiltInScoring | ScoringFn;
+  refit?: boolean;
+  errorScore?: "raise" | number;
+}
+
+export interface GridSearchResultRow {
+  params: Record<string, unknown>;
+  splitScores: number[];
+  meanTestScore: number;
+  stdTestScore: number;
+  rank: number;
+  status: "ok" | "error";
+  errorMessage?: string;
+}
+
+function mean(values: number[]): number {
+  let sum = 0;
+  for (let i = 0; i < values.length; i += 1) {
+    sum += values[i];
+  }
+  return sum / values.length;
+}
+
+function std(values: number[]): number {
+  if (values.length < 2) {
+    return 0;
+  }
+  const avg = mean(values);
+  let sum = 0;
+  for (let i = 0; i < values.length; i += 1) {
+    const diff = values[i] - avg;
+    sum += diff * diff;
+  }
+  return Math.sqrt(sum / values.length);
+}
+
+function resolveBuiltInScorer(scoring: BuiltInScoring): ScoringFn {
+  switch (scoring) {
+    case "accuracy":
+      return accuracyScore;
+    case "f1":
+      return f1Score;
+    case "precision":
+      return precisionScore;
+    case "recall":
+      return recallScore;
+    case "r2":
+      return r2Score;
+    case "mean_squared_error":
+      return meanSquaredError;
+    case "neg_mean_squared_error":
+      return (yTrue, yPred) => -meanSquaredError(yTrue, yPred);
+    default: {
+      const exhaustive: never = scoring;
+      throw new Error(`Unsupported scoring metric: ${exhaustive}`);
+    }
+  }
+}
+
+function isLossMetric(scoring: BuiltInScoring | ScoringFn | undefined): boolean {
+  return scoring === "mean_squared_error";
+}
+
+function cartesianProduct(grid: ParamGrid): Record<string, unknown>[] {
+  const keys = Object.keys(grid);
+  if (keys.length === 0) {
+    throw new Error("paramGrid must include at least one parameter.");
+  }
+
+  for (let i = 0; i < keys.length; i += 1) {
+    const values = grid[keys[i]];
+    if (!Array.isArray(values) || values.length === 0) {
+      throw new Error(`paramGrid '${keys[i]}' must be a non-empty array.`);
+    }
+  }
+
+  const out: Record<string, unknown>[] = [];
+  const current: Record<string, unknown> = {};
+
+  function recurse(depth: number): void {
+    if (depth === keys.length) {
+      out.push({ ...current });
+      return;
+    }
+
+    const key = keys[depth];
+    const values = grid[key];
+    for (let i = 0; i < values.length; i += 1) {
+      current[key] = values[i];
+      recurse(depth + 1);
+    }
+  }
+
+  recurse(0);
+  return out;
+}
+
+export class GridSearchCV<TEstimator extends CrossValEstimator> {
+  bestEstimator_: TEstimator | null = null;
+  bestParams_: Record<string, unknown> | null = null;
+  bestScore_: number | null = null;
+  cvResults_: GridSearchResultRow[] = [];
+
+  private readonly estimatorFactory: (params: Record<string, unknown>) => TEstimator;
+  private readonly paramGrid: ParamGrid;
+  private readonly cv?: number | CrossValSplitter;
+  private readonly scoring?: BuiltInScoring | ScoringFn;
+  private readonly refit: boolean;
+  private readonly errorScore: "raise" | number;
+  private isFitted = false;
+
+  constructor(
+    estimatorFactory: (params: Record<string, unknown>) => TEstimator,
+    paramGrid: ParamGrid,
+    options: GridSearchCVOptions = {},
+  ) {
+    if (typeof estimatorFactory !== "function") {
+      throw new Error("estimatorFactory must be a function.");
+    }
+    this.estimatorFactory = estimatorFactory;
+    this.paramGrid = paramGrid;
+    this.cv = options.cv;
+    this.scoring = options.scoring;
+    this.refit = options.refit ?? true;
+    this.errorScore = options.errorScore ?? "raise";
+  }
+
+  fit(X: Matrix, y: Vector): this {
+    const candidates = cartesianProduct(this.paramGrid);
+    const minimize = isLossMetric(this.scoring);
+    const rows: GridSearchResultRow[] = [];
+    const objectiveScores: number[] = [];
+
+    for (let candidateIndex = 0; candidateIndex < candidates.length; candidateIndex += 1) {
+      const params = candidates[candidateIndex];
+      try {
+        const splitScores = crossValScore(
+          () => this.estimatorFactory(params),
+          X,
+          y,
+          { cv: this.cv, scoring: this.scoring },
+        );
+        const meanTestScore = mean(splitScores);
+        rows.push({
+          params: { ...params },
+          splitScores,
+          meanTestScore,
+          stdTestScore: std(splitScores),
+          rank: 0,
+          status: "ok",
+        });
+        objectiveScores.push(minimize ? -meanTestScore : meanTestScore);
+      } catch (error) {
+        if (this.errorScore === "raise") {
+          throw error;
+        }
+        rows.push({
+          params: { ...params },
+          splitScores: [this.errorScore],
+          meanTestScore: this.errorScore,
+          stdTestScore: 0,
+          rank: 0,
+          status: "error",
+          errorMessage: error instanceof Error ? error.message : String(error),
+        });
+        objectiveScores.push(minimize ? -this.errorScore : this.errorScore);
+      }
+    }
+
+    const order = Array.from({ length: rows.length }, (_, idx) => idx).sort((a, b) => {
+      const delta = objectiveScores[b] - objectiveScores[a];
+      if (delta !== 0) {
+        return delta;
+      }
+      return a - b;
+    });
+
+    for (let rank = 0; rank < order.length; rank += 1) {
+      rows[order[rank]].rank = rank + 1;
+    }
+
+    const bestIndex = order[0];
+    this.bestParams_ = { ...rows[bestIndex].params };
+    this.bestScore_ = rows[bestIndex].meanTestScore;
+    this.cvResults_ = rows;
+
+    if (this.refit) {
+      const estimator = this.estimatorFactory(this.bestParams_);
+      estimator.fit(X, y);
+      this.bestEstimator_ = estimator;
+    } else {
+      this.bestEstimator_ = null;
+    }
+
+    this.isFitted = true;
+    return this;
+  }
+
+  predict(X: Matrix): Vector {
+    if (!this.isFitted) {
+      throw new Error("GridSearchCV has not been fitted.");
+    }
+    if (!this.refit || !this.bestEstimator_) {
+      throw new Error("GridSearchCV predict is unavailable when refit=false.");
+    }
+    return this.bestEstimator_.predict(X);
+  }
+
+  score(X: Matrix, y: Vector): number {
+    if (!this.isFitted) {
+      throw new Error("GridSearchCV has not been fitted.");
+    }
+    if (!this.refit || !this.bestEstimator_) {
+      throw new Error("GridSearchCV score is unavailable when refit=false.");
+    }
+
+    if (this.scoring) {
+      const scorer =
+        typeof this.scoring === "function" ? this.scoring : resolveBuiltInScorer(this.scoring);
+      return scorer(y, this.bestEstimator_.predict(X));
+    }
+
+    if (typeof this.bestEstimator_.score === "function") {
+      return this.bestEstimator_.score(X, y);
+    }
+
+    throw new Error("No scoring function available. Provide scoring in GridSearchCV options.");
+  }
+}

package/src/model_selection/KFold.ts

@@ -0,0 +1,82 @@
+export interface FoldIndices {
+  trainIndices: number[];
+  testIndices: number[];
+}
+
+export interface KFoldOptions {
+  nSplits?: number;
+  shuffle?: boolean;
+  randomState?: number;
+}
+
+function mulberry32(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state += 0x6d2b79f5;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t ^= t + Math.imul(t ^ (t >>> 7), 61 | t);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function shuffleInPlace(indices: number[], seed: number): void {
+  const random = mulberry32(seed);
+  for (let i = indices.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(random() * (i + 1));
+    const tmp = indices[i];
+    indices[i] = indices[j];
+    indices[j] = tmp;
+  }
+}
+
+export class KFold {
+  private readonly nSplits: number;
+  private readonly shuffle: boolean;
+  private readonly randomState: number;
+
+  constructor(options: KFoldOptions = {}) {
+    this.nSplits = options.nSplits ?? 5;
+    this.shuffle = options.shuffle ?? false;
+    this.randomState = options.randomState ?? 42;
+
+    if (!Number.isInteger(this.nSplits) || this.nSplits < 2) {
+      throw new Error(`nSplits must be an integer >= 2. Got ${this.nSplits}.`);
+    }
+  }
+
+  split<TX>(X: TX[], y?: unknown[]): FoldIndices[] {
+    if (!Array.isArray(X) || X.length === 0) {
+      throw new Error("X must be a non-empty array.");
+    }
+    if (y && y.length !== X.length) {
+      throw new Error(`X and y must have the same length. Got ${X.length} and ${y.length}.`);
+    }
+    if (this.nSplits > X.length) {
+      throw new Error(`nSplits (${this.nSplits}) cannot exceed sample count (${X.length}).`);
+    }
+
+    const indices = Array.from({ length: X.length }, (_, idx) => idx);
+    if (this.shuffle) {
+      shuffleInPlace(indices, this.randomState);
+    }
+
+    const foldSizes = new Array<number>(this.nSplits).fill(Math.floor(X.length / this.nSplits));
+    const remainder = X.length % this.nSplits;
+    for (let i = 0; i < remainder; i += 1) {
+      foldSizes[i] += 1;
+    }
+
+    const folds: FoldIndices[] = [];
+    let start = 0;
+    for (let foldIdx = 0; foldIdx < this.nSplits; foldIdx += 1) {
+      const size = foldSizes[foldIdx];
+      const end = start + size;
+      const testIndices = indices.slice(start, end);
+      const trainIndices = indices.slice(0, start).concat(indices.slice(end));
+      folds.push({ trainIndices, testIndices });
+      start = end;
+    }
+
+    return folds;
+  }
+}

package/src/model_selection/RepeatedKFold.ts

@@ -0,0 +1,49 @@
+import { KFold, type FoldIndices } from "./KFold";
+
+export interface RepeatedKFoldOptions {
+  nSplits?: number;
+  nRepeats?: number;
+  randomState?: number;
+}
+
+export class RepeatedKFold {
+  private readonly nSplits: number;
+  private readonly nRepeats: number;
+  private readonly randomState: number;
+
+  constructor(options: RepeatedKFoldOptions = {}) {
+    this.nSplits = options.nSplits ?? 5;
+    this.nRepeats = options.nRepeats ?? 10;
+    this.randomState = options.randomState ?? 42;
+
+    if (!Number.isInteger(this.nSplits) || this.nSplits < 2) {
+      throw new Error(`nSplits must be an integer >= 2. Got ${this.nSplits}.`);
+    }
+    if (!Number.isInteger(this.nRepeats) || this.nRepeats < 1) {
+      throw new Error(`nRepeats must be an integer >= 1. Got ${this.nRepeats}.`);
+    }
+  }
+
+  split<TX>(X: TX[], y?: unknown[]): FoldIndices[] {
+    if (!Array.isArray(X) || X.length === 0) {
+      throw new Error("X must be a non-empty array.");
+    }
+    if (y && y.length !== X.length) {
+      throw new Error(`X and y must have the same length. Got ${X.length} and ${y.length}.`);
+    }
+
+    const allFolds: FoldIndices[] = [];
+    for (let repeat = 0; repeat < this.nRepeats; repeat += 1) {
+      const splitter = new KFold({
+        nSplits: this.nSplits,
+        shuffle: true,
+        randomState: this.randomState + repeat * 104_729,
+      });
+      const folds = splitter.split(X, y);
+      for (let i = 0; i < folds.length; i += 1) {
+        allFolds.push(folds[i]);
+      }
+    }
+    return allFolds;
+  }
+}

package/src/model_selection/RepeatedStratifiedKFold.ts

@@ -0,0 +1,50 @@
+import type { FoldIndices } from "./KFold";
+import { StratifiedKFold } from "./StratifiedKFold";
+
+export interface RepeatedStratifiedKFoldOptions {
+  nSplits?: number;
+  nRepeats?: number;
+  randomState?: number;
+}
+
+export class RepeatedStratifiedKFold {
+  private readonly nSplits: number;
+  private readonly nRepeats: number;
+  private readonly randomState: number;
+
+  constructor(options: RepeatedStratifiedKFoldOptions = {}) {
+    this.nSplits = options.nSplits ?? 5;
+    this.nRepeats = options.nRepeats ?? 10;
+    this.randomState = options.randomState ?? 42;
+
+    if (!Number.isInteger(this.nSplits) || this.nSplits < 2) {
+      throw new Error(`nSplits must be an integer >= 2. Got ${this.nSplits}.`);
+    }
+    if (!Number.isInteger(this.nRepeats) || this.nRepeats < 1) {
+      throw new Error(`nRepeats must be an integer >= 1. Got ${this.nRepeats}.`);
+    }
+  }
+
+  split<TX>(X: TX[], y: number[]): FoldIndices[] {
+    if (!Array.isArray(X) || X.length === 0) {
+      throw new Error("X must be a non-empty array.");
+    }
+    if (!Array.isArray(y) || y.length !== X.length) {
+      throw new Error(`X and y must have the same length. Got ${X.length} and ${y.length}.`);
+    }
+
+    const allFolds: FoldIndices[] = [];
+    for (let repeat = 0; repeat < this.nRepeats; repeat += 1) {
+      const splitter = new StratifiedKFold({
+        nSplits: this.nSplits,
+        shuffle: true,
+        randomState: this.randomState + repeat * 104_729,
+      });
+      const folds = splitter.split(X, y);
+      for (let i = 0; i < folds.length; i += 1) {
+        allFolds.push(folds[i]);
+      }
+    }
+    return allFolds;
+  }
+}

package/src/model_selection/StratifiedKFold.ts

@@ -0,0 +1,112 @@
+import type { FoldIndices } from "./KFold";
+
+export interface StratifiedKFoldOptions {
+  nSplits?: number;
+  shuffle?: boolean;
+  randomState?: number;
+}
+
+function mulberry32(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state += 0x6d2b79f5;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t ^= t + Math.imul(t ^ (t >>> 7), 61 | t);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function shuffleInPlace(indices: number[], random: () => number): void {
+  for (let i = indices.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(random() * (i + 1));
+    const tmp = indices[i];
+    indices[i] = indices[j];
+    indices[j] = tmp;
+  }
+}
+
+export class StratifiedKFold {
+  private readonly nSplits: number;
+  private readonly shuffle: boolean;
+  private readonly randomState: number;
+
+  constructor(options: StratifiedKFoldOptions = {}) {
+    this.nSplits = options.nSplits ?? 5;
+    this.shuffle = options.shuffle ?? false;
+    this.randomState = options.randomState ?? 42;
+
+    if (!Number.isInteger(this.nSplits) || this.nSplits < 2) {
+      throw new Error(`nSplits must be an integer >= 2. Got ${this.nSplits}.`);
+    }
+  }
+
+  split<TX>(X: TX[], y: number[]): FoldIndices[] {
+    if (!Array.isArray(X) || X.length === 0) {
+      throw new Error("X must be a non-empty array.");
+    }
+    if (!Array.isArray(y) || y.length !== X.length) {
+      throw new Error(`X and y must have the same length. Got ${X.length} and ${y.length}.`);
+    }
+    if (this.nSplits > X.length) {
+      throw new Error(`nSplits (${this.nSplits}) cannot exceed sample count (${X.length}).`);
+    }
+
+    const byClass = new Map<number, number[]>();
+    for (let i = 0; i < y.length; i += 1) {
+      const label = y[i];
+      const bucket = byClass.get(label);
+      if (bucket) {
+        bucket.push(i);
+      } else {
+        byClass.set(label, [i]);
+      }
+    }
+
+    if (byClass.size < 2) {
+      throw new Error("StratifiedKFold requires at least two distinct classes.");
+    }
+
+    let minClassCount = Number.POSITIVE_INFINITY;
+    for (const indices of byClass.values()) {
+      if (indices.length < minClassCount) {
+        minClassCount = indices.length;
+      }
+    }
+    if (minClassCount < this.nSplits) {
+      throw new Error(
+        `nSplits (${this.nSplits}) cannot exceed the smallest class count (${minClassCount}).`,
+      );
+    }
+
+    const foldTestIndices = Array.from({ length: this.nSplits }, () => new Array<number>());
+    const random = mulberry32(this.randomState);
+
+    for (const classIndices of byClass.values()) {
+      const working = classIndices.slice();
+      if (this.shuffle) {
+        shuffleInPlace(working, random);
+      }
+      for (let i = 0; i < working.length; i += 1) {
+        foldTestIndices[i % this.nSplits].push(working[i]);
+      }
+    }
+
+    const folds: FoldIndices[] = [];
+    for (let foldIdx = 0; foldIdx < this.nSplits; foldIdx += 1) {
+      const testIndices = foldTestIndices[foldIdx].slice().sort((a, b) => a - b);
+      const testMask = new Uint8Array(X.length);
+      for (let i = 0; i < testIndices.length; i += 1) {
+        testMask[testIndices[i]] = 1;
+      }
+      const trainIndices = new Array<number>();
+      for (let i = 0; i < X.length; i += 1) {
+        if (testMask[i] === 0) {
+          trainIndices.push(i);
+        }
+      }
+      folds.push({ trainIndices, testIndices });
+    }
+
+    return folds;
+  }
+}