@graphty/algorithms 1.0.1

package/src/algorithms/centrality/closeness.ts

@@ -0,0 +1,296 @@
+import type {Graph} from "../../core/graph.js";
+import type {NodeId} from "../../types/index.js";
+
+/**
+ * Closeness centrality implementation
+ *
+ * Measures how close a node is to all other nodes in the graph.
+ * Uses BFS to compute shortest path distances efficiently.
+ */
+
+/**
+ * Closeness centrality options
+ */
+export interface ClosenessCentralityOptions {
+    /**
+     * Whether to normalize the centrality values (default: false)
+     */
+    normalized?: boolean;
+    /**
+     * Use harmonic mean instead of reciprocal of sum (default: false)
+     * Better for disconnected graphs
+     */
+    harmonic?: boolean;
+    /**
+     * Consider only nodes within this distance (default: undefined = all nodes)
+     */
+    cutoff?: number;
+}
+
+/**
+ * Calculate closeness centrality for all nodes
+ */
+export function closenessCentrality(
+    graph: Graph,
+    options: ClosenessCentralityOptions = {},
+): Record<string, number> {
+    const nodes = Array.from(graph.nodes()).map((node) => node.id);
+    const centrality: Record<string, number> = {};
+
+    for (const sourceNode of nodes) {
+        centrality[String(sourceNode)] = nodeClosenessCentrality(graph, sourceNode, options);
+    }
+
+    return centrality;
+}
+
+/**
+ * Calculate closeness centrality for a specific node
+ */
+export function nodeClosenessCentrality(
+    graph: Graph,
+    node: NodeId,
+    options: ClosenessCentralityOptions = {},
+): number {
+    if (!graph.hasNode(node)) {
+        throw new Error(`Node ${String(node)} not found in graph`);
+    }
+
+    const distances = singleSourceShortestPathLengths(graph, node, options.cutoff);
+
+    if (distances.size <= 1) {
+        return 0; // No other nodes reachable
+    }
+
+    let centrality = 0;
+
+    if (options.harmonic) {
+        // Harmonic centrality: sum of reciprocals of distances
+        for (const [targetNode, distance] of distances) {
+            if (targetNode !== node && distance > 0) {
+                centrality += 1 / distance;
+            }
+        }
+    } else {
+        // Standard closeness: reciprocal of sum of distances
+        let totalDistance = 0;
+        let reachableNodes = 0;
+
+        for (const [targetNode, distance] of distances) {
+            if (targetNode !== node) {
+                totalDistance += distance;
+                reachableNodes++;
+            }
+        }
+
+        if (totalDistance > 0) {
+            centrality = 1 / totalDistance;
+
+            // Wasserman and Faust normalization for disconnected graphs
+            if (options.normalized) {
+                const n = Array.from(graph.nodes()).length;
+                centrality = centrality * reachableNodes / (n - 1);
+            }
+        }
+    }
+
+    // Normalization for harmonic centrality
+    if (options.harmonic && options.normalized) {
+        const n = Array.from(graph.nodes()).length;
+        if (n > 1) {
+            centrality = centrality / (n - 1);
+        }
+    }
+
+    return centrality;
+}
+
+/**
+ * Single-source shortest path lengths using BFS (for unweighted graphs)
+ */
+function singleSourceShortestPathLengths(
+    graph: Graph,
+    source: NodeId,
+    cutoff?: number,
+): Map<NodeId, number> {
+    const distances = new Map<NodeId, number>();
+    const visited = new Set<NodeId>();
+    const queue: {node: NodeId, distance: number}[] = [];
+
+    // Initialize
+    queue.push({node: source, distance: 0});
+    visited.add(source);
+    distances.set(source, 0);
+
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (!current) {
+            break;
+        }
+
+        // Skip if beyond cutoff
+        if (cutoff !== undefined && current.distance >= cutoff) {
+            continue;
+        }
+
+        // Explore neighbors
+        for (const neighbor of graph.neighbors(current.node)) {
+            if (!visited.has(neighbor)) {
+                const newDistance = current.distance + 1;
+
+                // Skip if beyond cutoff
+                if (cutoff !== undefined && newDistance > cutoff) {
+                    continue;
+                }
+
+                visited.add(neighbor);
+                distances.set(neighbor, newDistance);
+                queue.push({node: neighbor, distance: newDistance});
+            }
+        }
+    }
+
+    return distances;
+}
+
+/**
+ * Calculate weighted closeness centrality using Dijkstra's algorithm
+ */
+export function weightedClosenessCentrality(
+    graph: Graph,
+    options: ClosenessCentralityOptions = {},
+): Record<string, number> {
+    const nodes = Array.from(graph.nodes()).map((node) => node.id);
+    const centrality: Record<string, number> = {};
+
+    for (const sourceNode of nodes) {
+        centrality[String(sourceNode)] = nodeWeightedClosenessCentrality(graph, sourceNode, options);
+    }
+
+    return centrality;
+}
+
+/**
+ * Calculate weighted closeness centrality for a specific node using Dijkstra
+ */
+export function nodeWeightedClosenessCentrality(
+    graph: Graph,
+    node: NodeId,
+    options: ClosenessCentralityOptions = {},
+): number {
+    if (!graph.hasNode(node)) {
+        throw new Error(`Node ${String(node)} not found in graph`);
+    }
+
+    const distances = dijkstraDistances(graph, node, options.cutoff);
+
+    if (distances.size <= 1) {
+        return 0; // No other nodes reachable
+    }
+
+    let centrality = 0;
+
+    if (options.harmonic) {
+        // Harmonic centrality: sum of reciprocals of distances
+        for (const [targetNode, distance] of distances) {
+            if (targetNode !== node && distance > 0 && distance < Infinity) {
+                centrality += 1 / distance;
+            }
+        }
+    } else {
+        // Standard closeness: reciprocal of sum of distances
+        let totalDistance = 0;
+        let reachableNodes = 0;
+
+        for (const [targetNode, distance] of distances) {
+            if (targetNode !== node && distance < Infinity) {
+                totalDistance += distance;
+                reachableNodes++;
+            }
+        }
+
+        if (totalDistance > 0) {
+            centrality = 1 / totalDistance;
+
+            // Wasserman and Faust normalization for disconnected graphs
+            if (options.normalized) {
+                const n = Array.from(graph.nodes()).length;
+                centrality = centrality * reachableNodes / (n - 1);
+            }
+        }
+    }
+
+    // Normalization for harmonic centrality
+    if (options.harmonic && options.normalized) {
+        const n = Array.from(graph.nodes()).length;
+        if (n > 1) {
+            centrality = centrality / (n - 1);
+        }
+    }
+
+    return centrality;
+}
+
+/**
+ * Single-source shortest path distances using Dijkstra's algorithm
+ */
+function dijkstraDistances(
+    graph: Graph,
+    source: NodeId,
+    cutoff?: number,
+): Map<NodeId, number> {
+    const distances = new Map<NodeId, number>();
+    const visited = new Set<NodeId>();
+    const pq: {node: NodeId, distance: number}[] = [];
+
+    // Initialize distances
+    for (const node of graph.nodes()) {
+        distances.set(node.id, node.id === source ? 0 : Infinity);
+    }
+
+    pq.push({node: source, distance: 0});
+
+    while (pq.length > 0) {
+        // Simple priority queue (could be optimized with a proper heap)
+        pq.sort((a, b) => a.distance - b.distance);
+        const current = pq.shift();
+
+        if (!current || visited.has(current.node)) {
+            continue;
+        }
+
+        visited.add(current.node);
+
+        // Skip if beyond cutoff
+        if (cutoff !== undefined && current.distance > cutoff) {
+            continue;
+        }
+
+        // Explore neighbors
+        for (const neighbor of graph.neighbors(current.node)) {
+            if (visited.has(neighbor)) {
+                continue;
+            }
+
+            const edge = graph.getEdge(current.node, neighbor);
+            if (!edge) {
+                continue;
+            }
+
+            const edgeWeight = edge.weight ?? 1;
+            const tentativeDistance = current.distance + edgeWeight;
+            const currentDistance = distances.get(neighbor) ?? Infinity;
+
+            if (tentativeDistance < currentDistance) {
+                distances.set(neighbor, tentativeDistance);
+
+                // Skip if beyond cutoff
+                if (cutoff === undefined || tentativeDistance <= cutoff) {
+                    pq.push({node: neighbor, distance: tentativeDistance});
+                }
+            }
+        }
+    }
+
+    return distances;
+}

