@graphty/algorithms 1.2.0 → 1.4.2

package/src/algorithms/centrality/betweenness.ts

@@ -1,5 +1,6 @@
-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";
+import { bfsWithPathCounting } from "../traversal/bfs-variants.js";
 
 /**
  * Betweenness centrality implementation using Brandes' algorithm
@@ -20,151 +21,218 @@ export interface BetweennessCentralityOptions {
      * Whether to use endpoints in path counting (default: false)
      */
     endpoints?: boolean;
+    /**
+     * Whether to use optimized BFS implementation for large graphs
+     */
+    optimized?: boolean;
 }
 
 /**
- * Calculate betweenness centrality for all nodes using Brandes' algorithm
+ * Result of Brandes algorithm computation for a single source
  */
-export function betweennessCentrality(
-    graph: Graph,
-    options: BetweennessCentralityOptions = {},
-): Record<string, number> {
-    const nodes = Array.from(graph.nodes()).map((node) => node.id);
-    const centrality: Record<string, number> = {};
+interface BrandesResult {
+    stack: NodeId[];
+    predecessors: Map<NodeId, NodeId[]>;
+    sigma: Map<NodeId, number>;
+    distance: Map<NodeId, number>;
+}
 
-    // Initialize centrality scores
-    for (const nodeId of nodes) {
-        centrality[String(nodeId)] = 0;
-    }
+/**
+ * Run single-source shortest path computation using BFS
+ * @param graph - The input graph to analyze
+ * @param source - The source node for shortest path computation
+ * @param optimized - Whether to use optimized BFS implementation
+ * @returns The BFS result containing stack, predecessors, sigma, and distances
+ */
+function brandesSingleSource(graph: Graph, source: NodeId, optimized?: boolean): BrandesResult {
+    const result = bfsWithPathCounting(graph, source, optimized !== undefined ? { optimized } : {});
+
+    return {
+        stack: result.stack,
+        predecessors: result.predecessors,
+        sigma: result.sigma,
+        distance: result.distances,
+    };
+}
 
-    // Brandes' algorithm
-    for (const source of nodes) {
-        const stack: NodeId[] = [];
-        const predecessors = new Map<NodeId, NodeId[]>();
-        const sigma = new Map<NodeId, number>(); // Number of shortest paths
-        const distance = new Map<NodeId, number>();
-        const delta = new Map<NodeId, number>();
+/**
+ * Accumulate betweenness contributions from a single source
+ * @param result - The BFS result from brandesSingleSource
+ * @param source - The source node used in BFS
+ * @param centrality - The centrality map to update
+ * @param options - Algorithm configuration options
+ */
+function accumulateBetweenness(
+    result: BrandesResult,
+    source: NodeId,
+    centrality: Record<string, number>,
+    options: BetweennessCentralityOptions,
+): void {
+    const { stack, predecessors, sigma } = result;
+    const delta = new Map<NodeId, number>();
+
+    // Initialize delta
+    for (const node of stack) {
+        delta.set(node, 0);
+    }
 
-        // Initialize
-        for (const nodeId of nodes) {
-            predecessors.set(nodeId, []);
-            sigma.set(nodeId, 0);
-            distance.set(nodeId, -1);
-            delta.set(nodeId, 0);
+    // Accumulation - back-propagation of dependencies
+    // Process nodes in reverse BFS order
+    for (let i = stack.length - 1; i >= 0; i--) {
+        const w = stack[i];
+        if (!w) {
+            continue;
         }
 
-        sigma.set(source, 1);
-        distance.set(source, 0);
-
-        const queue: NodeId[] = [source];
-
-        // BFS to find shortest paths
-        while (queue.length > 0) {
-            const current = queue.shift();
-            if (!current) {
-                break;
-            }
+        const wPreds = predecessors.get(w) ?? [];
+        const wSigma = sigma.get(w) ?? 0;
+        const wDelta = delta.get(w) ?? 0;
 
-            stack.push(current);
+        for (const v of wPreds) {
+            const vSigma = sigma.get(v) ?? 0;
+            const vDelta = delta.get(v) ?? 0;
 
-            for (const neighbor of Array.from(graph.neighbors(current))) {
-                const currentDistance = distance.get(current);
-                let neighborDistance = distance.get(neighbor);
+            if (vSigma > 0 && wSigma > 0) {
+                let contribution = (vSigma / wSigma) * (1 + wDelta);
 
-                if (currentDistance === undefined || neighborDistance === undefined) {
-                    continue;
-                }
-
-                // First time we reach this neighbor
-                if (neighborDistance < 0) {
-                    queue.push(neighbor);
-                    distance.set(neighbor, currentDistance + 1);
-                    neighborDistance = currentDistance + 1; // Update local variable
-                }
-
-                // Shortest path to neighbor via current
-                if (neighborDistance === currentDistance + 1) {
-                    const neighborSigma = sigma.get(neighbor) ?? 0;
-                    const currentSigma = sigma.get(current) ?? 0;
-                    sigma.set(neighbor, neighborSigma + currentSigma);
-
-                    const preds = predecessors.get(neighbor);
-                    if (preds) {
-                        preds.push(current);
+                // Apply endpoints option: when false, exclude endpoint contributions
+                if (!options.endpoints) {
+                    // For standard betweenness, don't count paths that only involve endpoints
+                    const isTargetEndpoint = wPreds.length === 0 && w !== source;
+                    if (isTargetEndpoint) {
+                        contribution = 0; // Exclude endpoint contributions
                     }
                 }
+
+                delta.set(v, vDelta + contribution);
             }
         }
 
-        // Accumulation - back-propagation of dependencies
-        while (stack.length > 0) {
-            const w = stack.pop();
-            if (!w) {
-                break;
-            }
+        if (w !== source) {
+            const currentCentrality = centrality[String(w)] ?? 0;
+            centrality[String(w)] = currentCentrality + wDelta;
+        }
+    }
+}
 
-            const wPreds = predecessors.get(w) ?? [];
-            const wSigma = sigma.get(w) ?? 0;
-            const wDelta = delta.get(w) ?? 0;
+/**
+ * Accumulate edge betweenness contributions from a single source
+ * @param result - The BFS result from brandesSingleSource
+ * @param source - The source node used in BFS
+ * @param edgeCentrality - The edge centrality map to update
+ * @param options - Algorithm configuration options
+ */
+function accumulateEdgeBetweenness(
+    result: BrandesResult,
+    source: NodeId,
+    edgeCentrality: Map<string, number>,
+    options: BetweennessCentralityOptions,
+): void {
+    const { stack, predecessors, sigma } = result;
+    const delta = new Map<NodeId, number>();
+
+    // Initialize delta
+    for (const node of stack) {
+        delta.set(node, 0);
+    }
 
-            for (const v of wPreds) {
-                const vSigma = sigma.get(v) ?? 0;
-                const vDelta = delta.get(v) ?? 0;
+    // Accumulation for edges
+    // Process nodes in reverse BFS order
+    for (let i = stack.length - 1; i >= 0; i--) {
+        const w = stack[i];
+        if (!w) {
+            continue;
+        }
 
-                if (vSigma > 0 && wSigma > 0) {
-                    let contribution = (vSigma / wSigma) * (1 + wDelta);
+        const wPreds = predecessors.get(w) ?? [];
+        const wSigma = sigma.get(w) ?? 0;
+        const wDelta = delta.get(w) ?? 0;
 
-                    // Apply endpoints option: when false, exclude endpoint contributions
-                    if (!options.endpoints) {
-                        // For standard betweenness, don't count paths that only involve endpoints
-                        const isTargetEndpoint = predecessors.get(w)?.length === 0 && w !== source;
-                        if (isTargetEndpoint) {
-                            contribution = 0; // Exclude endpoint contributions
-                        }
-                    }
+        for (const v of wPreds) {
+            const vSigma = sigma.get(v) ?? 0;
+
+            if (vSigma > 0 && wSigma > 0) {
+                let edgeContribution = (vSigma / wSigma) * (1 + wDelta);
 
-                    delta.set(v, vDelta + contribution);
+                // Apply endpoints option for edge betweenness
+                if (!options.endpoints) {
+                    const isTargetEndpoint = wPreds.length === 0 && w !== source;
+                    if (isTargetEndpoint) {
+                        edgeContribution = 0; // Exclude endpoint contributions
+                    }
                 }
+
+                // Update edge centrality
+                const edgeKey = `${String(v)}-${String(w)}`;
+                const currentEdgeCentrality = edgeCentrality.get(edgeKey) ?? 0;
+                edgeCentrality.set(edgeKey, currentEdgeCentrality + edgeContribution);
+
+                // Update node delta
+                const vDelta = delta.get(v) ?? 0;
+                delta.set(v, vDelta + edgeContribution);
             }
+        }
+    }
+}
 
-            if (w !== source) {
-                const currentCentrality = centrality[String(w)] ?? 0;
-                centrality[String(w)] = currentCentrality + wDelta;
+/**
+ * Apply normalization to centrality values
+ * @param centrality - The centrality map to normalize in place
+ * @param nodeCount - Total number of nodes in the graph
+ * @param isDirected - Whether the graph is directed
+ */
+function normalizeCentrality(centrality: Record<string, number>, nodeCount: number, isDirected: boolean): void {
+    const n = nodeCount;
+    const normalizationFactor = isDirected ? (n - 1) * (n - 2) : ((n - 1) * (n - 2)) / 2;
+
+    if (normalizationFactor > 0) {
+        for (const key in centrality) {
+            const value = centrality[key];
+            if (value !== undefined) {
+                centrality[key] = value / normalizationFactor;
             }
         }
     }
+}
+
+/**
+ * Calculate betweenness centrality for all nodes using Brandes' algorithm
+ * @param graph - The input graph to analyze
+ * @param options - Algorithm configuration options
+ * @returns Centrality scores for each node keyed by node ID
+ */
+export function betweennessCentrality(
+    graph: Graph,
+    options: BetweennessCentralityOptions = {},
+): Record<string, number> {
+    const nodes = Array.from(graph.nodes()).map((node) => node.id);
+    const centrality: Record<string, number> = {};
+
+    // Initialize centrality scores
+    for (const nodeId of nodes) {
+        centrality[String(nodeId)] = 0;
+    }
+
+    // Brandes' algorithm - run from each source
+    for (const source of nodes) {
+        const result = brandesSingleSource(graph, source, options.optimized);
+        accumulateBetweenness(result, source, centrality, options);
+    }
 
     // For undirected graphs, divide by 2 (each shortest path is counted twice)
     if (!graph.isDirected) {
         for (const nodeId of nodes) {
             const key = String(nodeId);
-            const currentValue = centrality[key];
-            if (currentValue !== undefined) {
-                centrality[key] = currentValue / 2;
+            const value = centrality[key];
+            if (value !== undefined) {
+                centrality[key] = value / 2;
             }
         }
     }
 
     // Normalization
     if (options.normalized) {
-        const n = nodes.length;
-        let normalizationFactor: number;
-
-        if (graph.isDirected) {
-            normalizationFactor = (n - 1) * (n - 2);
-        } else {
-            normalizationFactor = ((n - 1) * (n - 2)) / 2;
-        }
-
-        if (normalizationFactor > 0) {
-            for (const nodeId of nodes) {
-                const key = String(nodeId);
-                const currentValue = centrality[key];
-                if (currentValue !== undefined) {
-                    centrality[key] = currentValue / normalizationFactor;
-                }
-            }
-        }
+        normalizeCentrality(centrality, nodes.length, graph.isDirected);
     }
 
     return centrality;
@@ -172,6 +240,10 @@ export function betweennessCentrality(
 
 /**
  * Calculate betweenness centrality for a specific node
+ * @param graph - The input graph to analyze
+ * @param targetNode - The node to calculate centrality for
+ * @param options - Algorithm configuration options
+ * @returns The betweenness centrality score for the target node
  */
 export function nodeBetweennessCentrality(
     graph: Graph,
@@ -188,6 +260,9 @@ export function nodeBetweennessCentrality(
 
 /**
  * Calculate edge betweenness centrality
+ * @param graph - The input graph to analyze
+ * @param options - Algorithm configuration options
+ * @returns Edge centrality scores keyed by edge string representation
  */
 export function edgeBetweennessCentrality(
     graph: Graph,
@@ -204,97 +279,8 @@ export function edgeBetweennessCentrality(
 
     // Modified Brandes' algorithm for edge betweenness
     for (const source of nodes) {
-        const stack: NodeId[] = [];
-        const predecessors = new Map<NodeId, NodeId[]>();
-        const sigma = new Map<NodeId, number>();
-        const distance = new Map<NodeId, number>();
-        const delta = new Map<NodeId, number>();
-
-        // Initialize
-        for (const nodeId of nodes) {
-            predecessors.set(nodeId, []);
-            sigma.set(nodeId, 0);
-            distance.set(nodeId, -1);
-            delta.set(nodeId, 0);
-        }
-
-        sigma.set(source, 1);
-        distance.set(source, 0);
-
-        const queue: NodeId[] = [source];
-
-        // BFS to find shortest paths
-        while (queue.length > 0) {
-            const current = queue.shift();
-            if (!current) {
-                break;
-            }
-
-            stack.push(current);
-
-            for (const neighbor of Array.from(graph.neighbors(current))) {
-                const currentDistance = distance.get(current);
-                let neighborDistance = distance.get(neighbor);
-
-                if (currentDistance === undefined || neighborDistance === undefined) {
-                    continue;
-                }
-
-                if (neighborDistance < 0) {
-                    queue.push(neighbor);
-                    distance.set(neighbor, currentDistance + 1);
-                    neighborDistance = currentDistance + 1; // Update local variable
-                }
-
-                if (neighborDistance === currentDistance + 1) {
-                    const neighborSigma = sigma.get(neighbor) ?? 0;
-                    const currentSigma = sigma.get(current) ?? 0;
-                    sigma.set(neighbor, neighborSigma + currentSigma);
-
-                    const preds = predecessors.get(neighbor);
-                    if (preds) {
-                        preds.push(current);
-                    }
-                }
-            }
-        }
-
-        // Accumulation for edges
-        while (stack.length > 0) {
-            const w = stack.pop();
-            if (!w) {
-                break;
-            }
-
-            const wPreds = predecessors.get(w) ?? [];
-            const wSigma = sigma.get(w) ?? 0;
-            const wDelta = delta.get(w) ?? 0;
-
-            for (const v of wPreds) {
-                const vSigma = sigma.get(v) ?? 0;
-
-                if (vSigma > 0 && wSigma > 0) {
-                    let edgeContribution = vSigma / wSigma * (1 + wDelta);
-
-                    // Apply endpoints option for edge betweenness
-                    if (!options.endpoints) {
-                        const isTargetEndpoint = predecessors.get(w)?.length === 0 && w !== source;
-                        if (isTargetEndpoint) {
-                            edgeContribution = 0; // Exclude endpoint contributions
-                        }
-                    }
-
-                    // Update edge centrality
-                    const edgeKey = `${String(v)}-${String(w)}`;
-                    const currentEdgeCentrality = edgeCentrality.get(edgeKey) ?? 0;
-                    edgeCentrality.set(edgeKey, currentEdgeCentrality + edgeContribution);
-
-                    // Update node delta
-                    const vDelta = delta.get(v) ?? 0;
-                    delta.set(v, vDelta + edgeContribution);
-                }
-            }
-        }
+        const result = brandesSingleSource(graph, source, options.optimized);
+        accumulateEdgeBetweenness(result, source, edgeCentrality, options);
     }
 
     // For undirected graphs, divide by 2 (each shortest path is counted twice)
@@ -318,4 +304,3 @@ export function edgeBetweennessCentrality(
 
     return edgeCentrality;
 }
-