@graphty/algorithms 1.2.0 → 1.4.2

package/src/clustering/index.ts

@@ -1,6 +1,8 @@
-export * from "./hierarchical.js";
-export * from "./k-core.js";
-export type {MCLOptions, MCLResult} from "./mcl.js";
-export {calculateMCLModularity, markovClustering} from "./mcl.js";
-export type {SpectralClusteringOptions, SpectralClusteringResult} from "./spectral.js";
-export {spectralClustering} from "./spectral.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";
+export { spectralClustering } from "./spectral.js";

package/src/clustering/k-core.ts

@@ -6,6 +6,43 @@
  * understanding graph structure.
  */
 
+import type { Graph } from "../core/graph.js";
+
+/**
+ * Convert Graph to adjacency set representation
+ * @param graph - The input graph to convert
+ * @returns Map of node IDs to sets of neighbor node IDs
+ */
+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,20 +50,13 @@ 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
+ * @param graph - Adjacency map representation of the graph
+ * @returns K-core decomposition result with cores, coreness values, and maximum core number
  */
-export function kCoreDecomposition<T>(
-    graph: Map<T, Set<T>>,
-): KCoreResult<T> {
+function kCoreDecompositionImpl<T>(graph: Map<T, Set<T>>): KCoreResult<T> {
     if (graph.size === 0) {
-        return {cores: new Map(), coreness: new Map(), maxCore: 0};
+        return { cores: new Map(), coreness: new Map(), maxCore: 0 };
     }
 
     const n = graph.size;
@@ -180,23 +210,19 @@ export function kCoreDecomposition<T>(
         maxCore = Math.max(maxCore, core);
     }
 
-    return {cores, coreness, maxCore};
+    return { cores, coreness, maxCore };
 }
 
 /**
  * Extract the k-core subgraph
  * Returns nodes that belong to k-core or higher
- *
  * @param graph - Undirected graph
  * @param k - Core number
  * @returns Set of nodes in k-core or higher
  */
-export function getKCore<T>(
-    graph: Map<T, Set<T>>,
-    k: number,
-): Set<T> {
-    const {coreness} = kCoreDecomposition(graph);
-    const kCore = new Set<T>();
+export function getKCore(graph: Graph, k: number): Set<string> {
+    const { coreness } = kCoreDecomposition(graph);
+    const kCore = new Set<string>();
 
     for (const [node, core] of coreness) {
         if (core >= k) {
@@ -210,22 +236,19 @@ export function getKCore<T>(
 /**
  * Get the induced subgraph for k-core
  * Returns the actual subgraph containing only k-core nodes
- *
  * @param graph - Original graph
  * @param k - Core number
  * @returns K-core subgraph
  */
-export function getKCoreSubgraph<T>(
-    graph: Map<T, Set<T>>,
-    k: number,
-): Map<T, Set<T>> {
+export function getKCoreSubgraph(graph: Graph, k: number): 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);
@@ -241,28 +264,26 @@ export function getKCoreSubgraph<T>(
 /**
  * Degeneracy ordering of the graph
  * Orders nodes by their coreness values
- *
  * @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) {
-    // Find minimum degree node
+    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) {
@@ -297,28 +318,27 @@ export function degeneracyOrdering<T>(
 /**
  * Find k-truss subgraph (triangular k-cores)
  * Each edge must be part of at least k-2 triangles
- *
  * @param graph - Undirected graph
  * @param k - Truss number (k >= 2)
  * @returns Edges in k-truss
  */
-export function kTruss<T>(
-    graph: Map<T, Set<T>>,
-    k: number,
-): Set<string> {
+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)}`;
+            if (u < v) {
+                // Avoid duplicates
+                const edge = `${u},${v}`;
                 edges.add(edge);
                 edgeTriangles.set(edge, 0);
             }
@@ -326,18 +346,18 @@ 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) {
                         if (v < w && vNeighbors.has(w)) {
                             // Triangle found: u-v-w
-                            const edge1 = `${String(u)},${String(v)}`;
-                            const edge2 = `${String(u)},${String(w)}`;
-                            const edge3 = `${String(v)},${String(w)}`;
+                            const edge1 = `${u},${v}`;
+                            const edge2 = `${u},${w}`;
+                            const edge3 = `${v},${w}`;
 
                             const edge1Count = edgeTriangles.get(edge1);
                             const edge2Count = edgeTriangles.get(edge2);
@@ -390,16 +410,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 ? `${u},${w}` : `${w},${u}`;
+                        const edge2 = v < w ? `${v},${w}` : `${w},${v}`;
 
                         if (kTrussEdges.has(edge1)) {
                             const edge1Count = edgeTriangles.get(edge1);
@@ -425,10 +443,10 @@ export function kTruss<T>(
 
 /**
  * Convert directed graph to undirected for k-core analysis
+ * @param directedGraph - Directed graph represented as adjacency map with edge weights
+ * @returns Undirected graph represented as adjacency map with neighbor sets
  */
-export function toUndirected<T>(
-    directedGraph: Map<T, Map<T, number>>,
-): Map<T, Set<T>> {
+export function toUndirected<T>(directedGraph: Map<T, Map<T, number>>): Map<T, Set<T>> {
     const undirected = new Map<T, Set<T>>();
 
     // Initialize all nodes
@@ -458,3 +476,17 @@ 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/mcl.ts

@@ -1,5 +1,5 @@
-import type {Graph} from "../core/graph.js";
-import type {NodeId} from "../types/index.js";
+import type { Graph } from "../core/graph.js";
+import type { NodeId } from "../types/index.js";
 
 /**
  * Markov Clustering (MCL) algorithm implementation
@@ -31,11 +31,11 @@ export interface MCLResult {
 
 /**
  * Perform Markov Clustering on a graph
+ * @param graph - The input graph to cluster
+ * @param options - MCL algorithm options (expansion, inflation, iterations, etc.)
+ * @returns MCL clustering result with communities, attractors, and convergence info
  */
-export function markovClustering(
-    graph: Graph,
-    options: MCLOptions = {},
-): MCLResult {
+export function markovClustering(graph: Graph, options: MCLOptions = {}): MCLResult {
     const {
         expansion = 2,
         inflation = 2,
@@ -65,7 +65,7 @@ export function markovClustering(
     let iteration = 0;
 
     for (iteration = 0; iteration < maxIterations; iteration++) {
-        const oldMatrix = matrix.map((row) => [... row]);
+        const oldMatrix = matrix.map((row) => [...row]);
 
         // Expansion step (matrix multiplication)
         matrix = matrixPower(matrix, expansion);
@@ -84,7 +84,7 @@ export function markovClustering(
     }
 
     // Extract clusters from final matrix
-    const {communities, attractors} = extractClusters(matrix, nodeIds);
+    const { communities, attractors } = extractClusters(matrix, nodeIds);
 
     return {
         communities,
@@ -96,10 +96,14 @@ export function markovClustering(
 
 /**
  * Build initial transition matrix from graph
+ * @param graph - The input graph
+ * @param nodeIds - Array of node IDs in the graph
+ * @param selfLoops - Whether to add self-loops to the matrix
+ * @returns Column-normalized transition matrix
  */
 function buildTransitionMatrix(graph: Graph, nodeIds: NodeId[], selfLoops: boolean): number[][] {
     const n = nodeIds.length;
-    const matrix = Array.from({length: n}, (): number[] => Array(n).fill(0) as number[]);
+    const matrix = Array.from({ length: n }, (): number[] => Array(n).fill(0) as number[]);
     const nodeToIndex = new Map<NodeId, number>();
 
     nodeIds.forEach((id, index) => nodeToIndex.set(id, index));
@@ -168,6 +172,9 @@ function buildTransitionMatrix(graph: Graph, nodeIds: NodeId[], selfLoops: boole
 
 /**
  * Raise matrix to a power (for expansion step)
+ * @param matrix - Input square matrix
+ * @param power - Power to raise the matrix to
+ * @returns Matrix raised to the specified power
  */
 function matrixPower(matrix: number[][], power: number): number[][] {
     if (power === 1) {
@@ -187,13 +194,16 @@ function matrixPower(matrix: number[][], power: number): number[][] {
 
 /**
  * Multiply two matrices
+ * @param a - First matrix
+ * @param b - Second matrix
+ * @returns Product matrix a * b
  */
 function matrixMultiply(a: number[][], b: number[][]): number[][] {
     const n = a.length;
     const m = b[0]?.length ?? 0;
     const p = b.length;
 
-    const result: number[][] = Array.from({length: n}, () => Array(m).fill(0) as number[]);
+    const result: number[][] = Array.from({ length: n }, () => Array(m).fill(0) as number[]);
 
     for (let i = 0; i < n; i++) {
         for (let j = 0; j < m; j++) {
@@ -207,7 +217,7 @@ function matrixMultiply(a: number[][], b: number[][]): number[][] {
 
                 const prevVal = resultRow[j];
                 if (prevVal !== undefined) {
-                    resultRow[j] = prevVal + (aVal * bVal);
+                    resultRow[j] = prevVal + aVal * bVal;
                 }
             }
         }
@@ -218,10 +228,13 @@ function matrixMultiply(a: number[][], b: number[][]): number[][] {
 
 /**
  * Inflation step: element-wise powering and column normalization
+ * @param matrix - Input matrix to inflate
+ * @param inflation - Inflation parameter for element-wise powering
+ * @returns Inflated and column-normalized matrix
  */
 function inflate(matrix: number[][], inflation: number): number[][] {
     const n = matrix.length;
-    const result: number[][] = Array.from({length: n}, () => Array(n).fill(0) as number[]);
+    const result: number[][] = Array.from({ length: n }, () => Array(n).fill(0) as number[]);
 
     // Element-wise powering
     for (let i = 0; i < n; i++) {
@@ -266,10 +279,13 @@ function inflate(matrix: number[][], inflation: number): number[][] {
 
 /**
  * Pruning step: remove small values
+ * @param matrix - Input matrix to prune
+ * @param threshold - Values below this threshold are set to zero
+ * @returns Pruned and re-normalized matrix
  */
 function prune(matrix: number[][], threshold: number): number[][] {
     const n = matrix.length;
-    const result: number[][] = Array.from({length: n}, () => Array(n).fill(0) as number[]);
+    const result: number[][] = Array.from({ length: n }, () => Array(n).fill(0) as number[]);
 
     for (let i = 0; i < n; i++) {
         for (let j = 0; j < n; j++) {
@@ -323,6 +339,10 @@ function prune(matrix: number[][], threshold: number): number[][] {
 
 /**
  * Check if the algorithm has converged
+ * @param oldMatrix - Matrix from previous iteration
+ * @param newMatrix - Matrix from current iteration
+ * @param tolerance - Convergence tolerance threshold
+ * @returns True if the maximum difference between matrices is below tolerance
  */
 function hasConverged(oldMatrix: number[][], newMatrix: number[][], tolerance: number): boolean {
     const n = oldMatrix.length;
@@ -348,8 +368,14 @@ function hasConverged(oldMatrix: number[][], newMatrix: number[][], tolerance: n
 
 /**
  * Extract clusters from the final matrix
+ * @param matrix - Final converged MCL matrix
+ * @param nodeIds - Array of node IDs corresponding to matrix indices
+ * @returns Object containing communities and attractor nodes
  */
-function extractClusters(matrix: number[][], nodeIds: NodeId[]): {
+function extractClusters(
+    matrix: number[][],
+    nodeIds: NodeId[],
+): {
     communities: NodeId[][];
     attractors: Set<NodeId>;
 } {
@@ -391,10 +417,14 @@ function extractClusters(matrix: number[][], nodeIds: NodeId[]): {
         }
 
         if (clusterNodes.length > 0) {
-            communities.push(clusterNodes.map((idx) => {
-                const nodeId = nodeIds[idx];
-                return nodeId;
-            }).filter((node): node is NodeId => node !== undefined));
+            communities.push(
+                clusterNodes
+                    .map((idx) => {
+                        const nodeId = nodeIds[idx];
+                        return nodeId;
+                    })
+                    .filter((node): node is NodeId => node !== undefined),
+            );
             clusterIndex++;
         }
     }
@@ -411,16 +441,16 @@ function extractClusters(matrix: number[][], nodeIds: NodeId[]): {
         }
     }
 
-    return {communities, attractors};
+    return { communities, attractors };
 }
 
 /**
  * Calculate modularity of MCL clustering result
+ * @param graph - The original graph that was clustered
+ * @param communities - Array of communities (each community is an array of node IDs)
+ * @returns Modularity score between -0.5 and 1.0
  */
-export function calculateMCLModularity(
-    graph: Graph,
-    communities: NodeId[][],
-): number {
+export function calculateMCLModularity(graph: Graph, communities: NodeId[][]): number {
     const m = graph.totalEdgeCount;
     if (m === 0) {
         return 0;