package/src/algorithms/centrality/degree.ts

@@ -0,0 +1,105 @@
+import type {Graph} from "../../core/graph.js";
+import type {CentralityOptions, CentralityResult} from "../../types/index.js";
+
+/**
+ * Degree centrality implementation
+ *
+ * Measures the importance of a node based on the number of connections it has.
+ * The most basic centrality measure that simply counts incident edges.
+ */
+
+/**
+ * Calculate degree centrality for all nodes in the graph
+ */
+export function degreeCentrality(
+    graph: Graph,
+    options: CentralityOptions = {},
+): CentralityResult {
+    const centrality: CentralityResult = {};
+    const {nodeCount} = graph;
+
+    // Calculate normalization factor
+    const maxPossibleDegree = graph.isDirected ? nodeCount - 1 : nodeCount - 1;
+
+    for (const node of graph.nodes()) {
+        let degree: number;
+
+        if (graph.isDirected && options.mode) {
+            // For directed graphs, calculate specific degree type
+            switch (options.mode) {
+                case "in": {
+                    degree = graph.inDegree(node.id);
+                    break;
+                }
+                case "out": {
+                    degree = graph.outDegree(node.id);
+                    break;
+                }
+                case "total": {
+                    degree = graph.degree(node.id);
+                    break;
+                }
+                default: {
+                    degree = graph.degree(node.id);
+                }
+            }
+        } else {
+            // For undirected graphs or default case
+            degree = graph.degree(node.id);
+        }
+
+        // Apply normalization if requested
+        const normalizedDegree = options.normalized && maxPossibleDegree > 0 ?
+            degree / maxPossibleDegree :
+            degree;
+
+        centrality[node.id.toString()] = normalizedDegree;
+    }
+
+    return centrality;
+}
+
+/**
+ * Calculate degree centrality for a specific node
+ */
+export function nodeDegreeCentrality(
+    graph: Graph,
+    nodeId: string | number,
+    options: CentralityOptions = {},
+): number {
+    if (!graph.hasNode(nodeId)) {
+        throw new Error(`Node ${String(nodeId)} not found in graph`);
+    }
+
+    const {nodeCount} = graph;
+    let degree: number;
+
+    if (graph.isDirected && options.mode) {
+        switch (options.mode) {
+            case "in": {
+                degree = graph.inDegree(nodeId);
+                break;
+            }
+            case "out": {
+                degree = graph.outDegree(nodeId);
+                break;
+            }
+            case "total": {
+                degree = graph.degree(nodeId);
+                break;
+            }
+            default: {
+                degree = graph.degree(nodeId);
+            }
+        }
+    } else {
+        degree = graph.degree(nodeId);
+    }
+
+    // Apply normalization if requested
+    const maxPossibleDegree = nodeCount - 1;
+
+    return options.normalized && maxPossibleDegree > 0 ?
+        degree / maxPossibleDegree :
+        degree;
+}

