@buley/hexgrid-3d 1.0.0

package/src/adapters.ts

@@ -0,0 +1,65 @@
+/**
+ * Type-safe adapter pattern for converting domain objects to GridItems
+ */
+
+import type { GridItem } from './types'
+
+/**
+ * Options for adapter conversion
+ */
+export interface AdapterOptions {
+  /**
+   * Custom velocity calculation override
+   */
+  velocity?: number
+  /**
+   * Custom visual URL override
+   */
+  visualUrl?: string
+  /**
+   * Additional metadata to merge
+   */
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Type-safe adapter for converting domain objects to GridItems
+ */
+export interface ItemAdapter<T> {
+  /**
+   * Convert a domain object to a GridItem
+   */
+  toGridItem(data: T, options?: AdapterOptions): GridItem<T>
+  /**
+   * Extract the original domain object from a GridItem
+   */
+  fromGridItem(item: GridItem<T>): T
+  /**
+   * Calculate velocity for the item (optional)
+   */
+  calculateVelocity?(data: T): number
+  /**
+   * Extract visual URL for the item (optional)
+   */
+  extractVisualUrl?(data: T): string | undefined
+}
+
+/**
+ * Helper to create adapters for common patterns
+ */
+export function createAdapter<T>(
+  config: {
+    type: string
+    toGridItem: (data: T, options?: AdapterOptions) => GridItem<T>
+    fromGridItem: (item: GridItem<T>) => T
+    calculateVelocity?: (data: T) => number
+    extractVisualUrl?: (data: T) => string | undefined
+  }
+): ItemAdapter<T> {
+  return {
+    toGridItem: config.toGridItem,
+    fromGridItem: config.fromGridItem,
+    calculateVelocity: config.calculateVelocity,
+    extractVisualUrl: config.extractVisualUrl,
+  }
+}

package/src/algorithms/AdvancedStatistics.ts

@@ -0,0 +1,328 @@
+export interface TrendResult {
+  slope: number;
+  direction: 'increasing' | 'decreasing' | 'stable';
+  rSquared?: number;
+}
+
+export function giniCoefficient(values: number[]): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const total = sorted.reduce((sum, val) => sum + val, 0);
+  if (total === 0) return 0;
+  const n = sorted.length;
+  let cumulative = 0;
+  for (let i = 0; i < n; i++) {
+    cumulative += (i + 1) * sorted[i];
+  }
+  return (2 * cumulative) / (n * total) - (n + 1) / n;
+}
+
+export function theilIndex(values: number[]): number {
+  if (values.length === 0) return 0;
+  const avg = values.reduce((sum, val) => sum + val, 0) / values.length;
+  if (avg === 0) return 0;
+  return values.reduce((sum, val) => {
+    const ratio = val / avg;
+    return sum + (ratio === 0 ? 0 : ratio * Math.log(ratio));
+  }, 0) / values.length;
+}
+
+export function atkinsonIndex(values: number[], epsilon: number): number {
+  if (values.length === 0) return 0;
+  const avg = values.reduce((sum, val) => sum + val, 0) / values.length;
+  if (avg === 0) return 0;
+  if (epsilon === 1) {
+    const geomMean = Math.exp(
+      values.reduce((sum, val) => sum + Math.log(Math.max(val, 1e-9)), 0) /
+        values.length
+    );
+    return 1 - geomMean / avg;
+  }
+  const meanPower =
+    values.reduce((sum, val) => sum + Math.pow(val, 1 - epsilon), 0) /
+    values.length;
+  const eq = Math.pow(meanPower, 1 / (1 - epsilon));
+  return 1 - eq / avg;
+}
+
+export function paretoRatio(values: number[], topFraction: number): {
+  ratioHeld: number;
+  paretoIndex: number;
+} {
+  if (values.length === 0) return { ratioHeld: 0, paretoIndex: 0 };
+  const sorted = [...values].sort((a, b) => b - a);
+  const total = sorted.reduce((sum, val) => sum + val, 0);
+  if (total === 0) return { ratioHeld: 0, paretoIndex: 0 };
+  const topCount = Math.max(1, Math.floor(values.length * topFraction));
+  const topSum = sorted.slice(0, topCount).reduce((sum, val) => sum + val, 0);
+  return { ratioHeld: topSum / total, paretoIndex: topFraction };
+}
+
+export function zipfCoefficient(values: number[]): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => b - a);
+  const total = sorted.reduce((sum, val) => sum + val, 0);
+  if (total === 0) return 0;
+  return sorted.reduce((sum, val, idx) => sum + val / (idx + 1), 0) / total;
+}
+
+export function herfindahlIndex(values: number[]): number {
+  if (values.length === 0) return 0;
+  const total = values.reduce((sum, val) => sum + val, 0);
+  if (total === 0) return 0;
+  return values.reduce((sum, val) => {
+    const share = val / total;
+    return sum + share * share;
+  }, 0);
+}
+
+export function shannonEntropy(values: number[]): number {
+  if (values.length === 0) return 0;
+  const total = values.reduce((sum, val) => sum + val, 0);
+  if (total === 0) return 0;
+  return values.reduce((sum, val) => {
+    const p = val / total;
+    return p === 0 ? sum : sum - p * Math.log2(p);
+  }, 0);
+}
+
+export function normalizedEntropy(values: number[]): number {
+  if (values.length === 0) return 0;
+  const entropy = shannonEntropy(values);
+  const maxEntropy = Math.log2(values.length || 1);
+  return maxEntropy === 0 ? 0 : entropy / maxEntropy;
+}
+
+export function renyiEntropy(values: number[], alpha: number): number {
+  if (values.length === 0) return 0;
+  const total = values.reduce((sum, val) => sum + val, 0);
+  if (total === 0) return 0;
+  const sum = values.reduce((acc, val) => {
+    const p = val / total;
+    return acc + Math.pow(p, alpha);
+  }, 0);
+  return (1 / (1 - alpha)) * Math.log2(sum || 1);
+}
+
+export function tsallisEntropy(values: number[], q: number): number {
+  if (values.length === 0) return 0;
+  const total = values.reduce((sum, val) => sum + val, 0);
+  if (total === 0) return 0;
+  const sum = values.reduce((acc, val) => {
+    const p = val / total;
+    return acc + Math.pow(p, q);
+  }, 0);
+  return (1 - sum) / (q - 1);
+}
+
+export function detectTrend(values: number[]): TrendResult {
+  if (values.length < 2) {
+    return { slope: 0, direction: 'stable', rSquared: 0 };
+  }
+  const n = values.length;
+  const xMean = (n - 1) / 2;
+  const yMean = values.reduce((sum, v) => sum + v, 0) / n;
+  let num = 0;
+  let den = 0;
+  let ssRes = 0;
+  let ssTot = 0;
+  
+  for (let i = 0; i < n; i++) {
+    const dx = i - xMean;
+    num += dx * (values[i] - yMean);
+    den += dx * dx;
+  }
+  const slope = den === 0 ? 0 : num / den;
+  const intercept = yMean - slope * xMean;
+  
+  // Calculate R-squared
+  for (let i = 0; i < n; i++) {
+    const predicted = slope * i + intercept;
+    ssRes += Math.pow(values[i] - predicted, 2);
+    ssTot += Math.pow(values[i] - yMean, 2);
+  }
+  const rSquared = ssTot === 0 ? 0 : 1 - ssRes / ssTot;
+  
+  const direction = slope > 0.1 ? 'increasing' : slope < -0.1 ? 'decreasing' : 'stable';
+  return { slope, direction, rSquared };
+}
+
+export function detectChangePoints(values: number[]): number[] {
+  if (values.length < 3) return [];
+  const changes: number[] = [];
+  const avg = values.reduce((sum, val) => sum + val, 0) / values.length;
+  const variance = values.reduce((sum, val) => sum + (val - avg) ** 2, 0) / values.length;
+  const threshold = Math.sqrt(variance) * 1.5;
+  for (let i = 1; i < values.length; i++) {
+    if (Math.abs(values[i] - values[i - 1]) > threshold) {
+      changes.push(i);
+    }
+  }
+  return changes;
+}
+
+export function movingAverage(values: number[], windowSize: number): number[] {
+  if (values.length === 0) return [];
+  const result: number[] = [];
+  for (let i = 0; i < values.length; i++) {
+    const start = Math.max(0, i - windowSize + 1);
+    const window = values.slice(start, i + 1);
+    const avg = window.reduce((sum, val) => sum + val, 0) / window.length;
+    result.push(avg);
+  }
+  return result;
+}
+
+export function exponentialMovingAverage(values: number[], alpha: number): number[] {
+  if (values.length === 0) return [];
+  const result: number[] = [];
+  let current = values[0] ?? 0;
+  result.push(current);
+  for (let i = 1; i < values.length; i++) {
+    current = alpha * values[i] + (1 - alpha) * current;
+    result.push(current);
+  }
+  return result;
+}
+
+export function predictWinner(values: number[]): number {
+  if (values.length === 0) return 0;
+  const max = Math.max(...values);
+  return values.indexOf(max);
+}
+
+export function sparkline(values: number[]): string {
+  if (values.length === 0) return '';
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const range = max - min || 1;
+  const ticks = '▁▂▃▄▅▆▇█';
+  return values
+    .map((value) => {
+      const idx = Math.round(((value - min) / range) * (ticks.length - 1));
+      return ticks[idx] ?? ticks[0];
+    })
+    .join('');
+}
+
+export function sparklineSvg(values: number[], width: number = 100, height: number = 20): string {
+  if (values.length === 0) return '';
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const range = max - min || 1;
+  const step = width / Math.max(1, values.length - 1);
+  return values
+    .map((value, index) => {
+      const x = index * step;
+      const y = height - ((value - min) / range) * height;
+      return `${index === 0 ? 'M' : 'L'}${x},${y}`;
+    })
+    .join(' ');
+}
+
+// KL Divergence (Kullback-Leibler)
+export function klDivergence(p: number[], q: number[]): number {
+  if (p.length !== q.length || p.length === 0) return 0;
+  return p.reduce((sum, pi, i) => {
+    if (pi === 0) return sum;
+    const qi = q[i] ?? 1e-10;
+    return sum + pi * Math.log2(pi / qi);
+  }, 0);
+}
+
+// JS Divergence (Jensen-Shannon)
+export function jsDivergence(p: number[], q: number[]): number {
+  if (p.length !== q.length || p.length === 0) return 0;
+  const m = p.map((pi, i) => (pi + (q[i] ?? 0)) / 2);
+  return (klDivergence(p, m) + klDivergence(q, m)) / 2;
+}
+
+// Bhattacharyya Coefficient
+export function bhattacharyyaCoefficient(p: number[], q: number[]): number {
+  if (p.length !== q.length || p.length === 0) return 0;
+  return p.reduce((sum, pi, i) => {
+    const qi = q[i] ?? 0;
+    return sum + Math.sqrt(pi * qi);
+  }, 0);
+}
+
+// Hellinger Distance
+export function hellingerDistance(p: number[], q: number[]): number {
+  if (p.length !== q.length || p.length === 0) return 0;
+  const bc = bhattacharyyaCoefficient(p, q);
+  return Math.sqrt(1 - bc);
+}
+
+// Double Exponential Smoothing (Holt's method)
+export function doubleExponentialSmoothing(values: number[], alpha: number = 0.3, beta: number = 0.1): number[] {
+  if (values.length === 0) return [];
+  const result: number[] = [];
+  let level = values[0] ?? 0;
+  let trend = 0;
+  
+  result.push(level);
+  
+  for (let i = 1; i < values.length; i++) {
+    const prevLevel = level;
+    level = alpha * values[i] + (1 - alpha) * (level + trend);
+    trend = beta * (level - prevLevel) + (1 - beta) * trend;
+    result.push(level + trend);
+  }
+  
+  return result;
+}
+
+// Euler Characteristic (simplified for 2D)
+export function eulerCharacteristic(vertices: number, edges: number, faces: number): number {
+  return vertices - edges + faces;
+}
+
+// Estimate Betti Numbers (simplified - returns basic topological invariants)
+export function estimateBettiNumbers(complex: { vertices: number; edges: number; faces: number }): { b0: number; b1: number } {
+  const euler = eulerCharacteristic(complex.vertices, complex.edges, complex.faces);
+  // Simplified: b0 = number of connected components (assume 1 for now)
+  // b1 = edges - vertices + 1 (for a connected graph)
+  const b0 = 1;
+  const b1 = Math.max(0, complex.edges - complex.vertices + 1);
+  return { b0, b1 };
+}
+
+// Compactness measure
+export function compactness(area: number, perimeter: number): number {
+  if (perimeter === 0) return 0;
+  // 4π * area / perimeter^2 (circularity measure)
+  return (4 * Math.PI * area) / (perimeter * perimeter);
+}
+
+// Territory Statistics
+export interface TerritoryStats {
+  totalTerritories: number;
+  averageSize: number;
+  largestTerritory: number;
+  smallestTerritory: number;
+  compactness: number;
+}
+
+export function computeTerritoryStats(territories: Array<{ area: number; perimeter: number }>): TerritoryStats {
+  if (territories.length === 0) {
+    return {
+      totalTerritories: 0,
+      averageSize: 0,
+      largestTerritory: 0,
+      smallestTerritory: 0,
+      compactness: 0,
+    };
+  }
+  
+  const sizes = territories.map(t => t.area);
+  const totalSize = sizes.reduce((sum, s) => sum + s, 0);
+  const avgCompactness = territories.reduce((sum, t) => sum + compactness(t.area, t.perimeter), 0) / territories.length;
+  
+  return {
+    totalTerritories: territories.length,
+    averageSize: totalSize / territories.length,
+    largestTerritory: Math.max(...sizes),
+    smallestTerritory: Math.min(...sizes),
+    compactness: avgCompactness,
+  };
+}

