@graphty/algorithms 1.0.1 → 1.1.0

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

package/src/algorithms/centrality/pagerank.ts

@@ -111,7 +111,7 @@ export function pageRank(
         let outDegree = 0;
         let totalOutWeight = 0;
 
-        for (const neighbor of graph.neighbors(nodeId)) {
+        for (const neighbor of Array.from(graph.neighbors(nodeId))) {
             outDegree++;
             if (weight) {
                 const edge = graph.getEdge(nodeId, neighbor);
@@ -178,7 +178,7 @@ export function pageRank(
             const nodeOutWeight = outWeights.get(nodeId) ?? 0;
 
             if (nodeOutWeight > 0) {
-                for (const neighbor of graph.neighbors(nodeId)) {
+                for (const neighbor of Array.from(graph.neighbors(nodeId))) {
                     let edgeWeight = 1;
                     if (weight) {
                         const edge = graph.getEdge(nodeId, neighbor);
@@ -295,7 +295,7 @@ function normalizeRanks(ranks: Map<NodeId, number>): void {
     }
 
     if (sum > 0) {
-        for (const [nodeId, rank] of ranks) {
+        for (const [nodeId, rank] of Array.from(ranks)) {
             ranks.set(nodeId, rank / sum);
         }
     }