package/src/algorithms/centrality/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Centrality algorithms
+ */
+
+export type {BetweennessCentralityOptions} from "./betweenness.js";
+export {betweennessCentrality, edgeBetweennessCentrality, nodeBetweennessCentrality} from "./betweenness.js";
+export type {ClosenessCentralityOptions} from "./closeness.js";
+export {closenessCentrality, nodeClosenessCentrality, nodeWeightedClosenessCentrality, weightedClosenessCentrality} from "./closeness.js";
+export {degreeCentrality, nodeDegreeCentrality} from "./degree.js";
+export type {PageRankOptions, PageRankResult} from "./pagerank.js";
+export {pageRank, pageRankCentrality, personalizedPageRank, topPageRankNodes} from "./pagerank.js";

package/src/algorithms/centrality/pagerank.ts

@@ -0,0 +1,302 @@
+import type {Graph} from "../../core/graph.js";
+import type {NodeId} from "../../types/index.js";
+
+/**
+ * PageRank algorithm implementation
+ *
+ * Measures the importance of nodes in a directed graph based on the
+ * structure of incoming links. Originally designed for ranking web pages.
+ */
+
+/**
+ * PageRank algorithm options
+ */
+export interface PageRankOptions {
+    /**
+     * Damping factor (probability of following a link) (default: 0.85)
+     */
+    dampingFactor?: number;
+    /**
+     * Maximum number of iterations (default: 100)
+     */
+    maxIterations?: number;
+    /**
+     * Convergence tolerance (default: 1e-6)
+     */
+    tolerance?: number;
+    /**
+     * Initial PageRank values for nodes (default: uniform distribution)
+     */
+    initialRanks?: Map<NodeId, number>;
+    /**
+     * Personalization vector for Personalized PageRank (default: null)
+     */
+    personalization?: Map<NodeId, number>;
+    /**
+     * Weight attribute for weighted PageRank (default: null = unweighted)
+     */
+    weight?: string;
+}
+
+/**
+ * PageRank algorithm result
+ */
+export interface PageRankResult {
+    /**
+     * PageRank scores for each node
+     */
+    ranks: Record<string, number>;
+    /**
+     * Number of iterations until convergence
+     */
+    iterations: number;
+    /**
+     * Whether the algorithm converged
+     */
+    converged: boolean;
+}
+
+/**
+ * Calculate PageRank for all nodes in the graph
+ */
+export function pageRank(
+    graph: Graph,
+    options: PageRankOptions = {},
+): PageRankResult {
+    const {
+        dampingFactor = 0.85,
+        maxIterations = 100,
+        tolerance = 1e-6,
+        initialRanks,
+        personalization,
+        weight,
+    } = options;
+
+    if (!graph.isDirected) {
+        throw new Error("PageRank requires a directed graph");
+    }
+
+    if (dampingFactor < 0 || dampingFactor > 1) {
+        throw new Error("Damping factor must be between 0 and 1");
+    }
+
+    const nodes = Array.from(graph.nodes()).map((node) => node.id);
+    const n = nodes.length;
+
+    if (n === 0) {
+        return {ranks: {}, iterations: 0, converged: true};
+    }
+
+    // Initialize PageRank values
+    let ranks = new Map<NodeId, number>();
+    if (initialRanks) {
+        for (const nodeId of nodes) {
+            ranks.set(nodeId, initialRanks.get(nodeId) ?? 1 / n);
+        }
+    } else {
+        for (const nodeId of nodes) {
+            ranks.set(nodeId, 1 / n);
+        }
+    }
+
+    // Normalize initial ranks
+    normalizeRanks(ranks);
+
+    // Calculate out-degrees and handle dangling nodes
+    const outDegrees = new Map<NodeId, number>();
+    const outWeights = new Map<NodeId, number>();
+    const danglingNodes: NodeId[] = [];
+
+    for (const nodeId of nodes) {
+        let outDegree = 0;
+        let totalOutWeight = 0;
+
+        for (const neighbor of graph.neighbors(nodeId)) {
+            outDegree++;
+            if (weight) {
+                const edge = graph.getEdge(nodeId, neighbor);
+                const edgeWeight = edge?.weight ?? 1;
+                totalOutWeight += edgeWeight;
+            } else {
+                totalOutWeight += 1;
+            }
+        }
+
+        outDegrees.set(nodeId, outDegree);
+        outWeights.set(nodeId, totalOutWeight);
+
+        if (outDegree === 0) {
+            danglingNodes.push(nodeId);
+        }
+    }
+
+    // Setup personalization vector
+    let personalVector: Map<NodeId, number> | null = null;
+    if (personalization) {
+        personalVector = new Map(personalization);
+        normalizeRanks(personalVector);
+    }
+
+    let converged = false;
+    let iteration = 0;
+
+    // Power iteration
+    for (iteration = 0; iteration < maxIterations; iteration++) {
+        const newRanks = new Map<NodeId, number>();
+
+        // Initialize with teleportation probability
+        for (const nodeId of nodes) {
+            if (personalVector) {
+                newRanks.set(nodeId, (1 - dampingFactor) * (personalVector.get(nodeId) ?? 0));
+            } else {
+                newRanks.set(nodeId, (1 - dampingFactor) / n);
+            }
+        }
+
+        // Handle dangling nodes
+        let danglingSum = 0;
+        for (const danglingNode of danglingNodes) {
+            danglingSum += ranks.get(danglingNode) ?? 0;
+        }
+
+        if (danglingSum > 0) {
+            const danglingContribution = dampingFactor * danglingSum / n;
+            for (const nodeId of nodes) {
+                const currentRank = newRanks.get(nodeId) ?? 0;
+                if (personalVector) {
+                    const personalContrib = danglingContribution * (personalVector.get(nodeId) ?? 0);
+                    newRanks.set(nodeId, currentRank + personalContrib);
+                } else {
+                    newRanks.set(nodeId, currentRank + danglingContribution);
+                }
+            }
+        }
+
+        // Propagate rank from each node to its neighbors
+        for (const nodeId of nodes) {
+            const currentRank = ranks.get(nodeId) ?? 0;
+            const nodeOutWeight = outWeights.get(nodeId) ?? 0;
+
+            if (nodeOutWeight > 0) {
+                for (const neighbor of graph.neighbors(nodeId)) {
+                    let edgeWeight = 1;
+                    if (weight) {
+                        const edge = graph.getEdge(nodeId, neighbor);
+                        edgeWeight = edge?.weight ?? 1;
+                    }
+
+                    const contribution = dampingFactor * currentRank * (edgeWeight / nodeOutWeight);
+                    const neighborRank = newRanks.get(neighbor) ?? 0;
+                    newRanks.set(neighbor, neighborRank + contribution);
+                }
+            }
+        }
+
+        // Check for convergence
+        let maxDiff = 0;
+        for (const nodeId of nodes) {
+            const oldRank = ranks.get(nodeId) ?? 0;
+            const newRank = newRanks.get(nodeId) ?? 0;
+            maxDiff = Math.max(maxDiff, Math.abs(newRank - oldRank));
+        }
+
+        ranks = newRanks;
+
+        if (maxDiff < tolerance) {
+            converged = true;
+            break;
+        }
+    }
+
+    // Convert to string-keyed record
+    const result: Record<string, number> = {};
+    for (const nodeId of nodes) {
+        result[String(nodeId)] = ranks.get(nodeId) ?? 0;
+    }
+
+    return {
+        ranks: result,
+        iterations: iteration + 1,
+        converged,
+    };
+}
+
+/**
+ * Calculate Personalized PageRank for a specific set of source nodes
+ */
+export function personalizedPageRank(
+    graph: Graph,
+    personalNodes: NodeId[],
+    options: Omit<PageRankOptions, "personalization"> = {},
+): PageRankResult {
+    const nodes = Array.from(graph.nodes()).map((node) => node.id);
+    const personalization = new Map<NodeId, number>();
+
+    // Initialize personalization vector
+    for (const nodeId of nodes) {
+        personalization.set(nodeId, 0);
+    }
+
+    // Set equal probability for personal nodes
+    const personalValue = 1 / personalNodes.length;
+    for (const personalNode of personalNodes) {
+        if (!graph.hasNode(personalNode)) {
+            throw new Error(`Personal node ${String(personalNode)} not found in graph`);
+        }
+
+        personalization.set(personalNode, personalValue);
+    }
+
+    return pageRank(graph, {
+        ... options,
+        personalization,
+    });
+}
+
+/**
+ * Calculate PageRank centrality (normalized PageRank scores)
+ */
+export function pageRankCentrality(
+    graph: Graph,
+    options: PageRankOptions = {},
+): Record<string, number> {
+    const result = pageRank(graph, options);
+    return result.ranks;
+}
+
+/**
+ * Get the top-k nodes by PageRank score
+ */
+export function topPageRankNodes(
+    graph: Graph,
+    k: number,
+    options: PageRankOptions = {},
+): {node: NodeId, rank: number}[] {
+    const result = pageRank(graph, options);
+
+    const nodeRanks: {node: NodeId, rank: number}[] = [];
+    for (const [nodeStr, rank] of Object.entries(result.ranks)) {
+        nodeRanks.push({node: nodeStr as NodeId, rank});
+    }
+
+    // Sort by rank in descending order
+    nodeRanks.sort((a, b) => b.rank - a.rank);
+
+    return nodeRanks.slice(0, k);
+}
+
+/**
+ * Normalize ranks so they sum to 1
+ */
+function normalizeRanks(ranks: Map<NodeId, number>): void {
+    let sum = 0;
+    for (const rank of ranks.values()) {
+        sum += rank;
+    }
+
+    if (sum > 0) {
+        for (const [nodeId, rank] of ranks) {
+            ranks.set(nodeId, rank / sum);
+        }
+    }
+}