@hoox-sh/pynets 0.2.0 → 0.3.0

package/src/runtime/matrix.ts

@@ -3,9 +3,12 @@
  * SPDX-License-Identifier: AGPL-3.0-or-later
  *
  * Tiny Pine `matrix.*` value. `null` is `na`. Get is na-safe (OOB / non-finite → na).
- * Set OOB is a no-op. Python `Matrix` remains the source of truth.
+ * Set OOB is a no-op. Slots may hold numbers, na, or UDT instances.
+ * Python `Matrix` remains the source of truth.
  */
 
+import { UdtInstance } from "./udt.ts";
+
 export type Cell = number | null;
 
 /** Python has no matrix-size cap; bound elements like `array.set` (1e6). */
@@ -29,13 +32,176 @@ function fitsElements(rows: number, cols: number): boolean {
 }
 
 /** Pad with `na` or truncate so the vector has length *n*. */
-function padOrTrunc(values: Cell[] | undefined, n: number): Cell[] {
-  const out: Cell[] = [];
+function padOrTrunc(values: unknown[] | undefined, n: number): unknown[] {
+  const out: unknown[] = [];
   const src = values ?? [];
   for (let i = 0; i < n; i++) out.push(i < src.length ? src[i]! : null);
   return out;
 }
 
+function looksLikeUdt(item: unknown): boolean {
+  if (item == null || typeof item !== "object") return false;
+  if (item instanceof UdtInstance) return true;
+  return !Array.isArray(item) && Object.prototype.hasOwnProperty.call(item, "__type__");
+}
+
+function udtFieldNames(item: object): string[] | null {
+  if (item instanceof UdtInstance) return item.type.fields.map((f) => f.name);
+  const rec = item as Record<string, unknown>;
+  if (Object.prototype.hasOwnProperty.call(rec, "__type__")) {
+    return Object.keys(rec).filter((k) => k !== "__type__");
+  }
+  return null;
+}
+
+function readUdtField(item: object, name: string): unknown {
+  if (item instanceof UdtInstance) return item.get(name);
+  return (item as Record<string, unknown>)[name];
+}
+
+function udtFieldKey(item: unknown, sortField: unknown): unknown {
+  if (item == null || sortField == null || typeof item !== "object") return item;
+  if (typeof sortField === "string") return readUdtField(item, sortField);
+  if (typeof sortField === "number" && Number.isFinite(sortField)) {
+    const names = udtFieldNames(item);
+    if (names == null) return item;
+    const idx = Math.trunc(sortField);
+    if (idx < 0 || idx >= names.length) return item;
+    return readUdtField(item, names[idx]!);
+  }
+  return item;
+}
+
+function cellSortValue(cell: unknown, sortField: unknown): unknown {
+  return sortField != null ? udtFieldKey(cell, sortField) : cell;
+}
+
+function isSortNa(v: unknown): boolean {
+  if (v == null) return true;
+  if (typeof v === "number") return !Number.isFinite(v);
+  return false;
+}
+
+function asFiniteNumber(v: unknown): number | null {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+
+/** Python `isinstance(x, int | float)` — bool counts; `na` / non-finite does not. */
+function numericCell(v: unknown): number | null {
+  if (typeof v === "boolean") return v ? 1 : 0;
+  return asFiniteNumber(v);
+}
+
+function sumNumeric(cells: readonly unknown[]): number {
+  let total = 0;
+  for (const x of cells) {
+    const n = numericCell(x);
+    if (n !== null) total += n;
+  }
+  return total;
+}
+
+/** Empty numeric line → 0 (Python `avg_row` / `avg_col`). */
+function avgNumeric(cells: readonly unknown[]): number {
+  let total = 0;
+  let count = 0;
+  for (const x of cells) {
+    const n = numericCell(x);
+    if (n === null) continue;
+    total += n;
+    count += 1;
+  }
+  return count > 0 ? total / count : 0;
+}
+
+function extremumNumeric(cells: readonly unknown[], max: boolean): Cell {
+  let best: number | null = null;
+  for (const x of cells) {
+    const n = numericCell(x);
+    if (n === null) continue;
+    if (best === null || (max ? n > best : n < best)) best = n;
+  }
+  return best;
+}
+
+/** Python `Counter.most_common`: first-seen wins ties. Non-finite is `na`. */
+function modeOf(values: readonly unknown[]): unknown {
+  if (values.length === 0) return null;
+  const keys: unknown[] = [];
+  const counts: number[] = [];
+  let bestI = 0;
+  let bestN = 0;
+  for (const raw of values) {
+    const key = typeof raw === "number" && !Number.isFinite(raw) ? null : (raw ?? null);
+    let idx = -1;
+    for (let i = 0; i < keys.length; i++) {
+      if (keys[i] === key) {
+        idx = i;
+        break;
+      }
+    }
+    if (idx < 0) {
+      idx = keys.length;
+      keys.push(key);
+      counts.push(1);
+    } else {
+      counts[idx] = (counts[idx] ?? 0) + 1;
+    }
+    const n = counts[idx] ?? 0;
+    if (n > bestN) {
+      bestN = n;
+      bestI = idx;
+    }
+  }
+  return keys[bestI] ?? null;
+}
+
+/** Sample moments (Python `statistics.variance` / `stdev`, divisor n−1). */
+function sampleMoments(vals: readonly number[]): { variance: number; stdev: number } | null {
+  const n = vals.length;
+  if (n < 2) return null;
+  let sum = 0;
+  for (const x of vals) sum += x;
+  const mean = sum / n;
+  let ss = 0;
+  let dev = 0;
+  for (const x of vals) {
+    const d = x - mean;
+    dev += d;
+    ss += d * d;
+  }
+  ss -= (dev * dev) / n;
+  if (ss < 0) ss = 0;
+  const variance = ss / (n - 1);
+  const stdev = Math.sqrt(variance);
+  if (!Number.isFinite(variance) || !Number.isFinite(stdev)) return null;
+  return { variance, stdev };
+}
+
+function defaultMatrixSortField(rows: readonly unknown[][], column: number): unknown {
+  for (const row of rows) {
+    const cell = row[column];
+    if (cell == null) continue;
+    if (looksLikeUdt(cell)) return 0;
+    break;
+  }
+  return null;
+}
+
+function compareSortKeys(a: unknown, b: unknown): number {
+  if (a === b) return 0;
+  if (typeof a === "number" && typeof b === "number") {
+    if (a < b) return -1;
+    if (a > b) return 1;
+    return 0;
+  }
+  const sa = `${String(Object.prototype.toString.call(a))}${String(a)}`;
+  const sb = `${String(Object.prototype.toString.call(b))}${String(b)}`;
+  if (sa < sb) return -1;
+  if (sa > sb) return 1;
+  return 0;
+}
+
 function cloneGrid(src: number[][]): number[][] {
   const out: number[][] = [];
   for (let i = 0; i < src.length; i++) out.push(src[i]!.slice());
@@ -346,11 +512,11 @@ function nullspaceUnit(M: number[][]): number[] | null {
 }
 
 export class PineMatrix {
-  private readonly cells: Cell[][] = [];
+  private readonly cells: unknown[][] = [];
   private nRows: number;
   private nCols: number;
 
-  constructor(rows: number, cols: number, initial?: Cell) {
+  constructor(rows: number, cols: number, initial?: unknown) {
     let r = dim(rows);
     let c = dim(cols);
     if (r > 0 && c > Math.floor(MAX_MATRIX_ELEMENTS / r)) {
@@ -359,9 +525,9 @@ export class PineMatrix {
     }
     this.nRows = r;
     this.nCols = c;
-    const fill: Cell = initial === undefined ? null : initial;
+    const fill = initial === undefined ? null : initial;
     for (let i = 0; i < this.nRows; i++) {
-      const row: Cell[] = [];
+      const row: unknown[] = [];
       for (let j = 0; j < this.nCols; j++) row.push(fill);
       this.cells.push(row);
     }
@@ -380,18 +546,18 @@ export class PineMatrix {
     const i = resolveIndex(row, this.nRows);
     const j = resolveIndex(col, this.nCols);
     if (i === null || j === null) return null;
-    return this.cells[i]![j]!;
+    return this.cells[i]![j] as Cell;
   }
 
   /** `matrix.set` — OOB / non-finite index is a no-op. */
-  set(row: number, col: number, value: Cell): void {
+  set(row: number, col: number, value: unknown): void {
     const i = resolveIndex(row, this.nRows);
     const j = resolveIndex(col, this.nCols);
     if (i === null || j === null) return;
     this.cells[i]![j] = value;
   }
 
-  fill(value: Cell): void {
+  fill(value: unknown): void {
     for (let i = 0; i < this.nRows; i++) {
       const row = this.cells[i]!;
       for (let j = 0; j < this.nCols; j++) row[j] = value;
@@ -408,14 +574,14 @@ export class PineMatrix {
 
   row(i: number): Cell[] {
     const r = resolveIndex(i, this.nRows);
-    return r === null ? [] : this.cells[r]!.slice();
+    return r === null ? [] : (this.cells[r]!.slice() as Cell[]);
   }
 
   col(j: number): Cell[] {
     const c = resolveIndex(j, this.nCols);
     if (c === null) return [];
     const out: Cell[] = [];
-    for (let i = 0; i < this.nRows; i++) out.push(this.cells[i]![c]!);
+    for (let i = 0; i < this.nRows; i++) out.push(this.cells[i]![c] as Cell);
     return out;
   }
 
@@ -473,8 +639,8 @@ export class PineMatrix {
     if (!this.isSquare()) return null;
     let acc = 0;
     for (let i = 0; i < this.nRows; i++) {
-      const v = this.cells[i]![i]!;
-      if (v === null || !Number.isFinite(v)) return null;
+      const v = asFiniteNumber(this.cells[i]![i]);
+      if (v === null) return null;
       acc += v;
     }
     return acc;
@@ -489,8 +655,8 @@ export class PineMatrix {
     for (let i = 0; i < n; i++) {
       const row: number[] = [];
       for (let j = 0; j < n; j++) {
-        const v = this.cells[i]![j]!;
-        if (v === null || !Number.isFinite(v)) return null;
+        const v = asFiniteNumber(this.cells[i]![j]);
+        if (v === null) return null;
         row.push(v);
       }
       a.push(row);
@@ -536,8 +702,8 @@ export class PineMatrix {
       const out = new PineMatrix(this.nRows, this.nCols);
       for (let i = 0; i < this.nRows; i++) {
         for (let j = 0; j < this.nCols; j++) {
-          const v = this.cells[i]![j]!;
-          if (v === null || !Number.isFinite(v)) {
+          const v = asFiniteNumber(this.cells[i]![j]);
+          if (v === null) {
             out.set(i, j, null);
             continue;
           }
@@ -773,7 +939,7 @@ export class PineMatrix {
    * Short rows pad `na`; long rows truncate. 0×0 adopts column count from *values*.
    * Negative / non-finite index or size cap → no-op.
    */
-  addRow(index?: number, values?: Cell[]): void {
+  addRow(index?: number, values?: unknown[]): void {
     const adopt = this.nRows === 0 && this.nCols === 0;
     const cols = adopt ? (values?.length ?? 0) : this.nCols;
     if (!fitsElements(this.nRows + 1, cols)) return;
@@ -793,7 +959,7 @@ export class PineMatrix {
    * Insert a column at *index* (append if omitted / past end).
    * Short cols pad `na`; long cols truncate. 0×0 becomes N×1 from *values*.
    */
-  addCol(index?: number, values?: Cell[]): void {
+  addCol(index?: number, values?: unknown[]): void {
     if (this.nRows === 0 && this.nCols === 0) {
       const n = values?.length ?? 0;
       if (!fitsElements(n, n === 0 ? 0 : 1)) return;
@@ -891,35 +1057,60 @@ export class PineMatrix {
     for (const row of this.cells) row.reverse();
   }
 
-  /** Sort rows by *column*. `na` / non-finite keys always last. */
-  sort(column = 0, order: "asc" | "desc" = "asc"): void {
+  /** Sort rows by *column*. `na` last. Optional *sortField* keys UDT cells. */
+  sort(column = 0, order: "asc" | "desc" = "asc", sortField?: unknown): void {
     if (this.nRows === 0) return;
     const c = resolveIndex(column, this.nCols);
     if (c === null) return;
     const desc = order === "desc";
-    const nonNa: Cell[][] = [];
-    const naRows: Cell[][] = [];
+    const field = sortField ?? defaultMatrixSortField(this.cells, c);
+    const nonNa: unknown[][] = [];
+    const naRows: unknown[][] = [];
     for (const row of this.cells) {
-      const v = row[c]!;
-      if (v === null || !Number.isFinite(v)) naRows.push(row);
+      const v = cellSortValue(row[c], field);
+      if (isSortNa(v)) naRows.push(row);
       else nonNa.push(row);
     }
     nonNa.sort((a, b) => {
-      const d = (a[c] as number) - (b[c] as number);
-      return desc ? -d : d;
+      const ka = cellSortValue(a[c], field);
+      const kb = cellSortValue(b[c], field);
+      const cmp = compareSortKeys(ka, kb);
+      return desc ? -cmp : cmp;
     });
     this.cells.length = 0;
     for (const row of nonNa) this.cells.push(row);
     for (const row of naRows) this.cells.push(row);
   }
 
+  /** Row indices that would sort by *column*; `na` indices last. */
+  sortIndices(column = 0, order: "asc" | "desc" = "asc", sortField?: unknown): number[] {
+    if (this.nRows === 0) return [];
+    const c = resolveIndex(column, this.nCols);
+    if (c === null) return [];
+    const desc = order === "desc";
+    const field = sortField ?? defaultMatrixSortField(this.cells, c);
+    const nonNa: { key: unknown; idx: number }[] = [];
+    const naIdx: number[] = [];
+    for (let i = 0; i < this.nRows; i++) {
+      const v = cellSortValue(this.cells[i]![c], field);
+      if (isSortNa(v)) naIdx.push(i);
+      else nonNa.push({ key: v, idx: i });
+    }
+    nonNa.sort((a, b) => {
+      const cmp = compareSortKeys(a.key, b.key);
+      if (cmp !== 0) return desc ? -cmp : cmp;
+      return a.idx - b.idx;
+    });
+    return nonNa.map((x) => x.idx).concat(naIdx);
+  }
+
   /** Median of finite cells (Python skips `na`). Empty → `na`. */
   median(): Cell {
     const vals: number[] = [];
     for (let i = 0; i < this.nRows; i++) {
       for (let j = 0; j < this.nCols; j++) {
-        const v = this.cells[i]![j]!;
-        if (v !== null && Number.isFinite(v)) vals.push(v);
+        const v = asFiniteNumber(this.cells[i]![j]);
+        if (v !== null) vals.push(v);
       }
     }
     if (vals.length === 0) return null;
@@ -936,8 +1127,8 @@ export class PineMatrix {
     let bestCount = 0;
     for (let i = 0; i < this.nRows; i++) {
       for (let j = 0; j < this.nCols; j++) {
-        const v = this.cells[i]![j]!;
-        if (v === null || !Number.isFinite(v)) continue;
+        const v = asFiniteNumber(this.cells[i]![j]);
+        if (v === null) continue;
         const n = (counts.get(v) ?? 0) + 1;
         counts.set(v, n);
         if (n > bestCount) {
@@ -949,6 +1140,114 @@ export class PineMatrix {
     return best;
   }
 
+  /** Copy of the row. OOB → empty (same as `row`). */
+  copyRow(index: number): Cell[] {
+    return this.row(index);
+  }
+
+  /** Copy of the column. OOB → empty (same as `col`). */
+  copyCol(index: number): Cell[] {
+    return this.col(index);
+  }
+
+  /** Sum of numeric cells. Skips `na`. No numeric cells → 0. OOB → `na`. */
+  sumRow(index: number): Cell {
+    const line = this.lineAt("row", index);
+    return line === null ? null : sumNumeric(line);
+  }
+
+  sumCol(index: number): Cell {
+    const line = this.lineAt("col", index);
+    return line === null ? null : sumNumeric(line);
+  }
+
+  /** Mean of numeric cells. Skips `na`. No numeric cells → 0. OOB → `na`. */
+  avgRow(index: number): Cell {
+    const line = this.lineAt("row", index);
+    return line === null ? null : avgNumeric(line);
+  }
+
+  avgCol(index: number): Cell {
+    const line = this.lineAt("col", index);
+    return line === null ? null : avgNumeric(line);
+  }
+
+  /** Min numeric cell. Skips `na`. None → `na`. OOB → `na`. */
+  minRow(index: number): Cell {
+    const line = this.lineAt("row", index);
+    return line === null ? null : extremumNumeric(line, false);
+  }
+
+  minCol(index: number): Cell {
+    const line = this.lineAt("col", index);
+    return line === null ? null : extremumNumeric(line, false);
+  }
+
+  maxRow(index: number): Cell {
+    const line = this.lineAt("row", index);
+    return line === null ? null : extremumNumeric(line, true);
+  }
+
+  maxCol(index: number): Cell {
+    const line = this.lineAt("col", index);
+    return line === null ? null : extremumNumeric(line, true);
+  }
+
+  /** Most common cell in the row, including `na`. Empty / OOB → `na`. */
+  modeRow(index: number): unknown {
+    const line = this.lineAt("row", index);
+    return line === null ? null : modeOf(line);
+  }
+
+  modeCol(index: number): unknown {
+    const line = this.lineAt("col", index);
+    return line === null ? null : modeOf(line);
+  }
+
+  /** Most common cell, row-major, including `na` (Python `Counter`). Empty → `na`. */
+  modeAll(): unknown {
+    return modeOf(this.flatCells());
+  }
+
+  /** OOB / non-finite index is a no-op. */
+  fillRow(index: number, value: unknown): void {
+    const i = resolveIndex(index, this.nRows);
+    if (i === null) return;
+    const row = this.cells[i]!;
+    for (let j = 0; j < this.nCols; j++) row[j] = value;
+  }
+
+  /** OOB / non-finite index is a no-op. */
+  fillCol(index: number, value: unknown): void {
+    const j = resolveIndex(index, this.nCols);
+    if (j === null) return;
+    for (let i = 0; i < this.nRows; i++) this.cells[i]![j] = value;
+  }
+
+  /** Main diagonal, `min(rows, columns)` long. */
+  fillDiagonal(value: unknown): void {
+    const n = Math.min(this.nRows, this.nCols);
+    for (let i = 0; i < n; i++) this.cells[i]![i] = value;
+  }
+
+  reverseRows(): void {
+    this.cells.reverse();
+  }
+
+  reverseCols(): void {
+    for (const row of this.cells) row.reverse();
+  }
+
+  /** Sample stdev of numeric cells (n−1). Skips `na`. Fewer than 2 → `na`. */
+  stdev(): Cell {
+    return sampleMoments(this.numericFlat())?.stdev ?? null;
+  }
+
+  /** Sample variance of numeric cells (n−1). Skips `na`. Fewer than 2 → `na`. */
+  variance(): Cell {
+    return sampleMoments(this.numericFlat())?.variance ?? null;
+  }
+
   /** Every cell is 0 or 1. `na` / other values → false. Empty is true. */
   isBinary(): boolean {
     for (let i = 0; i < this.nRows; i++) {
@@ -965,8 +1264,8 @@ export class PineMatrix {
     for (let i = 0; i < this.nRows; i++) {
       let total = 0;
       for (let j = 0; j < this.nCols; j++) {
-        const v = this.cells[i]![j]!;
-        if (v === null || !Number.isFinite(v) || v < 0) return false;
+        const v = asFiniteNumber(this.cells[i]![j]);
+        if (v === null || v < 0) return false;
         total += v;
       }
       if (Math.abs(total - 1) > 1e-9) return false;
@@ -994,9 +1293,9 @@ export class PineMatrix {
     const out = new PineMatrix(this.nRows, this.nCols);
     for (let i = 0; i < this.nRows; i++) {
       for (let j = 0; j < this.nCols; j++) {
-        const a = this.cells[i]![j]!;
-        const b = other.cells[i]![j]!;
-        if (a === null || b === null || !Number.isFinite(a) || !Number.isFinite(b)) {
+        const a = asFiniteNumber(this.cells[i]![j]);
+        const b = asFiniteNumber(other.cells[i]![j]);
+        if (a === null || b === null) {
           out.set(i, j, null);
           continue;
         }
@@ -1123,8 +1422,8 @@ export class PineMatrix {
     for (let i = 0; i < this.nRows; i++) {
       const row: number[] = [];
       for (let j = 0; j < this.nCols; j++) {
-        const v = this.cells[i]![j]!;
-        if (v === null || !Number.isFinite(v)) return null;
+        const v = asFiniteNumber(this.cells[i]![j]);
+        if (v === null) return null;
         row.push(v);
       }
       out.push(row);
@@ -1136,8 +1435,8 @@ export class PineMatrix {
     const out: number[] = [];
     for (let i = 0; i < this.nRows; i++) {
       for (let j = 0; j < this.nCols; j++) {
-        const v = this.cells[i]![j]!;
-        if (v === null || !Number.isFinite(v)) return null;
+        const v = asFiniteNumber(this.cells[i]![j]);
+        if (v === null) return null;
         out.push(v);
       }
     }
@@ -1147,7 +1446,37 @@ export class PineMatrix {
   private flatten(): Cell[] {
     const out: Cell[] = [];
     for (let i = 0; i < this.nRows; i++) {
-      for (let j = 0; j < this.nCols; j++) out.push(this.cells[i]![j]!);
+      for (let j = 0; j < this.nCols; j++) out.push(this.cells[i]![j] as Cell);
+    }
+    return out;
+  }
+
+  /** In-range line, or `null` when the index is OOB / non-finite. */
+  private lineAt(axis: "row" | "col", index: number): readonly unknown[] | null {
+    if (axis === "row") {
+      const i = resolveIndex(index, this.nRows);
+      return i === null ? null : this.cells[i]!;
+    }
+    const j = resolveIndex(index, this.nCols);
+    if (j === null) return null;
+    const out: unknown[] = [];
+    for (let i = 0; i < this.nRows; i++) out.push(this.cells[i]![j]);
+    return out;
+  }
+
+  private flatCells(): unknown[] {
+    const out: unknown[] = [];
+    for (let i = 0; i < this.nRows; i++) {
+      for (let j = 0; j < this.nCols; j++) out.push(this.cells[i]![j]);
+    }
+    return out;
+  }
+
+  private numericFlat(): number[] {
+    const out: number[] = [];
+    for (const v of this.flatCells()) {
+      const n = numericCell(v);
+      if (n !== null) out.push(n);
     }
     return out;
   }