bun-scikit 0.1.1

package/src/linear_model/SGDClassifier.ts

@@ -0,0 +1,161 @@
+import type { ClassificationModel, Matrix, Vector } from "../types";
+import { accuracyScore } from "../metrics/classification";
+import { dot } from "../utils/linalg";
+import {
+  assertConsistentRowSize,
+  assertFiniteMatrix,
+  assertFiniteVector,
+  validateClassificationInputs,
+} from "../utils/validation";
+
+export type SGDClassifierLoss = "hinge" | "log_loss";
+
+export interface SGDClassifierOptions {
+  loss?: SGDClassifierLoss;
+  fitIntercept?: boolean;
+  learningRate?: number;
+  maxIter?: number;
+  tolerance?: number;
+  l2?: number;
+}
+
+function sigmoid(z: number): number {
+  if (z >= 0) {
+    const expNeg = Math.exp(-z);
+    return 1 / (1 + expNeg);
+  }
+  const expPos = Math.exp(z);
+  return expPos / (1 + expPos);
+}
+
+export class SGDClassifier implements ClassificationModel {
+  coef_: Vector = [];
+  intercept_ = 0;
+  classes_: Vector = [0, 1];
+
+  private readonly loss: SGDClassifierLoss;
+  private readonly fitIntercept: boolean;
+  private readonly learningRate: number;
+  private readonly maxIter: number;
+  private readonly tolerance: number;
+  private readonly l2: number;
+  private isFitted = false;
+
+  constructor(options: SGDClassifierOptions = {}) {
+    this.loss = options.loss ?? "hinge";
+    this.fitIntercept = options.fitIntercept ?? true;
+    this.learningRate = options.learningRate ?? 0.05;
+    this.maxIter = options.maxIter ?? 10_000;
+    this.tolerance = options.tolerance ?? 1e-6;
+    this.l2 = options.l2 ?? 0;
+  }
+
+  fit(X: Matrix, y: Vector): this {
+    validateClassificationInputs(X, y);
+    const nSamples = X.length;
+    const nFeatures = X[0].length;
+    const ySigned = y.map((value) => (value === 1 ? 1 : -1));
+
+    this.coef_ = new Array<number>(nFeatures).fill(0);
+    this.intercept_ = 0;
+
+    for (let iter = 0; iter < this.maxIter; iter += 1) {
+      const gradients = new Array<number>(nFeatures).fill(0);
+      let interceptGradient = 0;
+
+      for (let i = 0; i < nSamples; i += 1) {
+        const score = dot(X[i], this.coef_) + this.intercept_;
+
+        if (this.loss === "hinge") {
+          const margin = ySigned[i] * score;
+          if (margin < 1) {
+            const factor = -ySigned[i];
+            for (let j = 0; j < nFeatures; j += 1) {
+              gradients[j] += factor * X[i][j];
+            }
+            if (this.fitIntercept) {
+              interceptGradient += factor;
+            }
+          }
+        } else {
+          const p = sigmoid(score);
+          const error = p - y[i];
+          for (let j = 0; j < nFeatures; j += 1) {
+            gradients[j] += error * X[i][j];
+          }
+          if (this.fitIntercept) {
+            interceptGradient += error;
+          }
+        }
+      }
+
+      let maxUpdate = 0;
+      for (let j = 0; j < nFeatures; j += 1) {
+        const grad = gradients[j] / nSamples + this.l2 * this.coef_[j];
+        const delta = this.learningRate * grad;
+        this.coef_[j] -= delta;
+        const absDelta = Math.abs(delta);
+        if (absDelta > maxUpdate) {
+          maxUpdate = absDelta;
+        }
+      }
+
+      if (this.fitIntercept) {
+        const interceptDelta = this.learningRate * (interceptGradient / nSamples);
+        this.intercept_ -= interceptDelta;
+        const absInterceptDelta = Math.abs(interceptDelta);
+        if (absInterceptDelta > maxUpdate) {
+          maxUpdate = absInterceptDelta;
+        }
+      }
+
+      if (maxUpdate < this.tolerance) {
+        break;
+      }
+    }
+
+    this.isFitted = true;
+    return this;
+  }
+
+  predictProba(X: Matrix): Matrix {
+    if (this.loss !== "log_loss") {
+      throw new Error("predictProba is only available when loss='log_loss'.");
+    }
+    if (!this.isFitted) {
+      throw new Error("SGDClassifier has not been fitted.");
+    }
+    assertConsistentRowSize(X);
+    assertFiniteMatrix(X);
+    if (X[0].length !== this.coef_.length) {
+      throw new Error(`Feature size mismatch. Expected ${this.coef_.length}, got ${X[0].length}.`);
+    }
+
+    return X.map((row) => {
+      const positive = sigmoid(dot(row, this.coef_) + this.intercept_);
+      return [1 - positive, positive];
+    });
+  }
+
+  predict(X: Matrix): Vector {
+    if (!this.isFitted) {
+      throw new Error("SGDClassifier has not been fitted.");
+    }
+    assertConsistentRowSize(X);
+    assertFiniteMatrix(X);
+    if (X[0].length !== this.coef_.length) {
+      throw new Error(`Feature size mismatch. Expected ${this.coef_.length}, got ${X[0].length}.`);
+    }
+
+    if (this.loss === "log_loss") {
+      return this.predictProba(X).map((pair) => (pair[1] >= 0.5 ? 1 : 0));
+    }
+
+    return X.map((row) => (dot(row, this.coef_) + this.intercept_ >= 0 ? 1 : 0));
+  }
+
+  score(X: Matrix, y: Vector): number {
+    assertFiniteVector(y);
+    return accuracyScore(y, this.predict(X));
+  }
+}

