@graphty/algorithms 1.0.1 → 1.2.0

package/src/algorithms/centrality/betweenness.ts

@@ -67,7 +67,7 @@ export function betweennessCentrality(
 
             stack.push(current);
 
-            for (const neighbor of graph.neighbors(current)) {
+            for (const neighbor of Array.from(graph.neighbors(current))) {
                 const currentDistance = distance.get(current);
                 let neighborDistance = distance.get(neighbor);
 
@@ -112,7 +112,17 @@ export function betweennessCentrality(
                 const vDelta = delta.get(v) ?? 0;
 
                 if (vSigma > 0 && wSigma > 0) {
-                    const contribution = (vSigma / wSigma) * (1 + wDelta);
+                    let contribution = (vSigma / wSigma) * (1 + wDelta);
+
+                    // 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
+                        }
+                    }
+
                     delta.set(v, vDelta + contribution);
                 }
             }
@@ -187,7 +197,7 @@ export function edgeBetweennessCentrality(
     const edgeCentrality = new Map<string, number>();
 
     // Initialize edge centrality scores
-    for (const edge of graph.edges()) {
+    for (const edge of Array.from(graph.edges())) {
         const edgeKey = `${String(edge.source)}-${String(edge.target)}`;
         edgeCentrality.set(edgeKey, 0);
     }
@@ -222,7 +232,7 @@ export function edgeBetweennessCentrality(
 
             stack.push(current);
 
-            for (const neighbor of graph.neighbors(current)) {
+            for (const neighbor of Array.from(graph.neighbors(current))) {
                 const currentDistance = distance.get(current);
                 let neighborDistance = distance.get(neighbor);
 
@@ -264,7 +274,15 @@ export function edgeBetweennessCentrality(
                 const vSigma = sigma.get(v) ?? 0;
 
                 if (vSigma > 0 && wSigma > 0) {
-                    const edgeContribution = vSigma / wSigma * (1 + wDelta);
+                    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)}`;
@@ -281,7 +299,7 @@ export function edgeBetweennessCentrality(
 
     // For undirected graphs, divide by 2 (each shortest path is counted twice)
     if (!graph.isDirected) {
-        for (const [edgeKey, centrality] of edgeCentrality) {
+        for (const [edgeKey, centrality] of Array.from(edgeCentrality)) {
             edgeCentrality.set(edgeKey, centrality / 2);
         }
     }
@@ -292,7 +310,7 @@ export function edgeBetweennessCentrality(
         const normalizationFactor = graph.isDirected ? (n - 1) * (n - 2) : ((n - 1) * (n - 2)) / 2;
 
         if (normalizationFactor > 0) {
-            for (const [edgeKey, centrality] of edgeCentrality) {
+            for (const [edgeKey, centrality] of Array.from(edgeCentrality)) {
                 edgeCentrality.set(edgeKey, centrality / normalizationFactor);
             }
         }

package/src/algorithms/centrality/closeness.ts

@@ -66,7 +66,7 @@ export function nodeClosenessCentrality(
 
     if (options.harmonic) {
         // Harmonic centrality: sum of reciprocals of distances
-        for (const [targetNode, distance] of distances) {
+        for (const [targetNode, distance] of Array.from(distances)) {
             if (targetNode !== node && distance > 0) {
                 centrality += 1 / distance;
             }
@@ -76,7 +76,7 @@ export function nodeClosenessCentrality(
         let totalDistance = 0;
         let reachableNodes = 0;
 
-        for (const [targetNode, distance] of distances) {
+        for (const [targetNode, distance] of Array.from(distances)) {
             if (targetNode !== node) {
                 totalDistance += distance;
                 reachableNodes++;
@@ -134,7 +134,7 @@ function singleSourceShortestPathLengths(
         }
 
         // Explore neighbors
-        for (const neighbor of graph.neighbors(current.node)) {
+        for (const neighbor of Array.from(graph.neighbors(current.node))) {
             if (!visited.has(neighbor)) {
                 const newDistance = current.distance + 1;
 
@@ -192,7 +192,7 @@ export function nodeWeightedClosenessCentrality(
 
     if (options.harmonic) {
         // Harmonic centrality: sum of reciprocals of distances
-        for (const [targetNode, distance] of distances) {
+        for (const [targetNode, distance] of Array.from(distances)) {
             if (targetNode !== node && distance > 0 && distance < Infinity) {
                 centrality += 1 / distance;
             }
@@ -202,7 +202,7 @@ export function nodeWeightedClosenessCentrality(
         let totalDistance = 0;
         let reachableNodes = 0;
 
-        for (const [targetNode, distance] of distances) {
+        for (const [targetNode, distance] of Array.from(distances)) {
             if (targetNode !== node && distance < Infinity) {
                 totalDistance += distance;
                 reachableNodes++;
@@ -244,7 +244,7 @@ function dijkstraDistances(
     const pq: {node: NodeId, distance: number}[] = [];
 
     // Initialize distances
-    for (const node of graph.nodes()) {
+    for (const node of Array.from(graph.nodes())) {
         distances.set(node.id, node.id === source ? 0 : Infinity);
     }
 
@@ -267,7 +267,7 @@ function dijkstraDistances(
         }
 
         // Explore neighbors
-        for (const neighbor of graph.neighbors(current.node)) {
+        for (const neighbor of Array.from(graph.neighbors(current.node))) {
             if (visited.has(neighbor)) {
                 continue;
             }

package/src/algorithms/centrality/degree.ts

@@ -21,7 +21,7 @@ export function degreeCentrality(
     // Calculate normalization factor
     const maxPossibleDegree = graph.isDirected ? nodeCount - 1 : nodeCount - 1;
 
-    for (const node of graph.nodes()) {
+    for (const node of Array.from(graph.nodes())) {
         let degree: number;
 
         if (graph.isDirected && options.mode) {

package/src/algorithms/centrality/eigenvector.ts

@@ -0,0 +1,162 @@
+import type {Graph} from "../../core/graph.js";
+import type {CentralityOptions, CentralityResult} from "../../types/index.js";
+
+/**
+ * Eigenvector centrality implementation
+ *
+ * Measures the influence of a node based on the influence of its neighbors.
+ * A node has high eigenvector centrality if it is connected to nodes
+ * that themselves have high eigenvector centrality.
+ *
+ * Time complexity: O(V + E) per iteration
+ * Space complexity: O(V)
+ */
+
+export interface EigenvectorCentralityOptions extends CentralityOptions {
+    maxIterations?: number; // Maximum iterations (default: 100)
+    tolerance?: number; // Convergence tolerance (default: 1e-6)
+    startVector?: Map<string, number>; // Initial vector (optional)
+}
+
+/**
+ * Calculate eigenvector centrality for all nodes in the graph
+ * Uses the power iteration method to find the dominant eigenvector
+ */
+export function eigenvectorCentrality(
+    graph: Graph,
+    options: EigenvectorCentralityOptions = {},
+): CentralityResult {
+    const {
+        maxIterations = 100,
+        tolerance = 1e-6,
+        normalized = true,
+        startVector,
+    } = options;
+
+    const centrality: CentralityResult = {};
+    const nodes = Array.from(graph.nodes());
+    const nodeIds = nodes.map((node) => node.id);
+
+    if (nodeIds.length === 0) {
+        return centrality;
+    }
+
+    // Initialize the eigenvector
+    let currentVector = new Map<string, number>();
+    let previousVector = new Map<string, number>();
+
+    if (startVector) {
+        // Use provided start vector
+        for (const nodeId of nodeIds) {
+            const key = nodeId.toString();
+            currentVector.set(key, startVector.get(key) ?? 1.0 / Math.sqrt(nodeIds.length));
+        }
+    } else {
+        // Initialize with uniform distribution
+        const initialValue = 1.0 / Math.sqrt(nodeIds.length);
+        for (const nodeId of nodeIds) {
+            currentVector.set(nodeId.toString(), initialValue);
+        }
+    }
+
+    // Power iteration
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+        previousVector = new Map(currentVector);
+        currentVector = new Map();
+
+        // Update each node's centrality based on neighbors
+        for (const nodeId of nodeIds) {
+            let sum = 0;
+            const neighbors = Array.from(graph.neighbors(nodeId));
+
+            for (const neighbor of neighbors) {
+                const neighborKey = neighbor.toString();
+                const prevValue = previousVector.get(neighborKey);
+                sum += prevValue ?? 0;
+            }
+
+            currentVector.set(nodeId.toString(), sum);
+        }
+
+        // Normalize the vector
+        let norm = 0;
+        for (const value of Array.from(currentVector.values())) {
+            norm += value * value;
+        }
+        norm = Math.sqrt(norm);
+
+        if (norm === 0) {
+            // Graph has no edges or is disconnected
+            for (const nodeId of nodeIds) {
+                centrality[nodeId.toString()] = 0;
+            }
+            return centrality;
+        }
+
+        // Normalize the vector
+        for (const [nodeId, value] of Array.from(currentVector)) {
+            currentVector.set(nodeId, value / norm);
+        }
+
+        // Check for convergence
+        let maxDiff = 0;
+        for (const [nodeId, value] of Array.from(currentVector)) {
+            const prevValue = previousVector.get(nodeId) ?? 0;
+            const diff = Math.abs(value - prevValue);
+            maxDiff = Math.max(maxDiff, diff);
+        }
+
+        if (maxDiff < tolerance) {
+            break;
+        }
+    }
+
+    // Prepare results
+    for (const [nodeId, value] of Array.from(currentVector)) {
+        centrality[nodeId] = value;
+    }
+
+    // Additional normalization if requested (normalize to [0,1] range)
+    if (normalized) {
+        let maxValue = 0;
+        let minValue = Number.POSITIVE_INFINITY;
+
+        for (const value of Object.values(centrality)) {
+            maxValue = Math.max(maxValue, value);
+            minValue = Math.min(minValue, value);
+        }
+
+        const range = maxValue - minValue;
+        if (range > 0) {
+            for (const nodeId of Object.keys(centrality)) {
+                const centralityValue = centrality[nodeId];
+                if (centralityValue !== undefined) {
+                    centrality[nodeId] = (centralityValue - minValue) / range;
+                }
+            }
+        } else {
+            // All values are the same, set to 1
+            for (const nodeId of Object.keys(centrality)) {
+                centrality[nodeId] = maxValue > 0 ? 1 : 0;
+            }
+        }
+    }
+
+    return centrality;
+}
+
+/**
+ * Calculate eigenvector centrality for a specific node
+ */
+export function nodeEigenvectorCentrality(
+    graph: Graph,
+    nodeId: string | number,
+    options: EigenvectorCentralityOptions = {},
+): number {
+    if (!graph.hasNode(nodeId)) {
+        throw new Error(`Node ${String(nodeId)} not found in graph`);
+    }
+
+    const centrality = eigenvectorCentrality(graph, options);
+    return centrality[nodeId.toString()] ?? 0;
+}

package/src/algorithms/centrality/hits.ts

@@ -0,0 +1,210 @@
+import type {Graph} from "../../core/graph.js";
+import type {CentralityOptions} from "../../types/index.js";
+
+/**
+ * HITS (Hyperlink-Induced Topic Search) algorithm implementation
+ *
+ * Identifies hub and authority scores for nodes in a graph.
+ * - Authorities: nodes with valuable information (pointed to by hubs)
+ * - Hubs: nodes that point to many authorities
+ *
+ * Originally designed for web page ranking but applicable to any directed network.
+ *
+ * Time complexity: O(V + E) per iteration
+ * Space complexity: O(V)
+ */
+
+export interface HITSResult {
+    hubs: Record<string, number>;
+    authorities: Record<string, number>;
+}
+
+export interface HITSOptions extends CentralityOptions {
+    maxIterations?: number; // Maximum iterations (default: 100)
+    tolerance?: number; // Convergence tolerance (default: 1e-6)
+}
+
+/**
+ * Calculate HITS hub and authority scores for all nodes in the graph
+ * Uses iterative method with normalization
+ */
+export function hits(
+    graph: Graph,
+    options: HITSOptions = {},
+): HITSResult {
+    const {
+        maxIterations = 100,
+        tolerance = 1e-6,
+        normalized = true,
+    } = options;
+
+    const hubs: Record<string, number> = {};
+    const authorities: Record<string, number> = {};
+
+    const nodes = Array.from(graph.nodes());
+    const nodeIds = nodes.map((node) => node.id);
+
+    if (nodeIds.length === 0) {
+        return {hubs, authorities};
+    }
+
+    // Initialize scores
+    let currentHubs = new Map<string, number>();
+    let currentAuthorities = new Map<string, number>();
+    let previousHubs = new Map<string, number>();
+    let previousAuthorities = new Map<string, number>();
+
+    // Start with uniform distribution
+    const initialValue = 1.0 / Math.sqrt(nodeIds.length);
+    for (const nodeId of nodeIds) {
+        const key = nodeId.toString();
+        currentHubs.set(key, initialValue);
+        currentAuthorities.set(key, initialValue);
+    }
+
+    // Iterative computation
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+        previousHubs = new Map(currentHubs);
+        previousAuthorities = new Map(currentAuthorities);
+
+        // Update authority scores
+        // Authority score = sum of hub scores of nodes pointing to it
+        const newAuthorities = new Map<string, number>();
+        for (const nodeId of nodeIds) {
+            let authorityScore = 0;
+            const inNeighbors = Array.from(graph.inNeighbors(nodeId));
+
+            for (const inNeighbor of inNeighbors) {
+                const neighborKey = inNeighbor.toString();
+                authorityScore += previousHubs.get(neighborKey) ?? 0;
+            }
+
+            newAuthorities.set(nodeId.toString(), authorityScore);
+        }
+
+        // Update hub scores
+        // Hub score = sum of authority scores of nodes it points to
+        const newHubs = new Map<string, number>();
+        for (const nodeId of nodeIds) {
+            let hubScore = 0;
+            const outNeighbors = Array.from(graph.outNeighbors(nodeId));
+
+            for (const outNeighbor of outNeighbors) {
+                const neighborKey = outNeighbor.toString();
+                hubScore += previousAuthorities.get(neighborKey) ?? 0;
+            }
+
+            newHubs.set(nodeId.toString(), hubScore);
+        }
+
+        // Normalize authority scores
+        let authNorm = 0;
+        for (const value of Array.from(newAuthorities.values())) {
+            authNorm += value * value;
+        }
+        authNorm = Math.sqrt(authNorm);
+
+        if (authNorm > 0) {
+            for (const [nodeId, value] of Array.from(newAuthorities)) {
+                newAuthorities.set(nodeId, value / authNorm);
+            }
+        }
+
+        // Normalize hub scores
+        let hubNorm = 0;
+        for (const value of Array.from(newHubs.values())) {
+            hubNorm += value * value;
+        }
+        hubNorm = Math.sqrt(hubNorm);
+
+        if (hubNorm > 0) {
+            for (const [nodeId, value] of Array.from(newHubs)) {
+                newHubs.set(nodeId, value / hubNorm);
+            }
+        }
+
+        currentAuthorities = newAuthorities;
+        currentHubs = newHubs;
+
+        // Check for convergence
+        let maxDiff = 0;
+        for (const [nodeId, value] of currentHubs) {
+            const prevValue = previousHubs.get(nodeId) ?? 0;
+            const diff = Math.abs(value - prevValue);
+            maxDiff = Math.max(maxDiff, diff);
+        }
+        for (const [nodeId, value] of currentAuthorities) {
+            const prevValue = previousAuthorities.get(nodeId) ?? 0;
+            const diff = Math.abs(value - prevValue);
+            maxDiff = Math.max(maxDiff, diff);
+        }
+
+        if (maxDiff < tolerance) {
+            break;
+        }
+    }
+
+    // Prepare results
+    for (const [nodeId, value] of currentHubs) {
+        hubs[nodeId] = value;
+    }
+    for (const [nodeId, value] of currentAuthorities) {
+        authorities[nodeId] = value;
+    }
+
+    // The algorithm already normalizes to unit L2 norm during iterations
+    // Additional max normalization is only applied if explicitly requested
+    if (!normalized) {
+        // If normalization is explicitly disabled, normalize to [0, 1] range
+        let maxHub = 0;
+        let maxAuth = 0;
+
+        for (const value of Object.values(hubs)) {
+            maxHub = Math.max(maxHub, value);
+        }
+        for (const value of Object.values(authorities)) {
+            maxAuth = Math.max(maxAuth, value);
+        }
+
+        if (maxHub > 0) {
+            for (const nodeId of Object.keys(hubs)) {
+                const hubValue = hubs[nodeId];
+                if (hubValue !== undefined) {
+                    hubs[nodeId] = hubValue / maxHub;
+                }
+            }
+        }
+
+        if (maxAuth > 0) {
+            for (const nodeId of Object.keys(authorities)) {
+                const authValue = authorities[nodeId];
+                if (authValue !== undefined) {
+                    authorities[nodeId] = authValue / maxAuth;
+                }
+            }
+        }
+    }
+
+    return {hubs, authorities};
+}
+
+/**
+ * Calculate HITS scores for a specific node
+ */
+export function nodeHITS(
+    graph: Graph,
+    nodeId: string | number,
+    options: HITSOptions = {},
+): {hub: number, authority: number} {
+    if (!graph.hasNode(nodeId)) {
+        throw new Error(`Node ${String(nodeId)} not found in graph`);
+    }
+
+    const result = hits(graph, options);
+    const key = nodeId.toString();
+
+    return {
+        hub: result.hubs[key] ?? 0,
+        authority: result.authorities[key] ?? 0,
+    };
+}

package/src/algorithms/centrality/index.ts

@@ -7,5 +7,11 @@ export {betweennessCentrality, edgeBetweennessCentrality, nodeBetweennessCentral
 export type {ClosenessCentralityOptions} from "./closeness.js";
 export {closenessCentrality, nodeClosenessCentrality, nodeWeightedClosenessCentrality, weightedClosenessCentrality} from "./closeness.js";
 export {degreeCentrality, nodeDegreeCentrality} from "./degree.js";
+export type {EigenvectorCentralityOptions} from "./eigenvector.js";
+export {eigenvectorCentrality, nodeEigenvectorCentrality} from "./eigenvector.js";
+export type {HITSOptions, HITSResult} from "./hits.js";
+export {hits, nodeHITS} from "./hits.js";
+export type {KatzCentralityOptions} from "./katz.js";
+export {katzCentrality, nodeKatzCentrality} from "./katz.js";
 export type {PageRankOptions, PageRankResult} from "./pagerank.js";
 export {pageRank, pageRankCentrality, personalizedPageRank, topPageRankNodes} from "./pagerank.js";

package/src/algorithms/centrality/katz.ts

@@ -0,0 +1,139 @@
+import type {Graph} from "../../core/graph.js";
+import type {CentralityOptions, CentralityResult} from "../../types/index.js";
+
+/**
+ * Katz centrality implementation
+ *
+ * A generalization of eigenvector centrality that gives each node a base amount
+ * of influence regardless of its position in the network. Uses an attenuation
+ * factor (alpha) to control how much a node's centrality depends on its neighbors.
+ *
+ * Katz centrality = alpha * sum(neighbors' centrality) + beta
+ *
+ * Time complexity: O(V + E) per iteration
+ * Space complexity: O(V)
+ */
+
+export interface KatzCentralityOptions extends CentralityOptions {
+    alpha?: number; // Attenuation factor (default: 0.1)
+    beta?: number; // Base centrality weight (default: 1.0)
+    maxIterations?: number; // Maximum iterations (default: 100)
+    tolerance?: number; // Convergence tolerance (default: 1e-6)
+}
+
+/**
+ * Calculate Katz centrality for all nodes in the graph
+ * Uses iterative method to compute centrality scores
+ */
+export function katzCentrality(
+    graph: Graph,
+    options: KatzCentralityOptions = {},
+): CentralityResult {
+    const {
+        alpha = 0.1,
+        beta = 1.0,
+        maxIterations = 100,
+        tolerance = 1e-6,
+        normalized = true,
+    } = options;
+
+    const centrality: CentralityResult = {};
+    const nodes = Array.from(graph.nodes());
+    const nodeIds = nodes.map((node) => node.id);
+
+    if (nodeIds.length === 0) {
+        return centrality;
+    }
+
+    // Check if alpha is valid (should be less than 1/lambda_max)
+    // For simplicity, we'll trust the user's choice or use conservative default
+
+    // Initialize centrality scores
+    let currentScores = new Map<string, number>();
+    let previousScores = new Map<string, number>();
+
+    // Start with beta for all nodes
+    for (const nodeId of nodeIds) {
+        currentScores.set(nodeId.toString(), beta);
+    }
+
+    // Iterative computation
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+        previousScores = new Map(currentScores);
+        currentScores = new Map();
+
+        // Update each node's centrality
+        for (const nodeId of nodeIds) {
+            let sum = 0;
+
+            // For directed graphs, use in-neighbors
+            // For undirected graphs, use all neighbors
+            const neighbors = graph.isDirected ?
+                Array.from(graph.inNeighbors(nodeId)) :
+                graph.neighbors(nodeId);
+
+            for (const neighbor of neighbors) {
+                const neighborKey = neighbor.toString();
+                sum += previousScores.get(neighborKey) ?? 0;
+            }
+
+            currentScores.set(nodeId.toString(), (alpha * sum) + beta);
+        }
+
+        // Check for convergence
+        let maxDiff = 0;
+        for (const [nodeId, value] of Array.from(currentScores)) {
+            const prevValue = previousScores.get(nodeId) ?? 0;
+            const diff = Math.abs(value - prevValue);
+            maxDiff = Math.max(maxDiff, diff);
+        }
+
+        if (maxDiff < tolerance) {
+            break;
+        }
+    }
+
+    // Prepare results
+    for (const [nodeId, value] of Array.from(currentScores)) {
+        centrality[nodeId] = value;
+    }
+
+    // Normalize if requested
+    if (normalized) {
+        let maxValue = 0;
+        let minValue = Number.POSITIVE_INFINITY;
+
+        for (const value of Object.values(centrality)) {
+            maxValue = Math.max(maxValue, value);
+            minValue = Math.min(minValue, value);
+        }
+
+        const range = maxValue - minValue;
+        if (range > 0) {
+            for (const nodeId of Object.keys(centrality)) {
+                const centralityValue = centrality[nodeId];
+                if (centralityValue !== undefined) {
+                    centrality[nodeId] = (centralityValue - minValue) / range;
+                }
+            }
+        }
+    }
+
+    return centrality;
+}
+
+/**
+ * Calculate Katz centrality for a specific node
+ */
+export function nodeKatzCentrality(
+    graph: Graph,
+    nodeId: string | number,
+    options: KatzCentralityOptions = {},
+): number {
+    if (!graph.hasNode(nodeId)) {
+        throw new Error(`Node ${String(nodeId)} not found in graph`);
+    }
+
+    const centrality = katzCentrality(graph, options);
+    return centrality[nodeId.toString()] ?? 0;
+}