@graphty/algorithms 2.1.2 → 2.2.0

package/src/link-prediction/common-neighbors.ts

@@ -1,28 +1,57 @@
+/**
+ * Common-neighbour link prediction over a legacy `Graph`. Every function here delegates to its
+ * `indexed.*` port over an unweighted snapshot of the graph (the scores never read a weight) and
+ * keeps its signature and result shape; the results equal the pre-migration implementation in
+ * `common-neighbors-legacy.ts` exactly.
+ *
+ * A node argument is looked up by the id itself, never by its spelling, as `graph.hasNode` does: a
+ * node that is not in the graph scores 0 and has no candidates.
+ * @module
+ */
+
+import type { GraphSnapshot } from "@graphty/graph-format";
+
 import type { Graph } from "../core/graph.js";
+import { commonNeighborsScore as indexedCommonNeighborsScore } from "../indexed/common-neighbors.js";
+import {
+    commonNeighborsForPairs as indexedCommonNeighborsForPairs,
+    commonNeighborsPrediction as indexedCommonNeighborsPrediction,
+    evaluateCommonNeighbors as indexedEvaluateCommonNeighbors,
+    getTopCandidatesForNode as indexedGetTopCandidatesForNode,
+    type LinkPredictionResult,
+    type NodePairs,
+} from "../indexed/link-prediction.js";
+import { toTopologySnapshot } from "../indexed/to-snapshot.js";
 import type { NodeId } from "../types/index.js";
-import { getCommonNeighbors, getIntermediateNodes } from "../utils/graph-utilities.js";
+import type { LinkPredictionOptions, LinkPredictionScore } from "./common-neighbors-legacy.js";
+
+export type { LinkPredictionOptions, LinkPredictionScore } from "./common-neighbors-legacy.js";
 
 /**
- * Common Neighbors link prediction implementation
- *
- * Predicts the likelihood of a link between two nodes based on the number
- * of common neighbors they share. The intuition is that nodes with many
- * common neighbors are more likely to be connected.
- *
- * Time complexity: O(k²) where k is the average degree
- * Space complexity: O(k)
+ * Id pairs to index pairs; an id not in the graph becomes `INVALID_INDEX`, which scores 0.
+ * @param s - The snapshot
+ * @param pairs - The caller's id pairs
+ * @returns The index pairs
  */