package/src/linear_model/SGDRegressor.ts

@@ -0,0 +1,104 @@
+import type { Matrix, RegressionModel, Vector } from "../types";
+import { r2Score } from "../metrics/regression";
+import { dot } from "../utils/linalg";
+import {
+  assertConsistentRowSize,
+  assertFiniteMatrix,
+  assertFiniteVector,
+  validateRegressionInputs,
+} from "../utils/validation";
+
+export interface SGDRegressorOptions {
+  fitIntercept?: boolean;
+  learningRate?: number;
+  maxIter?: number;
+  tolerance?: number;
+  l2?: number;
+}
+
+export class SGDRegressor implements RegressionModel {
+  coef_: Vector = [];
+  intercept_ = 0;
+
+  private readonly fitIntercept: boolean;
+  private readonly learningRate: number;
+  private readonly maxIter: number;
+  private readonly tolerance: number;
+  private readonly l2: number;
+  private isFitted = false;
+
+  constructor(options: SGDRegressorOptions = {}) {
+    this.fitIntercept = options.fitIntercept ?? true;
+    this.learningRate = options.learningRate ?? 0.05;
+    this.maxIter = options.maxIter ?? 10_000;
+    this.tolerance = options.tolerance ?? 1e-6;
+    this.l2 = options.l2 ?? 0;
+  }
+
+  fit(X: Matrix, y: Vector): this {
+    validateRegressionInputs(X, y);
+    const nSamples = X.length;
+    const nFeatures = X[0].length;
+    this.coef_ = new Array<number>(nFeatures).fill(0);
+    this.intercept_ = 0;
+
+    for (let iter = 0; iter < this.maxIter; iter += 1) {
+      const gradients = new Array<number>(nFeatures).fill(0);
+      let interceptGradient = 0;
+
+      for (let i = 0; i < nSamples; i += 1) {
+        const prediction = dot(X[i], this.coef_) + this.intercept_;
+        const error = prediction - y[i];
+        for (let j = 0; j < nFeatures; j += 1) {
+          gradients[j] += error * X[i][j];
+        }
+        if (this.fitIntercept) {
+          interceptGradient += error;
+        }
+      }
+
+      let maxUpdate = 0;
+      for (let j = 0; j < nFeatures; j += 1) {
+        const grad = gradients[j] / nSamples + this.l2 * this.coef_[j];
+        const delta = this.learningRate * grad;
+        this.coef_[j] -= delta;
+        const absDelta = Math.abs(delta);
+        if (absDelta > maxUpdate) {
+          maxUpdate = absDelta;
+        }
+      }
+      if (this.fitIntercept) {
+        const interceptDelta = this.learningRate * (interceptGradient / nSamples);
+        this.intercept_ -= interceptDelta;
+        const absInterceptDelta = Math.abs(interceptDelta);
+        if (absInterceptDelta > maxUpdate) {
+          maxUpdate = absInterceptDelta;
+        }
+      }
+
+      if (maxUpdate < this.tolerance) {
+        break;
+      }
+    }
+
+    this.isFitted = true;
+    return this;
+  }
+
+  predict(X: Matrix): Vector {
+    if (!this.isFitted) {
+      throw new Error("SGDRegressor has not been fitted.");
+    }
+    assertConsistentRowSize(X);
+    assertFiniteMatrix(X);
+    if (X[0].length !== this.coef_.length) {
+      throw new Error(`Feature size mismatch. Expected ${this.coef_.length}, got ${X[0].length}.`);
+    }
+    return X.map((row) => dot(row, this.coef_) + this.intercept_);
+  }
+
+  score(X: Matrix, y: Vector): number {
+    assertFiniteVector(y);
+    return r2Score(y, this.predict(X));
+  }
+}

