@graphty/algorithms 1.2.0 → 1.3.1

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 {bfsWithPathCounting} from "../traversal/bfs-variants.js";
 
 /**
  * Betweenness centrality implementation using Brandes' algorithm
@@ -20,151 +21,206 @@ 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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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;
@@ -204,97 +260,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)
@@ -307,7 +274,9 @@ export function edgeBetweennessCentrality(
     // Normalization for edges
     if (options.normalized) {
         const n = nodes.length;
-        const normalizationFactor = graph.isDirected ? (n - 1) * (n - 2) : ((n - 1) * (n - 2)) / 2;
+        const normalizationFactor = graph.isDirected ?
+            (n - 1) * (n - 2) :
+            ((n - 1) * (n - 2)) / 2;
 
         if (normalizationFactor > 0) {
             for (const [edgeKey, centrality] of Array.from(edgeCentrality)) {
@@ -318,4 +287,3 @@ export function edgeBetweennessCentrality(
 
     return edgeCentrality;
 }
-