@graphty/algorithms 1.3.1 → 1.4.2

package/src/algorithms/community/leiden.ts

@@ -8,9 +8,9 @@
  * "From Louvain to Leiden: guaranteeing well-connected communities"
  */
 
-import type {Graph} from "../../core/graph.js";
-import {graphToMap} from "../../utils/graph-converters.js";
-import {SeededRandom, shuffle} from "../../utils/math-utilities.js";
+import type { Graph } from "../../core/graph.js";
+import { graphToMap } from "../../utils/graph-converters.js";
+import { SeededRandom, shuffle } from "../../utils/math-utilities.js";
 
 export interface LeidenOptions {
     resolution?: number;
@@ -28,17 +28,12 @@ export interface LeidenResult {
 /**
  * Internal implementation of Leiden algorithm for community detection
  * Improves upon Louvain by ensuring well-connected communities
+ * @param inputGraph - Map representation of the graph (node to neighbors with weights)
+ * @param options - Algorithm configuration options
+ * @returns Community assignments, modularity score, and iteration count
  */
-function leidenImpl(
-    inputGraph: Map<string, Map<string, number>>,
-    options: LeidenOptions = {},
-): LeidenResult {
-    const {
-        resolution = 1.0,
-        randomSeed = 42,
-        maxIterations = 100,
-        threshold = 1e-7,
-    } = options;
+function leidenImpl(inputGraph: Map<string, Map<string, number>>, options: LeidenOptions = {}): LeidenResult {
+    const { resolution = 1.0, randomSeed = 42, maxIterations = 100, threshold = 1e-7 } = options;
 
     // Handle empty graph
     if (inputGraph.size === 0) {
@@ -85,7 +80,7 @@ function leidenImpl(
         let improved = false;
 
         // Phase 1: Local moving of nodes (fast)
-        const nodeOrder = [... nodes];
+        const nodeOrder = [...nodes];
         shuffle(nodeOrder, random);
 
         for (const node of nodeOrder) {
@@ -106,7 +101,13 @@ function leidenImpl(
                 }
 
                 const gain = calculateModularityGain(
-                    node, community, currentGraph, communities, degrees, totalWeight, resolution,
+                    node,
+                    community,
+                    currentGraph,
+                    communities,
+                    degrees,
+                    totalWeight,
+                    resolution,
                 );
 
                 if (gain > bestGain) {
@@ -128,9 +129,7 @@ function leidenImpl(
         createAggregateNetwork(currentGraph, communities);
 
         // Refine partition using aggregate network
-        const subsetPartition = refinePartition(
-            currentGraph, communities,
-        );
+        const subsetPartition = refinePartition(currentGraph, communities);
 
         // Apply refined partition
         for (const [node, newCommunity] of subsetPartition) {
@@ -158,7 +157,7 @@ function leidenImpl(
         } // No aggregation possible
 
         // Continue with aggregated network
-        const {graph: aggregatedGraph} = aggregated;
+        const { graph: aggregatedGraph } = aggregated;
         currentGraph = aggregatedGraph;
         communities.clear();
         let communityId = 0;
@@ -195,6 +194,12 @@ function leidenImpl(
 
 /**
  * Calculate modularity of a partition
+ * @param graph - Map representation of the graph
+ * @param communities - Map of node IDs to community IDs
+ * @param degrees - Map of node IDs to their weighted degrees
+ * @param totalWeight - Total weight of all edges in the graph
+ * @param resolution - Resolution parameter for modularity calculation
+ * @returns The modularity score of the partition
  */
 function calculateModularity(
     graph: Map<string, Map<string, number>>,
@@ -236,11 +241,11 @@ function calculateModularity(
     }
 
     // Normalize and apply resolution
-    modularity /= (2 * totalWeight);
+    modularity /= 2 * totalWeight;
 
     // Subtract expected edges
     for (const weight of communityWeights.values()) {
-        modularity -= resolution * ((weight / (2 * totalWeight)) ** 2);
+        modularity -= resolution * (weight / (2 * totalWeight)) ** 2;
     }
 
     return modularity;
@@ -248,6 +253,10 @@ function calculateModularity(
 
 /**
  * Get communities of neighbors
+ * @param node - The node ID to get neighbor communities for
+ * @param graph - Map representation of the graph
+ * @param communities - Map of node IDs to community IDs
+ * @returns Map of community IDs to total edge weight connecting to that community
  */
 function getNeighborCommunities(
     node: string,
@@ -271,6 +280,14 @@ function getNeighborCommunities(
 
 /**
  * Calculate modularity gain from moving a node to a community
+ * @param node - The node ID to move
+ * @param targetCommunity - The target community ID
+ * @param graph - Map representation of the graph
+ * @param communities - Map of node IDs to community IDs
+ * @param degrees - Map of node IDs to their weighted degrees
+ * @param totalWeight - Total weight of all edges in the graph
+ * @param resolution - Resolution parameter for modularity calculation
+ * @returns The modularity gain from moving the node to the target community
  */
 function calculateModularityGain(
     node: string,
@@ -327,22 +344,26 @@ function calculateModularityGain(
 
     // Modularity gain calculation
     const m2 = 2 * totalWeight;
-    const gain = ((weightToTarget - weightToCurrent) / totalWeight) -
-    (resolution * nodeDegree * (targetDegree - currentDegree) / (m2 * m2));
+    const gain =
+        (weightToTarget - weightToCurrent) / totalWeight -
+        (resolution * nodeDegree * (targetDegree - currentDegree)) / (m2 * m2);
 
     return gain;
 }
 
 /**
  * Create aggregate network where each community becomes a super-node
+ * @param graph - Map representation of the graph
+ * @param communities - Map of node IDs to community IDs
+ * @returns Object with aggregate graph and node-to-community mapping
  */
 function createAggregateNetwork(
     graph: Map<string, Map<string, number>>,
     communities: Map<string, number>,
 ): {
-        aggregateGraph: Map<number, Map<number, number>>;
-        nodeMapping: Map<string, number>;
-    } {
+    aggregateGraph: Map<number, Map<number, number>>;
+    nodeMapping: Map<string, number>;
+} {
     const aggregateGraph = new Map<number, Map<number, number>>();
     const nodeMapping = new Map<string, number>();
 
@@ -375,12 +396,15 @@ function createAggregateNetwork(
         }
     }
 
-    return {aggregateGraph, nodeMapping};
+    return { aggregateGraph, nodeMapping };
 }
 
 /**
  * Refine partition (Leiden-specific improvement)
  * Ensures well-connected communities by considering subsets
+ * @param originalGraph - Map representation of the original graph
+ * @param communities - Map of node IDs to community IDs
+ * @returns Refined community assignments with well-connected communities
  */
 function refinePartition(
     originalGraph: Map<string, Map<string, number>>,
@@ -448,6 +472,8 @@ function refinePartition(
 
 /**
  * Find connected components in undirected graph
+ * @param graph - Map representation of the graph (node to set of neighbors)
+ * @returns Array of connected components (each is a set of node IDs)
  */
 function findConnectedComponents(graph: Map<string, Set<string>>): Set<string>[] {
     const visited = new Set<string>();
@@ -486,14 +512,17 @@ function findConnectedComponents(graph: Map<string, Set<string>>): Set<string>[]
 
 /**
  * Aggregate communities into super-nodes
+ * @param graph - Map representation of the graph
+ * @param communities - Map of node IDs to community IDs
+ * @returns Object with aggregated graph and node-to-supernode mapping
  */
 function aggregateCommunities(
     graph: Map<string, Map<string, number>>,
     communities: Map<string, number>,
 ): {
-        graph: Map<string, Map<string, number>>;
-        mapping: Map<string, string>;
-    } {
+    graph: Map<string, Map<string, number>>;
+    mapping: Map<string, string>;
+} {
     const aggregated = new Map<string, Map<string, number>>();
     const mapping = new Map<string, string>();
 
@@ -546,13 +575,12 @@ function aggregateCommunities(
         }
     }
 
-    return {graph: aggregated, mapping};
+    return { graph: aggregated, mapping };
 }
 
 /**
  * Leiden algorithm for community detection
  * Improves upon Louvain by ensuring well-connected communities
- *
  * @param graph - Undirected weighted graph - accepts Graph class or Map representation
  * @param options - Algorithm options
  * @returns Community assignments and modularity
@@ -560,12 +588,8 @@ function aggregateCommunities(
  * Time Complexity: O(m) per iteration, typically O(m log m) total
  * Space Complexity: O(n + m)
  */
-export function leiden(
-    graph: Graph,
-    options: LeidenOptions = {},
-): LeidenResult {
+export function leiden(graph: Graph, options: LeidenOptions = {}): LeidenResult {
     // Convert Graph to Map representation
     const graphMap = graphToMap(graph);
     return leidenImpl(graphMap, options);
 }
-

package/src/algorithms/community/louvain-optimized.ts

@@ -1,5 +1,5 @@
-import type {Graph} from "../../core/graph.js";
-import type {CommunityResult, NodeId} from "../../types/index.js";
+import type { Graph } from "../../core/graph.js";
+import type { CommunityResult, NodeId } from "../../types/index.js";
 
 /**
  * Optimized Louvain community detection algorithm with early pruning and threshold cycling
@@ -50,6 +50,9 @@ interface PruningStats {
     stableNodesPruned: number;
 }
 
+/**
+ * Optimized Louvain implementation with early pruning and threshold cycling
+ */
 export class OptimizedLouvain {
     private graph: Graph;
     private communities: Map<NodeId, number>;
@@ -59,6 +62,10 @@ export class OptimizedLouvain {
     private totalWeight: number;
     private pruningStats: PruningStats;
 
+    /**
+     * Create an optimized Louvain detector for the given graph
+     * @param graph - The input graph to detect communities in
+     */
     constructor(graph: Graph) {
         this.graph = graph;
         this.communities = new Map();
@@ -75,6 +82,8 @@ export class OptimizedLouvain {
 
     /**
      * Run optimized Louvain algorithm
+     * @param options - Algorithm configuration options
+     * @returns Community detection result with communities, modularity, and iterations
      */
     public detectCommunities(options: OptimizedLouvainOptions = {}): CommunityResult {
         const {
@@ -95,14 +104,12 @@ export class OptimizedLouvain {
 
         while (iteration < maxIterations && improved) {
             // Get nodes in optimal processing order
-            const orderedNodes = importanceOrdering ?
-                this.getNodesInImportanceOrder() :
-                Array.from(this.graph.nodes()).map((n) => n.id);
+            const orderedNodes = importanceOrdering
+                ? this.getNodesInImportanceOrder()
+                : Array.from(this.graph.nodes()).map((n) => n.id);
 
             // Apply adaptive threshold
-            const threshold = thresholdCycling ?
-                this.getAdaptiveThreshold(iteration, pruningThreshold) :
-                0;
+            const threshold = thresholdCycling ? this.getAdaptiveThreshold(iteration, pruningThreshold) : 0;
 
             // Perform local optimization
             improved = this.performLocalMoving(orderedNodes, {
@@ -193,6 +200,7 @@ export class OptimizedLouvain {
 
     /**
      * Get nodes ordered by importance (degree * log(weight))
+     * @returns Array of node IDs sorted by descending importance
      */
     private getNodesInImportanceOrder(): NodeId[] {
         const nodeImportance = new Map<NodeId, number>();
@@ -213,6 +221,12 @@ export class OptimizedLouvain {
 
     /**
      * Perform local moving phase with optimizations
+     * @param nodes - Array of node IDs to process
+     * @param options - Local moving options
+     * @param options.pruneLeaves - Whether to skip leaf nodes
+     * @param options.threshold - Minimum gain threshold for moves
+     * @param options.resolution - Resolution parameter for modularity
+     * @returns True if any improvement was made, false otherwise
      */
     private performLocalMoving(
         nodes: NodeId[],
@@ -222,7 +236,7 @@ export class OptimizedLouvain {
             resolution: number;
         },
     ): boolean {
-        const {pruneLeaves, threshold, resolution} = options;
+        const { pruneLeaves, threshold, resolution } = options;
         let improvement = false;
         let hasChanged = true;
 
@@ -284,6 +298,8 @@ export class OptimizedLouvain {
 
     /**
      * Check if node is a leaf (degree 1)
+     * @param nodeId - The node ID to check
+     * @returns True if the node has degree 1, false otherwise
      */
     private isLeafNode(nodeId: NodeId): boolean {
         const degree = this.nodeDegrees.get(nodeId) ?? 0;
@@ -292,6 +308,9 @@ export class OptimizedLouvain {
 
     /**
      * Get adaptive threshold that decreases with iterations
+     * @param iteration - Current iteration number
+     * @param baseThreshold - Base threshold value to scale
+     * @returns Adaptive threshold value that decays over iterations
      */
     private getAdaptiveThreshold(iteration: number, baseThreshold: number): number {
         // Exponentially decay threshold with iterations
@@ -301,12 +320,12 @@ export class OptimizedLouvain {
 
     /**
      * Calculate modularity gain from moving a node to a community
+     * @param nodeId - The node ID to move
+     * @param targetCommunity - The target community ID
+     * @param resolution - Resolution parameter for modularity calculation
+     * @returns The modularity gain from moving the node
      */
-    private calculateModularityGain(
-        nodeId: NodeId,
-        targetCommunity: number,
-        resolution: number,
-    ): number {
+    private calculateModularityGain(nodeId: NodeId, targetCommunity: number, resolution: number): number {
         const nodeWeight = this.nodeWeights.get(nodeId) ?? 0;
 
         // Sum of weights from node to target community
@@ -333,13 +352,16 @@ export class OptimizedLouvain {
         const targetWeight = this.communityWeights.get(targetCommunity) ?? 0;
 
         // Modularity gain formula
-        const gain = (weightToTarget - ((resolution * nodeWeight * targetWeight) / (2 * this.totalWeight))) / this.totalWeight;
+        const gain =
+            (weightToTarget - (resolution * nodeWeight * targetWeight) / (2 * this.totalWeight)) / this.totalWeight;
 
         return gain;
     }
 
     /**
      * Remove node from community (for gain calculation)
+     * @param nodeId - The node ID to remove
+     * @param community - The community ID to remove from
      */
     private removeNodeFromCommunity(nodeId: NodeId, community: number): void {
         const nodeWeight = this.nodeWeights.get(nodeId) ?? 0;
@@ -349,6 +371,8 @@ export class OptimizedLouvain {
 
     /**
      * Add node to community
+     * @param nodeId - The node ID to add
+     * @param community - The community ID to add to
      */
     private addNodeToCommunity(nodeId: NodeId, community: number): void {
         const nodeWeight = this.nodeWeights.get(nodeId) ?? 0;
@@ -358,6 +382,8 @@ export class OptimizedLouvain {
 
     /**
      * Get neighboring communities of a node
+     * @param nodeId - The node ID to find neighbor communities for
+     * @returns Set of community IDs that neighbors belong to
      */
     private getNeighborCommunities(nodeId: NodeId): Set<number> {
         const communities = new Set<number>();
@@ -384,6 +410,8 @@ export class OptimizedLouvain {
 
     /**
      * Calculate total modularity
+     * @param resolution - Resolution parameter for modularity calculation
+     * @returns The modularity score of the current partition
      */
     private calculateModularity(resolution: number): number {
         if (this.totalWeight === 0) {
@@ -427,19 +455,20 @@ export class OptimizedLouvain {
 
     /**
      * Get pruning statistics
+     * @returns Statistics about nodes pruned during optimization
      */
     public getPruningStats(): PruningStats {
-        return {... this.pruningStats};
+        return { ...this.pruningStats };
     }
 }
 
 /**
  * Optimized Louvain algorithm with automatic optimization selection
+ * @param graph - The input graph to detect communities in
+ * @param options - Algorithm configuration options
+ * @returns Community detection result with communities, modularity, and iterations
  */
-export function louvainOptimized(
-    graph: Graph,
-    options: OptimizedLouvainOptions = {},
-): CommunityResult {
+export function louvainOptimized(graph: Graph, options: OptimizedLouvainOptions = {}): CommunityResult {
     const optimizer = new OptimizedLouvain(graph);
     return optimizer.detectCommunities(options);
 }

package/src/algorithms/community/louvain.ts

@@ -1,12 +1,7 @@
-import {Graph} from "../../core/graph.js";
-import type {CommunityResult, LouvainOptions, NodeId} from "../../types/index.js";
-import {louvainOptimized} from "./louvain-optimized.js";
-import {
-    calculateModularity,
-    getNeighborCommunities,
-    getNodeDegree,
-    getTotalEdgeWeight,
-} from "./modularity-utils.js";
+import { Graph } from "../../core/graph.js";
+import type { CommunityResult, LouvainOptions, NodeId } from "../../types/index.js";
+import { louvainOptimized } from "./louvain-optimized.js";
+import { calculateModularity, getNeighborCommunities, getNodeDegree, getTotalEdgeWeight } from "./modularity-utils.js";
 
 /**
  * Louvain community detection algorithm
@@ -16,17 +11,13 @@ import {
  *
  * References:
  * - Blondel, V. D., Guillaume, J. L., Lambiotte, R., & Lefebvre, E. (2008).
- *   Fast unfolding of communities in large networks.
- *   Journal of statistical mechanics: theory and experiment, 2008(10), P10008.
- *
+ * Fast unfolding of communities in large networks.
+ * Journal of statistical mechanics: theory and experiment, 2008(10), P10008.
  * @param graph - The input graph
  * @param options - Algorithm options
  * @returns Community detection result with communities, modularity, and iterations
  */
-export function louvain(
-    graph: Graph,
-    options: LouvainOptions = {},
-): CommunityResult {
+export function louvain(graph: Graph, options: LouvainOptions = {}): CommunityResult {
     const resolution = options.resolution ?? 1.0;
     const maxIterations = options.maxIterations ?? 100;
     const tolerance = options.tolerance ?? 1e-6;
@@ -62,7 +53,7 @@ export function louvain(
             const newModularity = calculateModularity(graph, communities, resolution);
 
             // Check for convergence
-            if ((newModularity - modularity) < tolerance) {
+            if (newModularity - modularity < tolerance) {
                 break;
             }
 
@@ -80,6 +71,8 @@ export function louvain(
 
 /**
  * Initialize communities: each node in its own community
+ * @param graph - The input graph
+ * @returns Map of node IDs to their initial community IDs
  */
 function initializeCommunities(graph: Graph): Map<NodeId, number> {
     const communities = new Map<NodeId, number>();
@@ -96,12 +89,12 @@ function initializeCommunities(graph: Graph): Map<NodeId, number> {
  * Phase 1 of Louvain algorithm: Local optimization
  * For each node, try moving to neighboring communities and keep the move
  * that provides the best modularity gain.
+ * @param graph - The input graph
+ * @param communities - Map of node IDs to community IDs
+ * @param resolution - Resolution parameter for modularity calculation
+ * @returns True if any improvement was made, false otherwise
  */
-function louvainPhase1(
-    graph: Graph,
-    communities: Map<NodeId, number>,
-    resolution: number,
-): boolean {
+function louvainPhase1(graph: Graph, communities: Map<NodeId, number>, resolution: number): boolean {
     let globalImprovement = false;
     let localImprovement = true;
 
@@ -118,7 +111,11 @@ function louvainPhase1(
 
             // Calculate current modularity contribution
             const currentModularity = nodeModularityContribution(
-                graph, nodeId, currentCommunity, communities, resolution,
+                graph,
+                nodeId,
+                currentCommunity,
+                communities,
+                resolution,
             );
 
             let bestCommunity = currentCommunity;
@@ -133,7 +130,11 @@ function louvainPhase1(
                 }
 
                 const newModularity = nodeModularityContribution(
-                    graph, nodeId, neighborCommunity, communities, resolution,
+                    graph,
+                    nodeId,
+                    neighborCommunity,
+                    communities,
+                    resolution,
                 );
 
                 if (newModularity > bestModularity) {
@@ -156,6 +157,12 @@ function louvainPhase1(
 
 /**
  * Calculate modularity contribution of a node to a specific community
+ * @param graph - The input graph
+ * @param nodeId - The node ID to evaluate
+ * @param community - The community to measure contribution to
+ * @param communities - Map of all node IDs to community IDs
+ * @param resolution - Resolution parameter for modularity calculation
+ * @returns The modularity contribution of the node to the specified community
  */
 function nodeModularityContribution(
     graph: Graph,
@@ -192,13 +199,16 @@ function nodeModularityContribution(
     }
 
     // Modularity formula: Q = (1/2m) * Σ[A_ij - (k_i * k_j)/(2m)] * δ(c_i, c_j)
-    const modularityIncrease = (internalLinks - ((resolution * nodeDegree * communityDegree) / (2 * totalEdgeWeight))) / totalEdgeWeight;
+    const modularityIncrease =
+        (internalLinks - (resolution * nodeDegree * communityDegree) / (2 * totalEdgeWeight)) / totalEdgeWeight;
 
     return modularityIncrease;
 }
 
 /**
  * Extract final community structure
+ * @param communities - Map of node IDs to community IDs
+ * @returns Array of communities (each is an array of node IDs)
  */
 function extractCommunities(communities: Map<NodeId, number>): NodeId[][] {
     const communityMap = new Map<number, NodeId[]>();

package/src/algorithms/community/modularity-utils.ts

@@ -3,15 +3,14 @@
  *
  * Used by: Louvain, Leiden, Girvan-Newman
  */
-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";
 
 /**
  * Calculate total edge weight in the graph
  *
  * For undirected graphs, each edge is counted once.
  * For directed graphs, each directed edge is counted once.
- *
  * @param graph - The input graph
  * @returns Total sum of edge weights (default weight is 1)
  */
@@ -29,7 +28,6 @@ export function getTotalEdgeWeight(graph: Graph): number {
  * Get the total degree (sum of edge weights) for a node
  *
  * Computes the weighted degree by summing all edge weights incident to the node.
- *
  * @param graph - The input graph
  * @param nodeId - The node ID to compute degree for
  * @returns The weighted degree of the node
@@ -49,17 +47,12 @@ export function getNodeDegree(graph: Graph, nodeId: NodeId): number {
  * Get communities of neighboring nodes
  *
  * Returns the set of community IDs that neighbors of the given node belong to.
- *
  * @param graph - The input graph
  * @param nodeId - The node to get neighbor communities for
  * @param communities - Map from node IDs to community IDs
  * @returns Set of community IDs that neighbors belong to
  */
-export function getNeighborCommunities(
-    graph: Graph,
-    nodeId: NodeId,
-    communities: Map<NodeId, number>,
-): Set<number> {
+export function getNeighborCommunities(graph: Graph, nodeId: NodeId, communities: Map<NodeId, number>): Set<number> {
     const neighborCommunities = new Set<number>();
 
     for (const neighbor of graph.neighbors(nodeId)) {
@@ -85,17 +78,12 @@ export function getNeighborCommunities(
  * - k_i, k_j = degrees of nodes i and j
  * - γ = resolution parameter (higher values favor smaller communities)
  * - δ = Kronecker delta (1 if same community, 0 otherwise)
- *
  * @param graph - The input graph
  * @param communities - Map from node IDs to community IDs
  * @param resolution - Resolution parameter (default: 1.0)
  * @returns Modularity score (range typically -0.5 to 1.0)
  */
-export function calculateModularity(
-    graph: Graph,
-    communities: Map<NodeId, number>,
-    resolution = 1.0,
-): number {
+export function calculateModularity(graph: Graph, communities: Map<NodeId, number>, resolution = 1.0): number {
     const totalEdgeWeight = getTotalEdgeWeight(graph);
     if (totalEdgeWeight === 0) {
         return 0;
@@ -137,7 +125,7 @@ export function calculateModularity(
                 const degreeI = getNodeDegree(graph, nodeI.id);
                 const degreeJ = getNodeDegree(graph, nodeJ.id);
 
-                modularity += edgeWeight - ((resolution * degreeI * degreeJ) / (2 * totalEdgeWeight));
+                modularity += edgeWeight - (resolution * degreeI * degreeJ) / (2 * totalEdgeWeight);
             }
         }
     }