package/src/metrics/classification.ts

@@ -0,0 +1,294 @@
+function validateInputs(yTrue: number[], yPred: number[]): void {
+  if (yTrue.length === 0 || yPred.length === 0) {
+    throw new Error("yTrue and yPred must be non-empty.");
+  }
+
+  if (yTrue.length !== yPred.length) {
+    throw new Error(`Length mismatch: yTrue=${yTrue.length}, yPred=${yPred.length}.`);
+  }
+}
+
+function validateBinaryTargets(yTrue: number[]): void {
+  for (let i = 0; i < yTrue.length; i += 1) {
+    const value = yTrue[i];
+    if (!(value === 0 || value === 1)) {
+      throw new Error(`Binary classification target expected (0/1). Found ${value} at index ${i}.`);
+    }
+  }
+}
+
+function clampProbability(value: number, eps: number): number {
+  if (!Number.isFinite(value)) {
+    throw new Error(`Probability must be finite. Got ${value}.`);
+  }
+  if (value < eps) {
+    return eps;
+  }
+  if (value > 1 - eps) {
+    return 1 - eps;
+  }
+  return value;
+}
+
+function confusionCounts(yTrue: number[], yPred: number[], positiveLabel: number): {
+  tp: number;
+  fp: number;
+  fn: number;
+  tn: number;
+} {
+  validateInputs(yTrue, yPred);
+
+  let tp = 0;
+  let fp = 0;
+  let fn = 0;
+  let tn = 0;
+
+  for (let i = 0; i < yTrue.length; i += 1) {
+    const truthPositive = yTrue[i] === positiveLabel;
+    const predPositive = yPred[i] === positiveLabel;
+
+    if (truthPositive && predPositive) {
+      tp += 1;
+    } else if (!truthPositive && predPositive) {
+      fp += 1;
+    } else if (truthPositive && !predPositive) {
+      fn += 1;
+    } else {
+      tn += 1;
+    }
+  }
+
+  return { tp, fp, fn, tn };
+}
+
+export interface ConfusionMatrixResult {
+  labels: number[];
+  matrix: number[][];
+}
+
+export interface ClassificationReportLabelMetrics {
+  precision: number;
+  recall: number;
+  f1Score: number;
+  support: number;
+}
+
+export interface ClassificationReportResult {
+  labels: number[];
+  perLabel: Record<string, ClassificationReportLabelMetrics>;
+  accuracy: number;
+  macroAvg: ClassificationReportLabelMetrics;
+  weightedAvg: ClassificationReportLabelMetrics;
+}
+
+export function accuracyScore(yTrue: number[], yPred: number[]): number {
+  validateInputs(yTrue, yPred);
+  let correct = 0;
+  for (let i = 0; i < yTrue.length; i += 1) {
+    if (yTrue[i] === yPred[i]) {
+      correct += 1;
+    }
+  }
+  return correct / yTrue.length;
+}
+
+export function precisionScore(
+  yTrue: number[],
+  yPred: number[],
+  positiveLabel = 1,
+): number {
+  const { tp, fp } = confusionCounts(yTrue, yPred, positiveLabel);
+  const denominator = tp + fp;
+  if (denominator === 0) {
+    return 0;
+  }
+  return tp / denominator;
+}
+
+export function recallScore(yTrue: number[], yPred: number[], positiveLabel = 1): number {
+  const { tp, fn } = confusionCounts(yTrue, yPred, positiveLabel);
+  const denominator = tp + fn;
+  if (denominator === 0) {
+    return 0;
+  }
+  return tp / denominator;
+}
+
+export function f1Score(yTrue: number[], yPred: number[], positiveLabel = 1): number {
+  const precision = precisionScore(yTrue, yPred, positiveLabel);
+  const recall = recallScore(yTrue, yPred, positiveLabel);
+  const denominator = precision + recall;
+  if (denominator === 0) {
+    return 0;
+  }
+  return (2 * precision * recall) / denominator;
+}
+
+export function confusionMatrix(
+  yTrue: number[],
+  yPred: number[],
+  labels?: number[],
+): ConfusionMatrixResult {
+  validateInputs(yTrue, yPred);
+  const resolvedLabels =
+    labels && labels.length > 0
+      ? labels.slice()
+      : Array.from(new Set([...yTrue, ...yPred])).sort((a, b) => a - b);
+  if (resolvedLabels.length === 0) {
+    throw new Error("confusionMatrix requires at least one label.");
+  }
+
+  const labelToIndex = new Map<number, number>();
+  for (let i = 0; i < resolvedLabels.length; i += 1) {
+    labelToIndex.set(resolvedLabels[i], i);
+  }
+
+  const matrix = Array.from({ length: resolvedLabels.length }, () =>
+    new Array<number>(resolvedLabels.length).fill(0),
+  );
+
+  for (let i = 0; i < yTrue.length; i += 1) {
+    const trueLabel = yTrue[i];
+    const predLabel = yPred[i];
+    const trueIndex = labelToIndex.get(trueLabel);
+    const predIndex = labelToIndex.get(predLabel);
+    if (trueIndex === undefined || predIndex === undefined) {
+      continue;
+    }
+    matrix[trueIndex][predIndex] += 1;
+  }
+
+  return { labels: resolvedLabels, matrix };
+}
+
+export function logLoss(yTrue: number[], yPredProb: number[], eps = 1e-15): number {
+  validateInputs(yTrue, yPredProb);
+  validateBinaryTargets(yTrue);
+  if (!Number.isFinite(eps) || eps <= 0 || eps >= 0.5) {
+    throw new Error(`eps must be finite and in (0, 0.5). Got ${eps}.`);
+  }
+
+  let total = 0;
+  for (let i = 0; i < yTrue.length; i += 1) {
+    const p1 = clampProbability(yPredProb[i], eps);
+    const p0 = 1 - p1;
+    total += -(yTrue[i] * Math.log(p1) + (1 - yTrue[i]) * Math.log(p0));
+  }
+
+  return total / yTrue.length;
+}
+
+export function rocAucScore(yTrue: number[], yScore: number[]): number {
+  validateInputs(yTrue, yScore);
+  validateBinaryTargets(yTrue);
+
+  let positiveCount = 0;
+  for (let i = 0; i < yTrue.length; i += 1) {
+    if (yTrue[i] === 1) {
+      positiveCount += 1;
+    }
+  }
+  const negativeCount = yTrue.length - positiveCount;
+  if (positiveCount === 0 || negativeCount === 0) {
+    throw new Error("rocAucScore requires both positive and negative samples.");
+  }
+
+  const pairs = yScore.map((score, idx) => ({ score, label: yTrue[idx] }));
+  pairs.sort((a, b) => a.score - b.score);
+
+  // Average ranks for ties.
+  const ranks = new Array<number>(pairs.length);
+  let cursor = 0;
+  while (cursor < pairs.length) {
+    let tieEnd = cursor + 1;
+    while (tieEnd < pairs.length && pairs[tieEnd].score === pairs[cursor].score) {
+      tieEnd += 1;
+    }
+    const startRank = cursor + 1;
+    const endRank = tieEnd;
+    const averageRank = 0.5 * (startRank + endRank);
+    for (let i = cursor; i < tieEnd; i += 1) {
+      ranks[i] = averageRank;
+    }
+    cursor = tieEnd;
+  }
+
+  let rankSumPositives = 0;
+  for (let i = 0; i < pairs.length; i += 1) {
+    if (pairs[i].label === 1) {
+      rankSumPositives += ranks[i];
+    }
+  }
+
+  const u = rankSumPositives - (positiveCount * (positiveCount + 1)) / 2;
+  return u / (positiveCount * negativeCount);
+}
+
+export function classificationReport(
+  yTrue: number[],
+  yPred: number[],
+  labels?: number[],
+): ClassificationReportResult {
+  validateInputs(yTrue, yPred);
+
+  const { labels: resolvedLabels, matrix } = confusionMatrix(yTrue, yPred, labels);
+  const perLabel: Record<string, ClassificationReportLabelMetrics> = {};
+
+  let macroPrecision = 0;
+  let macroRecall = 0;
+  let macroF1 = 0;
+  let weightedPrecision = 0;
+  let weightedRecall = 0;
+  let weightedF1 = 0;
+
+  for (let labelIndex = 0; labelIndex < resolvedLabels.length; labelIndex += 1) {
+    const label = resolvedLabels[labelIndex];
+    let rowSum = 0;
+    let colSum = 0;
+    for (let j = 0; j < resolvedLabels.length; j += 1) {
+      rowSum += matrix[labelIndex][j];
+      colSum += matrix[j][labelIndex];
+    }
+
+    const tp = matrix[labelIndex][labelIndex];
+    const precision = colSum === 0 ? 0 : tp / colSum;
+    const recall = rowSum === 0 ? 0 : tp / rowSum;
+    const denom = precision + recall;
+    const f1 = denom === 0 ? 0 : (2 * precision * recall) / denom;
+
+    perLabel[String(label)] = {
+      precision,
+      recall,
+      f1Score: f1,
+      support: rowSum,
+    };
+
+    macroPrecision += precision;
+    macroRecall += recall;
+    macroF1 += f1;
+    weightedPrecision += precision * rowSum;
+    weightedRecall += recall * rowSum;
+    weightedF1 += f1 * rowSum;
+  }
+
+  const nLabels = resolvedLabels.length;
+  const totalSupport = yTrue.length;
+
+  return {
+    labels: resolvedLabels,
+    perLabel,
+    accuracy: accuracyScore(yTrue, yPred),
+    macroAvg: {
+      precision: macroPrecision / nLabels,
+      recall: macroRecall / nLabels,
+      f1Score: macroF1 / nLabels,
+      support: totalSupport,
+    },
+    weightedAvg: {
+      precision: weightedPrecision / totalSupport,
+      recall: weightedRecall / totalSupport,
+      f1Score: weightedF1 / totalSupport,
+      support: totalSupport,
+    },
+  };
+}

