@graphty/algorithms 1.1.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;
@@ -59,13 +74,27 @@ export function spectralClustering(
     // Find k smallest eigenvectors
     const eigenResult = findSmallestEigenvectors(laplacianMatrix, k);
 
-    // Normalize the eigenvector matrix row-wise (for normalized spectral clustering)
+    // Perform k-means clustering on the eigenvectors
+    // For spectral clustering, we need to transpose the eigenvector matrix
+    // Each row should be a data point (node) with features from the eigenvectors
+    const dataPoints: number[][] = [];
+    for (let i = 0; i < nodeIds.length; i++) {
+        const point: number[] = [];
+        for (let j = 0; j < k; j++) {
+            const eigenvector = eigenResult.eigenvectors[j];
+            if (eigenvector) {
+                point.push(eigenvector[i] ?? 0);
+            }
+        }
+        dataPoints.push(point);
+    }
+
+    // Normalize the data points row-wise (for normalized spectral clustering)
     if (laplacianType === "normalized") {
-        normalizeRows(eigenResult.eigenvectors);
+        normalizeRows(dataPoints);
     }
 
-    // Perform k-means clustering on the eigenvectors
-    const kmeans = kMeansClustering(eigenResult.eigenvectors, k, maxIterations);
+    const kmeans = kMeansClustering(dataPoints, k, maxIterations, tolerance);
 
     // Build communities
     const communities: NodeId[][] = Array.from({length: k}, () => []);
@@ -265,32 +294,34 @@ function findSmallestEigenvectors(matrix: number[][], k: number): {
         return {eigenvalues: [], eigenvectors: []};
     }
 
-    // For small matrices or when k >= n, use a simplified approach
-    if (n <= 3 || k >= n) {
-        // Create identity-like eigenvectors for simplicity
-        const eigenvectors: number[][] = [];
-        const eigenvalues: number[] = [];
-
-        for (let i = 0; i < Math.min(k, n); i++) {
-            const vector = Array(n).fill(0) as number[];
-            vector[i] = 1;
-            eigenvectors.push(vector);
-            eigenvalues.push(i);
-        }
+    // For very small matrices, use the full power iteration approach
+    // Remove the simplified approach that was causing issues
+    if (k >= n) {
+        // If k >= n, we still need proper eigenvectors, not identity
+        // Fall through to the power iteration below
+    }
 
-        return {eigenvalues, eigenvectors};
+    // For spectral clustering, we need proper eigenvectors
+    // Special handling for small k values which are common in clustering
+    if (k <= 3 && n > k) {
+        return computeSmallestEigenvectorsSimple(matrix, k, n);
     }
 
-    // For larger matrices, use power iteration to find dominant eigenvectors
-    // This is still simplified but better than random
+    // For larger k, use power iteration
     const eigenvectors: number[][] = [];
     const eigenvalues: number[] = [];
-    const maxIterations = 50;
+    const maxIterations = 100;
 
     for (let eigIdx = 0; eigIdx < k; eigIdx++) {
         // Initialize random vector
         let vector = Array(n).fill(0).map(() => Math.random() - 0.5);
 
+        // Normalize initial vector
+        const initNorm = Math.sqrt(vector.reduce((sum, val) => sum + (val * val), 0));
+        if (initNorm > 0) {
+            vector = vector.map((val) => val / initNorm);
+        }
+
         // Orthogonalize against previous eigenvectors
         for (let j = 0; j < eigIdx; j++) {
             const ejVector = eigenvectors[j];
@@ -400,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;
@@ -464,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[]);
@@ -518,28 +553,144 @@ 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;
                             }
                         }
                     }
                 }
             }
         }
+
+        // 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;
+                }
+            }
+        }
+
+        if (maxCentroidShift < tolerance) {
+            break;
+        }
     }
 
     return {assignments, centroids};
 }
 
 /**
- * Calculate Euclidean distance between two vectors
+ * Compute smallest eigenvectors for small k (optimized for k=2, k=3)
  */