package/src/algorithms/BayesianStatistics.ts

@@ -0,0 +1,317 @@
+export class BetaDistribution {
+  alpha: number;
+  beta: number;
+
+  constructor(alpha: number, beta: number) {
+    this.alpha = alpha;
+    this.beta = beta;
+  }
+
+  mean(): number {
+    const total = this.alpha + this.beta;
+    return total === 0 ? 0.5 : this.alpha / total;
+  }
+
+  variance(): number {
+    const total = this.alpha + this.beta;
+    if (total <= 1) return 0;
+    return (this.alpha * this.beta) / (total * total * (total + 1));
+  }
+}
+
+export class MarkovChain {
+  private transitions: Map<string, Map<string, number>> = new Map();
+
+  addTransition(from: string, to: string): void {
+    if (!this.transitions.has(from)) {
+      this.transitions.set(from, new Map());
+    }
+    const map = this.transitions.get(from)!;
+    map.set(to, (map.get(to) ?? 0) + 1);
+  }
+
+  probabilities(from: string): Array<{ to: string; probability: number }> {
+    const map = this.transitions.get(from);
+    if (!map) return [];
+    const total = Array.from(map.values()).reduce((sum, val) => sum + val, 0);
+    return Array.from(map.entries()).map(([to, count]) => ({
+      to,
+      probability: total === 0 ? 0 : count / total,
+    }));
+  }
+}
+
+export class KalmanFilter {
+  private state: number;
+  private uncertainty: number;
+  private processNoise: number;
+  private measurementNoise: number;
+
+  constructor(initialState: number, initialUncertainty: number, processNoise: number, measurementNoise: number) {
+    this.state = initialState;
+    this.uncertainty = initialUncertainty;
+    this.processNoise = processNoise;
+    this.measurementNoise = measurementNoise;
+  }
+
+  update(measurement: number): void {
+    const predictedUncertainty = this.uncertainty + this.processNoise;
+    const kalmanGain = predictedUncertainty / (predictedUncertainty + this.measurementNoise);
+    this.state = this.state + kalmanGain * (measurement - this.state);
+    this.uncertainty = (1 - kalmanGain) * predictedUncertainty;
+  }
+
+  step(): number {
+    // Predict next state without measurement
+    this.uncertainty += this.processNoise;
+    return this.state;
+  }
+
+  predict(steps: number = 1): number {
+    // Predict future state
+    let state = this.state;
+    for (let i = 0; i < steps; i++) {
+      state = state; // Simple prediction (no process model)
+    }
+    return state;
+  }
+
+  forecast(steps: number): { predictions: number[]; uncertainties: number[] } {
+    const predictions: number[] = [];
+    const uncertainties: number[] = [];
+    let state = this.state;
+    let uncertainty = this.uncertainty;
+
+    for (let i = 0; i < steps; i++) {
+      uncertainty += this.processNoise;
+      predictions.push(state);
+      uncertainties.push(uncertainty);
+    }
+
+    return { predictions, uncertainties };
+  }
+
+  getState(): number {
+    return this.state;
+  }
+
+  getUncertainty(): number {
+    return this.uncertainty;
+  }
+}
+
+export function bayesianWinProbability(wins: number, losses: number): number {
+  const total = wins + losses;
+  if (total === 0) return 0.5;
+  return wins / total;
+}
+
+export function bayesianConquestRate(successes: number, trials: number): number {
+  if (trials === 0) return 0;
+  return successes / trials;
+}
+
+export function bayesianChangepoint(values: number[]): number {
+  if (values.length < 2) return 0;
+  const mid = Math.floor(values.length / 2);
+  return mid;
+}
+
+export interface ProbabilitySnapshot {
+  probabilities: Array<{ label: string; probability: number }>;
+}
+
+export function generateProbabilitySnapshot(labels: string[]): ProbabilitySnapshot {
+  const probability = labels.length > 0 ? 1 / labels.length : 0;
+  return {
+    probabilities: labels.map((label) => ({ label, probability })),
+  };
+}
+
+// Dirichlet Distribution
+export class DirichletDistribution {
+  private alphas: number[];
+
+  constructor(alphas: number[]) {
+    this.alphas = alphas;
+  }
+
+  mean(): number[] {
+    const sum = this.alphas.reduce((s, a) => s + a, 0);
+    return this.alphas.map(a => sum === 0 ? 0 : a / sum);
+  }
+}
+
+// Normal Distribution
+export class NormalDistribution {
+  private mean: number;
+  private variance: number;
+
+  constructor(mean: number, variance: number) {
+    this.mean = mean;
+    this.variance = variance;
+  }
+
+  sample(): number {
+    // Box-Muller transform
+    const u1 = Math.random();
+    const u2 = Math.random();
+    const z0 = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+    return z0 * Math.sqrt(this.variance) + this.mean;
+  }
+}
+
+// Poisson Distribution
+export class PoissonDistribution {
+  private lambda: number;
+
+  constructor(lambda: number) {
+    this.lambda = lambda;
+  }
+
+  sample(): number {
+    let k = 0;
+    let p = 1;
+    const L = Math.exp(-this.lambda);
+    do {
+      k++;
+      p *= Math.random();
+    } while (p > L);
+    return k - 1;
+  }
+}
+
+// Exponential Distribution
+export class ExponentialDistribution {
+  private lambda: number;
+
+  constructor(lambda: number) {
+    this.lambda = lambda;
+  }
+
+  sample(): number {
+    return -Math.log(1 - Math.random()) / this.lambda;
+  }
+}
+
+// Hidden Markov Model
+export class HiddenMarkovModel {
+  private states: string[];
+  private transitions: Map<string, Map<string, number>>;
+  private emissions: Map<string, Map<string, number>>;
+
+  constructor(states: string[]) {
+    this.states = states;
+    this.transitions = new Map();
+    this.emissions = new Map();
+  }
+
+  addTransition(from: string, to: string, probability: number): void {
+    if (!this.transitions.has(from)) {
+      this.transitions.set(from, new Map());
+    }
+    this.transitions.get(from)!.set(to, probability);
+  }
+
+  addEmission(state: string, observation: string, probability: number): void {
+    if (!this.emissions.has(state)) {
+      this.emissions.set(state, new Map());
+    }
+    this.emissions.get(state)!.set(observation, probability);
+  }
+}
+
+// Bayesian A/B Test
+export function bayesianABTest(successA: number, trialsA: number, successB: number, trialsB: number): number {
+  const probA = trialsA === 0 ? 0.5 : successA / trialsA;
+  const probB = trialsB === 0 ? 0.5 : successB / trialsB;
+  return probB - probA; // Difference in probabilities
+}
+
+// Bayes Factor
+export function bayesFactor(priorOdds: number, likelihoodRatio: number): number {
+  return priorOdds * likelihoodRatio;
+}
+
+// MAP Estimate (Maximum A Posteriori)
+export function mapEstimate(data: number[], prior: { alpha: number; beta: number }): number {
+  const sum = data.reduce((s, x) => s + x, 0);
+  const n = data.length;
+  const alpha = prior.alpha + sum;
+  const beta = prior.beta + n - sum;
+  return alpha / (alpha + beta);
+}
+
+// Learn Markov Chain from sequence
+export function learnMarkovChain(sequence: string[]): MarkovChain {
+  const chain = new MarkovChain();
+  for (let i = 0; i < sequence.length - 1; i++) {
+    chain.addTransition(sequence[i]!, sequence[i + 1]!);
+  }
+  return chain;
+}
+
+// Bootstrap Confidence Interval
+export function bootstrapConfidenceInterval(data: number[], iterations: number = 1000, confidence: number = 0.95): { lower: number; upper: number } {
+  const samples: number[] = [];
+  for (let i = 0; i < iterations; i++) {
+    const sample: number[] = [];
+    for (let j = 0; j < data.length; j++) {
+      sample.push(data[Math.floor(Math.random() * data.length)] ?? 0);
+    }
+    samples.push(sample.reduce((s, x) => s + x, 0) / sample.length);
+  }
+  samples.sort((a, b) => a - b);
+  const lowerIdx = Math.floor((1 - confidence) / 2 * samples.length);
+  const upperIdx = Math.floor((1 + confidence) / 2 * samples.length);
+  return {
+    lower: samples[lowerIdx] ?? 0,
+    upper: samples[upperIdx] ?? 0,
+  };
+}
+
+// Monte Carlo Integration
+export function monteCarloIntegrate(fn: (x: number) => number, a: number, b: number, samples: number = 1000): number {
+  let sum = 0;
+  for (let i = 0; i < samples; i++) {
+    const x = a + Math.random() * (b - a);
+    sum += fn(x);
+  }
+  return ((b - a) * sum) / samples;
+}
+
+// Mutual Information
+export function mutualInformation(x: number[], y: number[]): number {
+  // Simplified implementation
+  if (x.length !== y.length || x.length === 0) return 0;
+  const n = x.length;
+  const hx = shannonEntropy(x);
+  const hy = shannonEntropy(y);
+  // Simplified: assume independence for now
+  return Math.max(0, hx + hy - (hx + hy) * 0.5);
+}
+
+function shannonEntropy(values: number[]): number {
+  const total = values.reduce((s, v) => s + Math.abs(v), 0);
+  if (total === 0) return 0;
+  return values.reduce((sum, val) => {
+    const p = Math.abs(val) / total;
+    return p === 0 ? sum : sum - p * Math.log2(p);
+  }, 0);
+}
+
+// Conditional Entropy
+export function conditionalEntropy(x: number[], y: number[]): number {
+  if (x.length !== y.length || x.length === 0) return 0;
+  // Simplified: return marginal entropy
+  return shannonEntropy(x);
+}
+
+// Normalized Mutual Information
+export function normalizedMutualInformation(x: number[], y: number[]): number {
+  const mi = mutualInformation(x, y);
+  const hx = shannonEntropy(x);
+  const hy = shannonEntropy(y);
+  const denom = Math.sqrt(hx * hy);
+  return denom === 0 ? 0 : mi / denom;
+}