@graphty/algorithms 1.3.1 → 1.5.0

package/src/algorithms/community/girvan-newman.ts

@@ -1,6 +1,6 @@
-import {Graph} from "../../core/graph.js";
-import type {CommunityResult, ComponentResult, GirvanNewmanOptions, NodeId} from "../../types/index.js";
-import {connectedComponents} from "../components/connected.js";
+import { Graph } from "../../core/graph.js";
+import type { CommunityResult, ComponentResult, GirvanNewmanOptions, NodeId } from "../../types/index.js";
+import { connectedComponents } from "../components/connected.js";
 
 /**
  * Girvan-Newman community detection algorithm
@@ -14,18 +14,14 @@ import {connectedComponents} from "../components/connected.js";
  *
  * References:
  * - Girvan, M., & Newman, M. E. J. (2002). Community structure in social
- *   and biological networks. Proceedings of the National Academy of Sciences,
- *   99(12), 7821-7826.
- *
+ * and biological networks. Proceedings of the National Academy of Sciences,
+ * 99(12), 7821-7826.
  * @param graph - The input graph
  * @param options - Algorithm options
  * @returns Array of community detection results representing the dendrogram
  */
-export function girvanNewman(
-    graph: Graph,
-    options: GirvanNewmanOptions = {},
-): CommunityResult[] {
-    const {maxCommunities} = options;
+export function girvanNewman(graph: Graph, options: GirvanNewmanOptions = {}): CommunityResult[] {
+    const { maxCommunities } = options;
     const minCommunitySize = options.minCommunitySize ?? 1;
     const maxIterations = options.maxIterations ?? 100; // Prevent infinite loops
 
@@ -50,20 +46,20 @@ export function girvanNewman(
         }
 
         // Find edges with maximum betweenness
-        const maxBetweenness = Math.max(... edgeBetweenness.values());
-        const edgesToRemove: {source: NodeId, target: NodeId}[] = [];
+        const maxBetweenness = Math.max(...edgeBetweenness.values());
+        const edgesToRemove: { source: NodeId; target: NodeId }[] = [];
 
         for (const [edgeKey, centrality] of edgeBetweenness) {
             if (Math.abs(centrality - maxBetweenness) < 1e-10) {
                 const [source, target] = edgeKey.split("|");
                 if (source && target) {
-                    edgesToRemove.push({source, target});
+                    edgesToRemove.push({ source, target });
                 }
             }
         }
 
         // Remove edges with highest betweenness
-        for (const {source, target} of edgesToRemove) {
+        for (const { source, target } of edgesToRemove) {
             workingGraph.removeEdge(source, target);
         }
 
@@ -71,9 +67,7 @@ export function girvanNewman(
         components = getConnectedComponentsResult(workingGraph);
 
         // Filter communities by minimum size
-        const validCommunities = components.components.filter(
-            (community) => community.length >= minCommunitySize,
-        );
+        const validCommunities = components.components.filter((community) => community.length >= minCommunitySize);
 
         // Calculate modularity for the new community structure
         const modularity = calculateModularity(graph, components.componentMap);
@@ -102,6 +96,8 @@ export function girvanNewman(
  *
  * Edge betweenness is the fraction of shortest paths that pass through the edge.
  * We adapt node betweenness centrality calculation to work with edges.
+ * @param graph - The input graph to analyze
+ * @returns Map of edge keys to their betweenness centrality values
  */
 function calculateEdgeBetweenness(graph: Graph): Map<string, number> {
     const edgeBetweenness = new Map<string, number>();
@@ -117,7 +113,7 @@ function calculateEdgeBetweenness(graph: Graph): Map<string, number> {
         const source = sourceNode.id;
 
         // Run BFS to find all shortest paths from source
-        const {distances, predecessors, pathCounts} = findAllShortestPaths(graph, source);
+        const { distances, predecessors, pathCounts } = findAllShortestPaths(graph, source);
 
         // Calculate dependency for each node and accumulate edge betweenness
         const dependency = new Map<NodeId, number>();
@@ -191,8 +187,14 @@ function calculateEdgeBetweenness(graph: Graph): Map<string, number> {
 
 /**
  * Find all shortest paths from a source node using optimized BFS
+ * @param graph - The input graph to search
+ * @param source - The source node to compute shortest paths from
+ * @returns Object containing distances, predecessors, and path counts
  */
-function findAllShortestPaths(graph: Graph, source: NodeId): {
+function findAllShortestPaths(
+    graph: Graph,
+    source: NodeId,
+): {
     distances: Map<NodeId, number>;
     predecessors: Map<NodeId, NodeId[]>;
     pathCounts: Map<NodeId, number>;
@@ -262,11 +264,14 @@ function findAllShortestPaths(graph: Graph, source: NodeId): {
         }
     }
 
-    return {distances, predecessors, pathCounts};
+    return { distances, predecessors, pathCounts };
 }
 
 /**
  * Generate a consistent edge key for undirected graphs
+ * @param source - The source node ID
+ * @param target - The target node ID
+ * @returns A consistent string key for the edge (ordered alphabetically)
  */
 function getEdgeKey(source: NodeId, target: NodeId): string {
     // For undirected graphs, ensure consistent ordering
@@ -282,11 +287,11 @@ function getEdgeKey(source: NodeId, target: NodeId): string {
 
 /**
  * Calculate modularity for a given community structure - optimized version
+ * @param graph - The original graph
+ * @param communityMap - Map from node IDs to community indices
+ * @returns The modularity score of the partition
  */
-function calculateModularity(
-    graph: Graph,
-    communityMap: Map<NodeId, number>,
-): number {
+function calculateModularity(graph: Graph, communityMap: Map<NodeId, number>): number {
     const totalEdgeWeight = getTotalEdgeWeight(graph);
     if (totalEdgeWeight === 0) {
         return 0;
@@ -313,7 +318,7 @@ function calculateModularity(
                 continue;
             }
 
-            modularity += edgeWeight - ((degreeI * degreeJ) / (2 * totalEdgeWeight));
+            modularity += edgeWeight - (degreeI * degreeJ) / (2 * totalEdgeWeight);
         }
     }
 
@@ -322,6 +327,8 @@ function calculateModularity(
 
 /**
  * Calculate total edge weight in the graph
+ * @param graph - The input graph
+ * @returns Total sum of all edge weights
  */
 function getTotalEdgeWeight(graph: Graph): number {
     let totalWeight = 0;
@@ -335,6 +342,9 @@ function getTotalEdgeWeight(graph: Graph): number {
 
 /**
  * Get the total degree (sum of edge weights) for a node
+ * @param graph - The input graph
+ * @param nodeId - The node ID to compute degree for
+ * @returns The weighted degree of the node
  */
 function getNodeDegree(graph: Graph, nodeId: NodeId): number {
     let degree = 0;
@@ -349,6 +359,8 @@ function getNodeDegree(graph: Graph, nodeId: NodeId): number {
 
 /**
  * Convert connected components result to ComponentResult format
+ * @param graph - The input graph
+ * @returns Object containing components array and node-to-component map
  */
 function getConnectedComponentsResult(graph: Graph): ComponentResult {
     const components = connectedComponents(graph);
@@ -360,6 +372,5 @@ function getConnectedComponentsResult(graph: Graph): ComponentResult {
         });
     });
 
-    return {components, componentMap};
+    return { components, componentMap };
 }
-

package/src/algorithms/community/index.ts

@@ -6,10 +6,9 @@
  * than with the rest of the network.
  */
 
-export {girvanNewman} from "./girvan-newman.js";
-export type {LabelPropagationOptions, LabelPropagationResult} from "./label-propagation.js";
-export {labelPropagation, labelPropagationAsync, labelPropagationSemiSupervised} from "./label-propagation.js";
-export type {LeidenOptions, LeidenResult} from "./leiden.js";
-export {leiden} from "./leiden.js";
-export {louvain} from "./louvain.js";
-
+export { girvanNewman } from "./girvan-newman.js";
+export type { LabelPropagationOptions, LabelPropagationResult } from "./label-propagation.js";
+export { labelPropagation, labelPropagationAsync, labelPropagationSemiSupervised } from "./label-propagation.js";
+export type { LeidenOptions, LeidenResult } from "./leiden.js";
+export { leiden } from "./leiden.js";
+export { louvain } from "./louvain.js";

package/src/algorithms/community/label-propagation.ts

@@ -9,9 +9,9 @@
  * detect community structures in large-scale networks"
  */
 
-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 LabelPropagationOptions {
     maxIterations?: number;
@@ -26,15 +26,15 @@ export interface LabelPropagationResult {
 
 /**
  * Internal implementation of Label Propagation Algorithm
+ * @param graph - Map representation of the graph (node to neighbors with weights)
+ * @param options - Algorithm configuration options
+ * @returns Community assignments, iteration count, and convergence status
  */
 function labelPropagationImpl(
     graph: Map<string, Map<string, number>>,
     options: LabelPropagationOptions = {},
 ): LabelPropagationResult {
-    const {
-        maxIterations = 100,
-        randomSeed = 42,
-    } = options;
+    const { maxIterations = 100, randomSeed = 42 } = options;
 
     if (graph.size === 0) {
         return {
@@ -61,7 +61,7 @@ function labelPropagationImpl(
         converged = true;
 
         // Create random order for node updates
-        const nodeOrder = [... nodes];
+        const nodeOrder = [...nodes];
         shuffle(nodeOrder, random);
 
         // Update each node's label
@@ -151,14 +151,15 @@ function labelPropagationImpl(
 /**
  * Internal implementation of Asynchronous Label Propagation
  * Updates all nodes simultaneously (can lead to oscillations)
+ * @param graph - Map representation of the graph (node to neighbors with weights)
+ * @param options - Algorithm configuration options
+ * @returns Community assignments, iteration count, and convergence status
  */
 function labelPropagationAsyncImpl(
     graph: Map<string, Map<string, number>>,
     options: LabelPropagationOptions = {},
 ): LabelPropagationResult {
-    const {
-        maxIterations = 100,
-    } = options;
+    const { maxIterations = 100 } = options;
 
     if (graph.size === 0) {
         return {
@@ -261,16 +262,17 @@ function labelPropagationAsyncImpl(
 /**
  * Internal implementation of Semi-supervised Label Propagation
  * Some nodes have fixed labels that don't change
+ * @param graph - Map representation of the graph (node to neighbors with weights)
+ * @param seedLabels - Map of node IDs to their fixed community labels
+ * @param options - Algorithm configuration options
+ * @returns Community assignments, iteration count, and convergence status
  */
 function labelPropagationSemiSupervisedImpl(
     graph: Map<string, Map<string, number>>,
     seedLabels: Map<string, number>,
     options: LabelPropagationOptions = {},
 ): LabelPropagationResult {
-    const {
-        maxIterations = 100,
-        randomSeed = 42,
-    } = options;
+    const { maxIterations = 100, randomSeed = 42 } = options;
 
     // Initialize random number generator
     const random = SeededRandom.createGenerator(randomSeed);
@@ -278,7 +280,7 @@ function labelPropagationSemiSupervisedImpl(
     // Initialize labels
     const labels = new Map<string, number>();
     const nodes = Array.from(graph.keys());
-    let labelCounter = Math.max(... Array.from(seedLabels.values())) + 1;
+    let labelCounter = Math.max(...Array.from(seedLabels.values())) + 1;
 
     for (const node of nodes) {
         if (seedLabels.has(node)) {
@@ -366,7 +368,6 @@ function labelPropagationSemiSupervisedImpl(
 /**
  * Label Propagation Algorithm
  * Each node adopts the most frequent label among its neighbors
- *
  * @param graph - Undirected graph (can be weighted)
  * @param options - Algorithm options
  * @returns Community assignments
@@ -374,10 +375,7 @@ function labelPropagationSemiSupervisedImpl(
  * Time Complexity: O(m) per iteration, typically O(km) for k iterations
  * Space Complexity: O(n)
  */
-export function labelPropagation(
-    graph: Graph,
-    options: LabelPropagationOptions = {},
-): LabelPropagationResult {
+export function labelPropagation(graph: Graph, options: LabelPropagationOptions = {}): LabelPropagationResult {
     // Convert Graph to Map representation
     const graphMap = graphToMap(graph);
     return labelPropagationImpl(graphMap, options);
@@ -386,15 +384,11 @@ export function labelPropagation(
 /**
  * Asynchronous Label Propagation
  * Updates all nodes simultaneously (can lead to oscillations)
- *
  * @param graph - Undirected graph (can be weighted)
  * @param options - Algorithm options
  * @returns Community assignments
  */
-export function labelPropagationAsync(
-    graph: Graph,
-    options: LabelPropagationOptions = {},
-): LabelPropagationResult {
+export function labelPropagationAsync(graph: Graph, options: LabelPropagationOptions = {}): LabelPropagationResult {
     // Convert Graph to Map representation
     const graphMap = graphToMap(graph);
     return labelPropagationAsyncImpl(graphMap, options);
@@ -403,7 +397,6 @@ export function labelPropagationAsync(
 /**
  * Semi-supervised Label Propagation
  * Some nodes have fixed labels that don't change
- *
  * @param graph - Undirected graph (can be weighted)
  * @param seedLabels - Initial fixed labels for some nodes
  * @param options - Algorithm options
@@ -418,4 +411,3 @@ export function labelPropagationSemiSupervised(
     const graphMap = graphToMap(graph);
     return labelPropagationSemiSupervisedImpl(graphMap, seedLabels, options);
 }
-

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);
 }
-