@graphty/algorithms 1.3.1 → 1.4.2

package/src/clustering/index.ts

@@ -1,8 +1,8 @@
-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";
+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,10 +6,12 @@
  * understanding graph structure.
  */
 
-import type {Graph} from "../core/graph.js";
+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>>();
@@ -49,12 +51,12 @@ export interface KCoreResult<T> {
 
 /**
  * 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
  */
-function kCoreDecompositionImpl<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;
@@ -208,22 +210,18 @@ function kCoreDecompositionImpl<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(
-    graph: Graph,
-    k: number,
-): Set<string> {
-    const {coreness} = kCoreDecomposition(graph);
+export function getKCore(graph: Graph, k: number): Set<string> {
+    const { coreness } = kCoreDecomposition(graph);
     const kCore = new Set<string>();
 
     for (const [node, core] of coreness) {
@@ -238,15 +236,11 @@ export function getKCore(
 /**
  * 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(
-    graph: Graph,
-    k: number,
-): Map<string, Set<string>> {
+export function getKCoreSubgraph(graph: Graph, k: number): Map<string, Set<string>> {
     const kCoreNodes = getKCore(graph, k);
     const adjacencySet = graphToAdjacencySet(graph);
     const subgraph = new Map<string, Set<string>>();
@@ -270,13 +264,10 @@ export function getKCoreSubgraph(
 /**
  * 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(
-    graph: Graph,
-): string[] {
+export function degeneracyOrdering(graph: Graph): string[] {
     const adjacencySet = graphToAdjacencySet(graph);
     const degree = new Map<string, number>();
     const remaining = new Map<string, Set<string>>();
@@ -290,7 +281,7 @@ export function degeneracyOrdering(
 
     // Build ordering
     while (ordering.length < adjacencySet.size) {
-    // Find minimum degree node
+        // Find minimum degree node
         let minDegree = Infinity;
         let minNode: string | undefined;
 
@@ -327,15 +318,11 @@ export function degeneracyOrdering(
 /**
  * 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(
-    graph: Graph,
-    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");
     }
@@ -349,8 +336,9 @@ export function kTruss(
     // Initialize edges
     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);
             }
@@ -367,9 +355,9 @@ export function kTruss(
                     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);
@@ -428,8 +416,8 @@ export function kTruss(
             if (uNeighbors && vNeighbors) {
                 for (const w of uNeighbors) {
                     if (vNeighbors.has(w)) {
-                        const edge1 = u < w ? `${String(u)},${String(w)}` : `${String(w)},${String(u)}`;
-                        const edge2 = v < w ? `${String(v)},${String(w)}` : `${String(w)},${String(v)}`;
+                        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);
@@ -455,10 +443,10 @@ export function kTruss(
 
 /**
  * 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
@@ -491,18 +479,14 @@ export function toUndirected<T>(
 /**
  * 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> {
+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;