-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;
+function computeSmallestEigenvectorsSimple(matrix: number[][], k: number, n: number): {
+    eigenvalues: number[];
+    eigenvectors: number[][];
+} {
+    const eigenvectors: number[][] = [];
+    const eigenvalues: number[] = [];
+
+    // First eigenvector is constant (corresponds to eigenvalue 0 for connected graph)
+    const firstVector = Array(n).fill(1 / Math.sqrt(n)) as number[];
+    eigenvectors.push(firstVector);
+    eigenvalues.push(0);
+
+    // For k >= 2, compute the Fiedler vector (second smallest eigenvector)
+    if (k >= 2) {
+        // Use power iteration on I - L/lambda_max to find second smallest
+        const maxEig = 2; // For normalized Laplacian, max eigenvalue <= 2
+        let vector = Array(n).fill(0).map(() => Math.random() - 0.5);
+
+        // Make orthogonal to first eigenvector
+        const dot1 = vector.reduce((sum, val) => sum + (val / Math.sqrt(n)), 0);
+        vector = vector.map((val) => val - (dot1 / Math.sqrt(n)));
+
+        // Power iteration on shifted matrix
+        for (let iter = 0; iter < 100; iter++) {
+            // Compute (I - L/maxEig) * v
+            const newVector = Array(n).fill(0) as number[];
+
+            // Identity part
+            for (let i = 0; i < n; i++) {
+                newVector[i] = vector[i] ?? 0;
+            }
+
+            // Subtract L * v / maxEig
+            for (let i = 0; i < n; i++) {
+                for (let j = 0; j < n; j++) {
+                    const matrixVal = matrix[i]?.[j] ?? 0;
+                    const vecVal = vector[j] ?? 0;
+                    newVector[i] = (newVector[i] ?? 0) - ((matrixVal * vecVal) / maxEig);
+                }
+            }
+
+            // Orthogonalize against first eigenvector
+            const dot = newVector.reduce((sum, val) => sum + (val / Math.sqrt(n)), 0);
+            for (let i = 0; i < n; i++) {
+                newVector[i] = (newVector[i] ?? 0) - (dot / Math.sqrt(n));
+            }
+
+            // Normalize
+            const norm = Math.sqrt(newVector.reduce((sum, val) => sum + (val * val), 0));
+            if (norm > 1e-10) {
+                vector = newVector.map((val) => val / norm);
+            }
+        }
+
+        eigenvectors.push(vector);
+        eigenvalues.push(0.1); // Approximate
+    }
+
+    // For k = 3, add another eigenvector
+    if (k >= 3) {
+        let vector = Array(n).fill(0).map(() => Math.random() - 0.5);
+
+        // Orthogonalize against previous eigenvectors
+        for (const prev of eigenvectors) {
+            const dot = vector.reduce((sum, val, idx) => sum + (val * (prev[idx] ?? 0)), 0);
+            vector = vector.map((val, idx) => val - (dot * (prev[idx] ?? 0)));
+        }
+
+        // Similar power iteration
+        for (let iter = 0; iter < 50; iter++) {
+            const newVector = Array(n).fill(0) as number[];
+
+            // Identity part
+            for (let i = 0; i < n; i++) {
+                newVector[i] = vector[i] ?? 0;
+            }
+
+            // Subtract L * v / 2
+            for (let i = 0; i < n; i++) {
+                for (let j = 0; j < n; j++) {
+                    const matrixVal = matrix[i]?.[j] ?? 0;
+                    const vecVal = vector[j] ?? 0;
+                    newVector[i] = (newVector[i] ?? 0) - ((matrixVal * vecVal) / 2);
+                }
+            }
+
+            // Orthogonalize
+            for (const prev of eigenvectors) {
+                const dot = newVector.reduce((sum, val, idx) => sum + (val * (prev[idx] ?? 0)), 0);
+                for (let i = 0; i < n; i++) {
+                    newVector[i] = (newVector[i] ?? 0) - (dot * (prev[i] ?? 0));
+                }
+            }
+
+            // Normalize
+            const norm = Math.sqrt(newVector.reduce((sum, val) => sum + (val * val), 0));
+            if (norm > 1e-10) {
+                vector = newVector.map((val) => val / norm);
+            }
+        }
+
+        eigenvectors.push(vector);
+        eigenvalues.push(0.2); // Approximate
     }
-    return Math.sqrt(sum);
+
+    return {eigenvalues: eigenvalues.slice(0, k), eigenvectors: eigenvectors.slice(0, k)};
 }

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;