@graphty/algorithms 1.2.0 → 1.3.1

package/src/clustering/index.ts

@@ -1,5 +1,7 @@
-export * from "./hierarchical.js";
-export * from "./k-core.js";
+export type {ClusterNode, HierarchicalClusteringResult, LinkageMethod} from "./hierarchical.js";
+export {hierarchicalClustering} from "./hierarchical.js";
+export type {KCoreResult} from "./k-core.js";
+export {getKCore, kCoreDecomposition} from "./k-core.js";
 export type {MCLOptions, MCLResult} from "./mcl.js";
 export {calculateMCLModularity, markovClustering} from "./mcl.js";
 export type {SpectralClusteringOptions, SpectralClusteringResult} from "./spectral.js";

package/src/clustering/k-core.ts

@@ -6,6 +6,41 @@
  * understanding graph structure.
  */
 
+import type {Graph} from "../core/graph.js";
+
+/**
+ * Convert Graph to adjacency set representation
+ */
+function graphToAdjacencySet(graph: Graph): Map<string, Set<string>> {
+    const adjacency = new Map<string, Set<string>>();
+
+    // Initialize all nodes
+    for (const node of graph.nodes()) {
+        adjacency.set(String(node.id), new Set());
+    }
+
+    // Add edges
+    for (const edge of graph.edges()) {
+        const source = String(edge.source);
+        const target = String(edge.target);
+
+        const sourceSet = adjacency.get(source);
+        if (sourceSet) {
+            sourceSet.add(target);
+        }
+
+        // For undirected graphs, add reverse edge
+        if (!graph.isDirected) {
+            const targetSet = adjacency.get(target);
+            if (targetSet) {
+                targetSet.add(source);
+            }
+        }
+    }
+
+    return adjacency;
+}
+
 export interface KCoreResult<T> {
     cores: Map<number, Set<T>>;
     coreness: Map<T, number>;
@@ -13,16 +48,9 @@ export interface KCoreResult<T> {
 }
 
 /**
- * K-Core decomposition algorithm
- * Finds all k-cores in the graph and assigns coreness values to nodes
- *
- * @param graph - Undirected graph as adjacency list
- * @returns K-core decomposition results
- *
- * Time Complexity: O(V + E)
- * Space Complexity: O(V)
+ * Internal implementation of K-Core decomposition algorithm
  */
-export function kCoreDecomposition<T>(
+function kCoreDecompositionImpl<T>(
     graph: Map<T, Set<T>>,
 ): KCoreResult<T> {
     if (graph.size === 0) {
@@ -191,12 +219,12 @@ export function kCoreDecomposition<T>(
  * @param k - Core number
  * @returns Set of nodes in k-core or higher
  */
-export function getKCore<T>(
-    graph: Map<T, Set<T>>,
+export function getKCore(
+    graph: Graph,
     k: number,
-): Set<T> {
+): Set<string> {
     const {coreness} = kCoreDecomposition(graph);
-    const kCore = new Set<T>();
+    const kCore = new Set<string>();
 
     for (const [node, core] of coreness) {
         if (core >= k) {
@@ -215,17 +243,18 @@ export function getKCore<T>(
  * @param k - Core number
  * @returns K-core subgraph
  */
-export function getKCoreSubgraph<T>(
-    graph: Map<T, Set<T>>,
+export function getKCoreSubgraph(
+    graph: Graph,
     k: number,
-): Map<T, Set<T>> {
+): Map<string, Set<string>> {
     const kCoreNodes = getKCore(graph, k);
-    const subgraph = new Map<T, Set<T>>();
+    const adjacencySet = graphToAdjacencySet(graph);
+    const subgraph = new Map<string, Set<string>>();
 
     for (const node of kCoreNodes) {
-        const neighbors = graph.get(node);
+        const neighbors = adjacencySet.get(node);
         if (neighbors) {
-            const coreNeighbors = new Set<T>();
+            const coreNeighbors = new Set<string>();
             for (const neighbor of neighbors) {
                 if (kCoreNodes.has(neighbor)) {
                     coreNeighbors.add(neighbor);
@@ -245,24 +274,25 @@ export function getKCoreSubgraph<T>(
  * @param graph - Undirected graph
  * @returns Array of nodes ordered by degeneracy
  */
-export function degeneracyOrdering<T>(
-    graph: Map<T, Set<T>>,
-): T[] {
-    const degree = new Map<T, number>();
-    const remaining = new Map<T, Set<T>>();
-    const ordering: T[] = [];
+export function degeneracyOrdering(
+    graph: Graph,
+): string[] {
+    const adjacencySet = graphToAdjacencySet(graph);
+    const degree = new Map<string, number>();
+    const remaining = new Map<string, Set<string>>();
+    const ordering: string[] = [];
 
     // Initialize
-    for (const [node, neighbors] of graph) {
+    for (const [node, neighbors] of adjacencySet) {
         degree.set(node, neighbors.size);
         remaining.set(node, new Set(neighbors));
     }
 
     // Build ordering
-    while (ordering.length < graph.size) {
+    while (ordering.length < adjacencySet.size) {
     // Find minimum degree node
         let minDegree = Infinity;
-        let minNode: T | undefined;
+        let minNode: string | undefined;
 
         for (const [node, deg] of degree) {
             if (!ordering.includes(node) && deg < minDegree) {
@@ -302,20 +332,22 @@ export function degeneracyOrdering<T>(
  * @param k - Truss number (k >= 2)
  * @returns Edges in k-truss
  */
-export function kTruss<T>(
-    graph: Map<T, Set<T>>,
+export function kTruss(
+    graph: Graph,
     k: number,
 ): Set<string> {
     if (k < 2) {
         throw new Error("k must be at least 2 for k-truss");
     }
 
+    const adjacencySet = graphToAdjacencySet(graph);
+
     // Count triangles for each edge
     const edgeTriangles = new Map<string, number>();
     const edges = new Set<string>();
 
     // Initialize edges
-    for (const [u, neighbors] of graph) {
+    for (const [u, neighbors] of adjacencySet) {
         for (const v of neighbors) {
             if (u < v) { // Avoid duplicates
                 const edge = `${String(u)},${String(v)}`;
@@ -326,10 +358,10 @@ export function kTruss<T>(
     }
 
     // Count triangles
-    for (const [u, uNeighbors] of graph) {
+    for (const [u, uNeighbors] of adjacencySet) {
         for (const v of uNeighbors) {
             if (u < v) {
-                const vNeighbors = graph.get(v);
+                const vNeighbors = adjacencySet.get(v);
                 if (vNeighbors) {
                     // Find common neighbors (triangles)
                     for (const w of uNeighbors) {
@@ -390,16 +422,14 @@ export function kTruss<T>(
             }
 
             // Update triangle counts for affected edges
-            const uNode = u as T;
-            const vNode = v as T;
-            const uNeighbors = graph.get(uNode);
-            const vNeighbors = graph.get(vNode);
+            const uNeighbors = adjacencySet.get(u);
+            const vNeighbors = adjacencySet.get(v);
 
             if (uNeighbors && vNeighbors) {
                 for (const w of uNeighbors) {
                     if (vNeighbors.has(w)) {
-                        const edge1 = uNode < w ? `${String(uNode)},${String(w)}` : `${String(w)},${String(uNode)}`;
-                        const edge2 = vNode < w ? `${String(vNode)},${String(w)}` : `${String(w)},${String(vNode)}`;
+                        const edge1 = u < w ? `${String(u)},${String(w)}` : `${String(w)},${String(u)}`;
+                        const edge2 = v < w ? `${String(v)},${String(w)}` : `${String(w)},${String(v)}`;
 
                         if (kTrussEdges.has(edge1)) {
                             const edge1Count = edgeTriangles.get(edge1);
@@ -458,3 +488,21 @@ export function toUndirected<T>(
     return undirected;
 }
 
+/**
+ * K-Core decomposition algorithm
+ * Finds all k-cores in the graph and assigns coreness values to nodes
+ *
+ * @param graph - Undirected graph - accepts Graph class or Map<T, Set<T>>
+ * @returns K-core decomposition results
+ *
+ * Time Complexity: O(V + E)
+ * Space Complexity: O(V)
+ */
+export function kCoreDecomposition(
+    graph: Graph,
+): KCoreResult<string> {
+    // Convert Graph to adjacency set representation
+    const adjacencySet = graphToAdjacencySet(graph);
+    return kCoreDecompositionImpl(adjacencySet);
+}
+

package/src/clustering/spectral.ts

@@ -1,5 +1,6 @@
 import type {Graph} from "../core/graph.js";
 import type {NodeId} from "../types/index.js";
+import {euclideanDistance} from "../utils/math-utilities.js";
 
 /**
  * Spectral Clustering implementation
@@ -27,6 +28,14 @@ export interface SpectralClusteringResult {
 
 /**
  * Perform spectral clustering on a graph
+ *
+ * @warning This implementation uses simplified power iteration for eigenvector
+ * computation with approximate eigenvalues. For production use cases requiring
+ * precise clustering, consider using a proper linear algebra library like ml-matrix.
+ *
+ * The approximate eigenvalues (0.1, 0.2 for second and third eigenvectors) work
+ * well for most graph structures but may produce suboptimal results for graphs
+ * with unusual spectral properties.
  */
 export function spectralClustering(
     graph: Graph,
@@ -36,8 +45,14 @@ export function spectralClustering(
         k,
         laplacianType = "normalized",
         maxIterations = 100,
+        tolerance = 1e-4,
     } = options;
 
+    // Input validation
+    if (k < 1 || !Number.isInteger(k)) {
+        throw new Error("k must be a positive integer");
+    }
+
     const nodes = Array.from(graph.nodes());
     const nodeIds = nodes.map((node) => node.id);
     const n = nodeIds.length;
@@ -79,7 +94,7 @@ export function spectralClustering(
         normalizeRows(dataPoints);
     }
 
-    const kmeans = kMeansClustering(dataPoints, k, maxIterations);
+    const kmeans = kMeansClustering(dataPoints, k, maxIterations, tolerance);
 
     // Build communities
     const communities: NodeId[][] = Array.from({length: k}, () => []);
@@ -416,6 +431,7 @@ function kMeansClustering(
     data: number[][],
     k: number,
     maxIterations: number,
+    tolerance = 1e-4,
 ): {assignments: number[], centroids: number[][]} {
     const n = data.length;
     const d = data[0]?.length ?? 0;
@@ -480,21 +496,24 @@ function kMeansClustering(
             assignments[i] = bestCluster;
         }
 
-        // Check for convergence
-        let changed = false;
+        // Check for convergence based on assignment changes
+        let assignmentsChanged = false;
         for (let i = 0; i < n; i++) {
             if (assignments[i] !== oldAssignments[i]) {
-                changed = true;
+                assignmentsChanged = true;
                 break;
             }
         }
 
-        if (!changed) {
+        if (!assignmentsChanged) {
             break;
         }
 
         oldAssignments = [... assignments];
 
+        // Store old centroids for tolerance-based convergence check
+        const oldCentroids = centroids.map((c) => [... c]);
+
         // Update centroids
         const counts = Array(k).fill(0) as number[];
         const sums: number[][] = Array.from({length: k}, () => Array(d).fill(0) as number[]);
@@ -534,30 +553,35 @@ function kMeansClustering(
                     for (let j = 0; j < d; j++) {
                         const sumVal = sumsRow[j];
                         if (sumVal !== undefined) {
-                            const countVal = counts[i];
-                            if (countVal !== undefined) {
-                                centroidsRow[j] = sumVal / countVal;
+                            const countValInner = counts[i];
+                            if (countValInner !== undefined) {
+                                centroidsRow[j] = sumVal / countValInner;
                             }
                         }
                     }
                 }
             }
         }
-    }
 
-    return {assignments, centroids};
-}
+        // Check for tolerance-based convergence (centroid movement)
+        let maxCentroidShift = 0;
+        for (let i = 0; i < k; i++) {
+            const oldCentroid = oldCentroids[i];
+            const newCentroid = centroids[i];
+            if (oldCentroid && newCentroid) {
+                const shift = euclideanDistance(oldCentroid, newCentroid);
+                if (shift > maxCentroidShift) {
+                    maxCentroidShift = shift;
+                }
+            }
+        }
 
-/**
- * Calculate Euclidean distance between two vectors
- */
-function euclideanDistance(a: number[], b: number[]): number {
-    let sum = 0;
-    for (let i = 0; i < a.length; i++) {
-        const diff = (a[i] ?? 0) - (b[i] ?? 0);
-        sum += diff * diff;
+        if (maxCentroidShift < tolerance) {
+            break;
+        }
     }
-    return Math.sqrt(sum);
+
+    return {assignments, centroids};
 }
 
 /**

package/src/core/graph.ts

@@ -222,7 +222,7 @@ export class Graph {
      * Get all edges in the graph
      */
     *edges(): IterableIterator<Edge> {
-        for (const [source, edges] of Array.from(this.adjacencyList)) {
+        for (const [source, edges] of this.adjacencyList) {
             for (const edge of edges.values()) {
                 // For undirected graphs, only yield each edge once
                 if (!this.config.directed && source > edge.target) {
@@ -300,12 +300,12 @@ export class Graph {
         const cloned = new Graph(this.config);
 
         // Copy nodes
-        for (const node of Array.from(this.nodeMap.values())) {
+        for (const node of this.nodeMap.values()) {
             cloned.addNode(node.id, node.data ? {... node.data} : undefined);
         }
 
         // Copy edges
-        for (const edge of Array.from(this.edges())) {
+        for (const edge of this.edges()) {
             cloned.addEdge(
                 edge.source,
                 edge.target,
@@ -346,7 +346,7 @@ export class Graph {
         // For undirected graphs, we need to count each edge only once
         let count = 0;
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        for (const _edge of Array.from(this.edges())) {
+        for (const _edge of this.edges()) {
             count++;
         }
         return count;