package/src/metrics/regression.ts

@@ -0,0 +1,51 @@
+import { mean } from "../utils/linalg";
+
+function validateInputs(yTrue: number[], yPred: number[]): void {
+  if (yTrue.length === 0 || yPred.length === 0) {
+    throw new Error("yTrue and yPred must be non-empty.");
+  }
+
+  if (yTrue.length !== yPred.length) {
+    throw new Error(`Length mismatch: yTrue=${yTrue.length}, yPred=${yPred.length}.`);
+  }
+}
+
+export function meanSquaredError(yTrue: number[], yPred: number[]): number {
+  validateInputs(yTrue, yPred);
+  let total = 0;
+  for (let i = 0; i < yTrue.length; i += 1) {
+    const diff = yTrue[i] - yPred[i];
+    total += diff * diff;
+  }
+  return total / yTrue.length;
+}
+
+export function meanAbsoluteError(yTrue: number[], yPred: number[]): number {
+  validateInputs(yTrue, yPred);
+  let total = 0;
+  for (let i = 0; i < yTrue.length; i += 1) {
+    total += Math.abs(yTrue[i] - yPred[i]);
+  }
+  return total / yTrue.length;
+}
+
+export function r2Score(yTrue: number[], yPred: number[]): number {
+  validateInputs(yTrue, yPred);
+
+  const yMean = mean(yTrue);
+  let ssRes = 0;
+  let ssTot = 0;
+
+  for (let i = 0; i < yTrue.length; i += 1) {
+    const residual = yTrue[i] - yPred[i];
+    const centered = yTrue[i] - yMean;
+    ssRes += residual * residual;
+    ssTot += centered * centered;
+  }
+
+  if (ssTot === 0) {
+    return ssRes === 0 ? 1 : 0;
+  }
+
+  return 1 - ssRes / ssTot;
+}