-
-export interface LinkPredictionScore {
-    source: NodeId;
-    target: NodeId;
-    score: number;
+function toNodePairs(s: GraphSnapshot, pairs: [NodeId, NodeId][]): NodePairs {
+    return {
+        sources: Uint32Array.from(pairs, ([u]) => s.ids.indexOf(u)),
+        targets: Uint32Array.from(pairs, ([, v]) => s.ids.indexOf(v)),
+    };
 }
 
-export interface LinkPredictionOptions {
-    directed?: boolean; // Consider direction (default: false)
-    includeExisting?: boolean; // Include existing edges (default: false)
-    topK?: number; // Return only top K predictions
+/**
+ * Ranked index pairs to the legacy score objects.
+ * @param s - The snapshot
+ * @param r - The port's ranked pairs
+ * @returns One score object per pair, in rank order
+ */
+function toScores(s: GraphSnapshot, r: LinkPredictionResult): LinkPredictionScore[] {
+    return Array.from(r.scores, (score, k) => ({
+        source: s.ids.idOf(r.sources[k]),
+        target: s.ids.idOf(r.targets[k]),
+        score,
+    }));
 }
 
 /**
@@ -39,19 +68,13 @@ export function commonNeighborsScore(
     target: NodeId,
     options: LinkPredictionOptions = {},
 ): number {
-    if (!graph.hasNode(source) || !graph.hasNode(target)) {
+    const s = toTopologySnapshot(graph);
+    const u = s.ids.indexOf(source);
+    const v = s.ids.indexOf(target);
+    if (u >= s.nodeCount || v >= s.nodeCount) {
         return 0;
     }
-
-    const { directed = false } = options;
-
-    // Use utility function to get common neighbors
-    // For directed graphs, we want intermediate nodes that form paths source->X->target
-    const commonNeighborsSet = directed
-        ? getIntermediateNodes(graph, source, target)
-        : getCommonNeighbors(graph, source, target, false);
-
-    return commonNeighborsSet.size;
+    return indexedCommonNeighborsScore(s, u, v, { directed: options.directed });
 }
 
 /**
@@ -61,47 +84,8 @@ export function commonNeighborsScore(
  * @returns Array of link prediction scores sorted by score descending
  */
 export function commonNeighborsPrediction(graph: Graph, options: LinkPredictionOptions = {}): LinkPredictionScore[] {
-    const { directed = false, includeExisting = false, topK } = options;
-
-    const scores: LinkPredictionScore[] = [];
-    const nodes = Array.from(graph.nodes()).map((n) => n.id);
-
-    for (let i = 0; i < nodes.length; i++) {
-        for (let j = i + 1; j < nodes.length; j++) {
-            const source = nodes[i];
-            const target = nodes[j];
-
-            if (source === undefined || target === undefined) {
-                continue;
-            }
-
-            // Skip existing edges unless requested
-            if (!includeExisting && graph.hasEdge(source, target)) {
-                continue;
-            }
-
-            const score = commonNeighborsScore(graph, source, target, { directed });
-
-            if (score > 0) {
-                scores.push({ source, target, score });
-
-                // For undirected graphs, also add the reverse pair
-                if (!directed && source !== target) {
-                    scores.push({ source: target, target: source, score });
-                }
-            }
-        }
-    }
-
-    // Sort by score in descending order
-    scores.sort((a, b) => b.score - a.score);
-
-    // Return top K if specified
-    if (topK && topK > 0) {
-        return scores.slice(0, topK);
-    }
-
-    return scores;
+    const s = toTopologySnapshot(graph);
+    return toScores(s, indexedCommonNeighborsPrediction(s, options));
 }
 
 /**
@@ -116,11 +100,9 @@ export function commonNeighborsForPairs(
     pairs: [NodeId, NodeId][],
     options: LinkPredictionOptions = {},
 ): LinkPredictionScore[] {
-    return pairs.map(([source, target]) => ({
-        source,
-        target,
-        score: commonNeighborsScore(graph, source, target, options),
-    }));
+    const s = toTopologySnapshot(graph);
+    const scores = indexedCommonNeighborsForPairs(s, toNodePairs(s, pairs), { directed: options.directed });
+    return pairs.map(([source, target], k) => ({ source, target, score: scores[k] }));
 }
 
 /**
@@ -135,36 +117,9 @@ export function getTopCandidatesForNode(
     node: NodeId,
     options: LinkPredictionOptions & { candidates?: NodeId[] } = {},
 ): LinkPredictionScore[] {
-    if (!graph.hasNode(node)) {
-        return [];
-    }
-
-    const { directed = false, includeExisting = false, topK = 10, candidates } = options;
-
-    const scores: LinkPredictionScore[] = [];
-    const targetNodes = candidates ?? Array.from(graph.nodes()).map((n) => n.id);
-
-    for (const target of targetNodes) {
-        if (target === node) {
-            continue;
-        }
-
-        // Skip existing edges unless requested
-        if (!includeExisting && graph.hasEdge(node, target)) {
-            continue;
-        }
-
-        const score = commonNeighborsScore(graph, node, target, { directed });
-
-        if (score > 0) {
-            scores.push({ source: node, target, score });
-        }
-    }
-
-    // Sort by score in descending order
-    scores.sort((a, b) => b.score - a.score);
-
-    return scores.slice(0, topK);
+    const s = toTopologySnapshot(graph);
+    const candidates = options.candidates?.map((id) => s.ids.indexOf(id));
+    return toScores(s, indexedGetTopCandidatesForNode(s, s.ids.indexOf(node), { ...options, candidates }));
 }
 
 /**
@@ -186,67 +141,9 @@ export function evaluateCommonNeighbors(
     f1Score: number;
     auc: number;
 } {
-    // Get scores for test edges and non-edges
-    const testScores = commonNeighborsForPairs(trainingGraph, testEdges, options);
-    const nonEdgeScores = commonNeighborsForPairs(trainingGraph, nonEdges, options);
-
-    // Combine and sort all scores
-    const allScores = [
-        ...testScores.map((s) => ({ ...s, isActualEdge: true })),
-        ...nonEdgeScores.map((s) => ({ ...s, isActualEdge: false })),
-    ].sort((a, b) => b.score - a.score);
-
-    // Calculate precision and recall at different thresholds
-    let truePositives = 0;
-    let falsePositives = 0;
-    let bestF1 = 0;
-    let bestPrecision = 0;
-    let bestRecall = 0;
-
-    const totalPositives = testEdges.length;
-
-    for (const scoreItem of allScores) {
-        if (scoreItem.isActualEdge) {
-            truePositives++;
-        } else {
-            falsePositives++;
-        }
-
-        const precision = truePositives / (truePositives + falsePositives);
-        const recall = truePositives / totalPositives;
-        const f1 = precision + recall > 0 ? (2 * (precision * recall)) / (precision + recall) : 0;
-
-        if (f1 > bestF1) {
-            bestF1 = f1;
-            bestPrecision = precision;
-            bestRecall = recall;
-        }
-    }
-
-    // Calculate AUC (Area Under Curve)
-    let auc = 0;
-    let tpCount = 0;
-    let fpCount = 0;
-
-    for (const item of allScores) {
-        if (item.isActualEdge) {
-            tpCount++;
-        } else {
-            auc += tpCount;
-            fpCount++;
-        }
-    }
-
-    if (tpCount > 0 && fpCount > 0) {
-        auc = auc / (tpCount * fpCount);
-    } else {
-        auc = 0.5; // Random performance
-    }
-
-    return {
-        precision: bestPrecision,
-        recall: bestRecall,
-        f1Score: bestF1,
-        auc,
-    };
+    const s = toTopologySnapshot(trainingGraph);
+    const metrics = indexedEvaluateCommonNeighbors(s, toNodePairs(s, testEdges), toNodePairs(s, nonEdges), {
+        directed: options.directed,
+    });
+    return { ...metrics };
 }

package/src/optimized/direction-optimized-bfs.ts

@@ -28,6 +28,12 @@ interface BFSResult<TNodeId> {
  *
  * Based on: Beamer, S., Asanović, K., & Patterson, D. (2012).
  * "Direction-optimizing breadth-first search." SC'12.
+ *
+ * The snapshot replacement is `indexed.directionOptimizedBfs`, which gives the same distances,
+ * and the same parents when the snapshot numbers nodes in this class's CSR order. This class
+ * keeps its own code rather than delegating: it runs on a `CSRGraph`, not a `Graph`;
+ * `searchMultiple` has no single-call equivalent; and a second `search` without `reset` keeps
+ * the previous search's nodes, where the replacement starts every call afresh.
  */
 export class DirectionOptimizedBFS<TNodeId = NodeId> {
     private graph: CSRGraph<TNodeId>;
@@ -292,4 +298,3 @@ export function directionOptimizedBFS<TNodeId = NodeId>(
     const bfs = new DirectionOptimizedBFS(graph, options);
     return bfs.search(source);
 }
-