graphwise 1.2.0 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 # graphwise
 
-Low-dependency TypeScript graph algorithms for citation network analysis.
+Low-dependency TypeScript graph algorithms for citation network analysis: novel expansion, MI variants, and path ranking.
 
 ## Features
 
@@ -20,7 +20,7 @@ pnpm add graphwise
 ## Usage
 
 ```typescript
-import { AdjacencyMapGraph, dome, parse, jaccard } from 'graphwise';
+import { AdjacencyMapGraph, dome, parse, jaccard } from "graphwise";
 
 const graph = AdjacencyMapGraph.undirected();
 // add nodes and edges...
@@ -29,6 +29,153 @@ const result = dome(graph, seeds);
 const ranked = parse(graph, result.paths, { mi: jaccard });
 ```
 
+## Algorithms
+
+### Expansion: BASE Framework
+
+**Boundary-free Adaptive Seeded Expansion** (BASE) is a parameter-free graph expansion algorithm. Given a graph $G = (V, E)$ and seed nodes $S \subseteq V$, BASE produces the subgraph induced by all vertices visited during priority-ordered expansion until frontier exhaustion:
+
+$$G_S = (V_S, E_S) \quad \text{where} \quad V_S = \bigcup_{v \in S} \text{Expand}(v, \pi)$$
+
+Three key properties:
+
+1. **Priority-ordered exploration**: the vertex with globally minimum priority $\pi(v)$ is expanded next across all frontiers
+2. **Frontier collision detection**: when a vertex is reached by multiple frontiers, the connecting path is recorded
+3. **Implicit termination**: halts when all frontier queues are empty; no depth bound or size threshold
+
+#### DOME: Degree-Ordered Multi-seed Expansion
+
+The default priority function uses degree-based hub deferral:
+
+$$\pi(v) = \frac{\deg^{+}(v) + \deg^{-}(v)}{w_V(v) + \varepsilon}$$
+
+where $\deg^{+}(v)$ is weighted out-degree, $\deg^{-}(v)$ is weighted in-degree, $w_V(v)$ is node weight, and $\varepsilon > 0$ prevents division by zero.
+
+#### Expansion Variants
+
+| Algorithm | Priority Function                                      | Phases |
+| --------- | ------------------------------------------------------ | ------ |
+| **DOME**  | Degree (hub deferral)                                  | 1      |
+| **EDGE**  | Local neighbourhood type entropy                       | 1      |
+| **HAE**   | User-supplied type entropy (generalises EDGE)          | 1      |
+| **PIPE**  | Path potential (neighbours visited by other frontiers) | 1      |
+| **SAGE**  | Salience accumulation from discovered paths            | 2      |
+| **REACH** | Rolling MI estimates of discovered path quality        | 2      |
+| **MAZE**  | PIPE + SAGE + adaptive termination                     | 3      |
+
+### Path Ranking: PARSE
+
+**Path Aggregation Ranked by Salience Estimation** (PARSE) scores paths by the geometric mean of per-edge mutual information, eliminating length bias:
+
+$$M(P) = \exp\left( \frac{1}{k} \sum_{i=1}^{k} \log I(u_i, v_i) \right)$$
+
+where $k$ is path length (number of edges) and $I(u_i, v_i)$ is the per-edge MI score from any variant below. The geometric mean ensures a 10-hop path with consistently high-MI edges scores equally to a 2-hop path with the same average MI.
+
+---
+
+### MI Variants
+
+Seven MI variants serve as per-edge estimators within PARSE. All build on Jaccard neighbourhood overlap, then weight by domain-specific structural properties.
+
+---
+
+#### Jaccard (baseline)
+
+$$I_{\text{Jac}}(u, v) = \frac{|N(u) \cap N(v)|}{|N(u) \cup N(v)|}$$
+
+Standard neighbourhood overlap. Default MI estimator.
+
+---
+
+#### Adamic-Adar
+
+$$I_{\text{AA}}(u, v) = \sum_{w \in N(u) \cap N(v)} \frac{1}{\log(\deg(w) + 1)}$$
+
+Downweights common neighbours with high degree. Shared hub neighbours are less informative than shared rare neighbours.
+
+---
+
+#### SCALE: Structural Correction via Adjusted Local Estimation
+
+$$I_{\text{SCALE}}(u, v) = \frac{J(N(u), N(v))}{\rho(G)}$$
+
+where $\rho(G) = \frac{2|E|}{|V|(|V|-1)}$ is graph density. Normalises Jaccard by density so that overlap in dense subgraphs is not artificially inflated.
+
+---
+
+#### SKEW: Sparse-weighted Knowledge Emphasis Weighting
+
+$$I_{\text{SKEW}}(u, v) = J(N(u), N(v)) \cdot \log\!\left(\frac{N}{\deg(u) + 1}\right) \cdot \log\!\left(\frac{N}{\deg(v) + 1}\right)$$
+
+where $N = |V|$. IDF-style rarity weighting on both endpoints. Paths through low-degree (rare) nodes score higher; paths through hubs score lower.
+
+---
+
+#### SPAN: Spanning-community Penalty for Adjacent Nodes
+
+$$I_{\text{SPAN}}(u, v) = J(N(u), N(v)) \cdot \bigl(1 - \max(C(u), C(v))\bigr)$$
+
+where $C(v)$ is the local clustering coefficient. Penalises edges within tight clusters; rewards edges bridging communities (structural holes).
+
+---
+
+#### ETCH: Edge Type Contrast Heuristic
+
+$$I_{\text{ETCH}}(u, v) = J(N(u), N(v)) \cdot \log\!\left(\frac{|E|}{\text{count}(\text{edges with type}(u,v))}\right)$$
+
+Weights Jaccard by edge-type rarity. Paths traversing rare edge types receive higher scores. Requires edge-type annotations; falls back to Jaccard when unavailable.
+
+---
+
+#### NOTCH: Node Type Contrast Heuristic
+
+$$I_{\text{NOTCH}}(u, v) = J(N(u), N(v)) \cdot \log\!\left(\frac{|V|}{c(\tau_u)}\right) \cdot \log\!\left(\frac{|V|}{c(\tau_v)}\right)$$
+
+where $c(\tau_u)$ is the count of nodes with the same type as $u$. Weights Jaccard by node-type rarity for both endpoints.
+
+---
+
+### Ranking Baselines
+
+| Measure                     | Formula                                             |
+| --------------------------- | --------------------------------------------------- |
+| **Katz Index**              | $\sum_{k=1}^{\infty} \beta^k (A^k)_{st}$            |
+| **Communicability**         | $(e^A)_{st}$                                        |
+| **Resistance Distance**     | $L^{+}_{ss} + L^{+}_{tt} - 2L^{+}_{st}$             |
+| **Jaccard Arithmetic Mean** | $\frac{1}{k} \sum J(N(u), N(v))$                    |
+| **Degree-Sum**              | $\sum_{v \in P} \deg(v)$                            |
+| **Widest Path**             | $\min_{(u,v) \in P} w(u,v)$                         |
+| **PageRank**                | Stationary distribution of random walk with damping |
+| **Betweenness**             | Fraction of shortest paths through node             |
+| **Random**                  | Uniform random score (null baseline)                |
+
+### Seed Selection: GRASP
+
+**Graph-agnostic Representative seed pAir Sampling**: selects structurally representative seed pairs from an unknown graph using reservoir sampling and structural feature clustering. Operates blind: no full graph loading, no ground-truth labels, no human-defined strata.
+
+Three phases:
+
+1. **Reservoir sampling**: stream graph edges; maintain a reservoir of $N$ nodes
+2. **Structural features**: for each sampled node compute $\log(\deg + 1)$, clustering coefficient, approximate PageRank
+3. **Cluster and sample**: MiniBatchKMeans into $K$ groups; sample within-cluster and cross-cluster pairs
+
+## Module Exports
+
+```typescript
+import { ... } from 'graphwise';           // Everything
+import { ... } from 'graphwise/graph';      // Graph data structures
+import { ... } from 'graphwise/expansion';  // Expansion algorithms
+import { ... } from 'graphwise/ranking';    // PARSE + baselines
+import { ... } from 'graphwise/ranking/mi'; // MI variants
+import { ... } from 'graphwise/seeds';      // Seed selection
+import { ... } from 'graphwise/traversal';  // Graph traversal
+import { ... } from 'graphwise/structures'; // Data structures
+import { ... } from 'graphwise/extraction'; // Subgraph extraction
+import { ... } from 'graphwise/utils';      // Utilities
+import { ... } from 'graphwise/gpu';        // WebGPU acceleration
+import { ... } from 'graphwise/schemas';    // Zod schemas
+```
+
 ## Commands
 
 ```bash

package/dist/index/index.cjs

@@ -3,8 +3,8 @@ const require_graph = require("../graph/index.cjs");
 const require_traversal = require("../traversal/index.cjs");
 const require_structures = require("../structures/index.cjs");
 const require_kmeans = require("../kmeans-BIgSyGKu.cjs");
-const require_seeds = require("../seeds/index.cjs");
 const require_utils = require("../utils/index.cjs");
+const require_seeds = require("../seeds/index.cjs");
 const require_gpu = require("../gpu/index.cjs");
 //#region src/expansion/base.ts
 /**
@@ -299,15 +299,9 @@ function edge(graph, seeds, config) {
 */
 function jaccard(graph, source, target, config) {
 	const { epsilon = 1e-10 } = config ?? {};
-	const sourceNeighbours = new Set(graph.neighbours(source));
-	const targetNeighbours = new Set(graph.neighbours(target));
-	sourceNeighbours.delete(target);
-	targetNeighbours.delete(source);
-	let intersectionSize = 0;
-	for (const neighbour of sourceNeighbours) if (targetNeighbours.has(neighbour)) intersectionSize++;
-	const unionSize = sourceNeighbours.size + targetNeighbours.size - intersectionSize;
-	if (unionSize === 0) return 0;
-	const score = intersectionSize / unionSize;
+	const { intersection, union } = require_utils.neighbourOverlap(require_utils.neighbourSet(graph, source, target), require_utils.neighbourSet(graph, target, source));
+	if (union === 0) return 0;
+	const score = intersection / union;
 	return Math.max(epsilon, score);
 }
 //#endregion
@@ -687,19 +681,14 @@ function computePathSalience(graph, path, mi, epsilon) {
 */
 function adamicAdar(graph, source, target, config) {
 	const { epsilon = 1e-10, normalise = true } = config ?? {};
-	const sourceNeighbours = new Set(graph.neighbours(source));
-	const targetNeighbours = new Set(graph.neighbours(target));
-	sourceNeighbours.delete(target);
-	targetNeighbours.delete(source);
+	const commonNeighbours = require_utils.neighbourIntersection(require_utils.neighbourSet(graph, source, target), require_utils.neighbourSet(graph, target, source));
 	let score = 0;
-	for (const neighbour of sourceNeighbours) if (targetNeighbours.has(neighbour)) {
+	for (const neighbour of commonNeighbours) {
 		const degree = graph.degree(neighbour);
-		if (degree > 1) score += 1 / Math.log(degree);
+		score += 1 / Math.log(degree + 1);
 	}
-	if (normalise) {
-		const commonCount = sourceNeighbours.size < targetNeighbours.size ? sourceNeighbours.size : targetNeighbours.size;
-		if (commonCount === 0) return 0;
-		const maxScore = commonCount / Math.log(2);
+	if (normalise && commonNeighbours.size > 0) {
+		const maxScore = commonNeighbours.size / Math.log(2);
 		score = score / maxScore;
 	}
 	return Math.max(epsilon, score);
@@ -711,22 +700,15 @@ function adamicAdar(graph, source, target, config) {
 */
 function scale(graph, source, target, config) {
 	const { epsilon = 1e-10 } = config ?? {};
-	const sourceNeighbours = new Set(graph.neighbours(source));
-	const targetNeighbours = new Set(graph.neighbours(target));
-	sourceNeighbours.delete(target);
-	targetNeighbours.delete(source);
-	const sourceDegree = sourceNeighbours.size;
-	const targetDegree = targetNeighbours.size;
-	let intersectionSize = 0;
-	for (const neighbour of sourceNeighbours) if (targetNeighbours.has(neighbour)) intersectionSize++;
-	const unionSize = sourceDegree + targetDegree - intersectionSize;
-	const jaccard = unionSize > 0 ? intersectionSize / unionSize : 0;
-	const minDegree = Math.min(sourceDegree, targetDegree);
-	const maxDegree = Math.max(sourceDegree, targetDegree);
-	const degreeRatio = maxDegree > 0 ? minDegree / maxDegree : 0;
-	if (jaccard + degreeRatio === 0) return epsilon;
-	const score = 2 * jaccard * degreeRatio / (jaccard + degreeRatio);
-	return Math.max(epsilon, Math.min(1, score));
+	const { intersection, union } = require_utils.neighbourOverlap(require_utils.neighbourSet(graph, source, target), require_utils.neighbourSet(graph, target, source));
+	const jaccard = union > 0 ? intersection / union : 0;
+	const n = graph.nodeCount;
+	const m = graph.edgeCount;
+	const densityNormaliser = graph.directed ? n * (n - 1) : 2 * n * (n - 1);
+	const density = densityNormaliser > 0 ? m / densityNormaliser : 0;
+	if (density === 0) return epsilon;
+	const score = jaccard / density;
+	return Math.max(epsilon, score);
 }
 //#endregion
 //#region src/ranking/mi/skew.ts
@@ -735,23 +717,15 @@ function scale(graph, source, target, config) {
 */
 function skew(graph, source, target, config) {
 	const { epsilon = 1e-10 } = config ?? {};
-	const sourceNeighbours = new Set(graph.neighbours(source));
-	const targetNeighbours = new Set(graph.neighbours(target));
-	sourceNeighbours.delete(target);
-	targetNeighbours.delete(source);
-	let weightedIntersection = 0;
-	let commonCount = 0;
-	for (const neighbour of sourceNeighbours) if (targetNeighbours.has(neighbour)) {
-		commonCount++;
-		const degree = graph.degree(neighbour);
-		if (degree > 1) weightedIntersection += 1 / Math.log(degree);
-	}
-	if (commonCount === 0) return epsilon;
-	const sourceDegree = sourceNeighbours.size;
-	const targetDegree = targetNeighbours.size;
-	const maxScore = Math.min(sourceDegree, targetDegree) / Math.log(2);
-	const score = weightedIntersection / maxScore;
-	return Math.max(epsilon, Math.min(1, score));
+	const { intersection, union } = require_utils.neighbourOverlap(require_utils.neighbourSet(graph, source, target), require_utils.neighbourSet(graph, target, source));
+	const jaccard = union > 0 ? intersection / union : 0;
+	const N = graph.nodeCount;
+	const sourceDegree = graph.degree(source);
+	const targetDegree = graph.degree(target);
+	const sourceIdf = Math.log(N / (sourceDegree + 1));
+	const targetIdf = Math.log(N / (targetDegree + 1));
+	const score = jaccard * sourceIdf * targetIdf;
+	return Math.max(epsilon, score);
 }
 //#endregion
 //#region src/ranking/mi/span.ts
@@ -760,21 +734,12 @@ function skew(graph, source, target, config) {
 */
 function span(graph, source, target, config) {
 	const { epsilon = 1e-10 } = config ?? {};
-	const sourceNeighbours = new Set(graph.neighbours(source));
-	const targetNeighbours = new Set(graph.neighbours(target));
-	sourceNeighbours.delete(target);
-	targetNeighbours.delete(source);
-	const sourceDegree = sourceNeighbours.size;
-	const targetDegree = targetNeighbours.size;
-	let intersectionSize = 0;
-	for (const neighbour of sourceNeighbours) if (targetNeighbours.has(neighbour)) intersectionSize++;
-	const unionSize = sourceDegree + targetDegree - intersectionSize;
-	const jaccard = unionSize > 0 ? intersectionSize / unionSize : 0;
-	const maxDegree = Math.max(sourceDegree, targetDegree);
-	const degreeDiff = Math.abs(sourceDegree - targetDegree);
-	const degreeSimilarity = maxDegree > 0 ? 1 - degreeDiff / maxDegree : 1;
-	const score = Math.sqrt(jaccard * degreeSimilarity);
-	return Math.max(epsilon, Math.min(1, score));
+	const { intersection, union } = require_utils.neighbourOverlap(require_utils.neighbourSet(graph, source, target), require_utils.neighbourSet(graph, target, source));
+	const jaccard = union > 0 ? intersection / union : 0;
+	const sourceCc = require_utils.localClusteringCoefficient(graph, source);
+	const targetCc = require_utils.localClusteringCoefficient(graph, target);
+	const score = jaccard * (1 - Math.max(sourceCc, targetCc));
+	return Math.max(epsilon, score);
 }
 //#endregion
 //#region src/ranking/mi/etch.ts
@@ -783,30 +748,14 @@ function span(graph, source, target, config) {
 */
 function etch(graph, source, target, config) {
 	const { epsilon = 1e-10 } = config ?? {};
-	const sourceNeighbours = new Set(graph.neighbours(source));
-	const targetNeighbours = new Set(graph.neighbours(target));
-	sourceNeighbours.delete(target);
-	targetNeighbours.delete(source);
-	const commonNeighbours = [];
-	for (const neighbour of sourceNeighbours) if (targetNeighbours.has(neighbour)) commonNeighbours.push(neighbour);
-	if (commonNeighbours.length < 2) return epsilon;
-	let jointEdges = 0;
-	for (let i = 0; i < commonNeighbours.length; i++) for (let j = i + 1; j < commonNeighbours.length; j++) {
-		const ni = commonNeighbours[i];
-		const nj = commonNeighbours[j];
-		if (ni !== void 0 && nj !== void 0 && graph.getEdge(ni, nj) !== void 0) jointEdges++;
-	}
-	const maxJointEdges = commonNeighbours.length * (commonNeighbours.length - 1) / 2;
-	const jointDensity = maxJointEdges > 0 ? jointEdges / maxJointEdges : 0;
-	let commonEdges = 0;
-	for (const cn of commonNeighbours) {
-		if (graph.getEdge(source, cn) !== void 0) commonEdges++;
-		if (graph.getEdge(target, cn) !== void 0) commonEdges++;
-	}
-	const maxCommonEdges = commonNeighbours.length * 2;
-	const commonDensity = maxCommonEdges > 0 ? commonEdges / maxCommonEdges : 0;
-	const score = jointDensity * .7 + commonDensity * .3;
-	return Math.max(epsilon, Math.min(1, score));
+	const { intersection, union } = require_utils.neighbourOverlap(require_utils.neighbourSet(graph, source, target), require_utils.neighbourSet(graph, target, source));
+	const jaccard = union > 0 ? intersection / union : 0;
+	const edge = graph.getEdge(source, target);
+	if (edge?.type === void 0) return Math.max(epsilon, jaccard);
+	const edgeTypeCount = require_utils.countEdgesOfType(graph, edge.type);
+	if (edgeTypeCount === 0) return Math.max(epsilon, jaccard);
+	const score = jaccard * Math.log(graph.edgeCount / edgeTypeCount);
+	return Math.max(epsilon, score);
 }
 //#endregion
 //#region src/ranking/mi/notch.ts
@@ -815,20 +764,18 @@ function etch(graph, source, target, config) {
 */
 function notch(graph, source, target, config) {
 	const { epsilon = 1e-10 } = config ?? {};
-	const sourceNeighbours = new Set(graph.neighbours(source));
-	const targetNeighbours = new Set(graph.neighbours(target));
-	sourceNeighbours.delete(target);
-	targetNeighbours.delete(source);
-	const sourceDegree = sourceNeighbours.size;
-	const targetDegree = targetNeighbours.size;
-	let intersectionSize = 0;
-	for (const neighbour of sourceNeighbours) if (targetNeighbours.has(neighbour)) intersectionSize++;
-	const minDegree = Math.min(sourceDegree, targetDegree);
-	const overlap = minDegree > 0 ? intersectionSize / minDegree : 0;
-	const maxDegree = Math.max(sourceDegree, targetDegree);
-	const correlation = maxDegree > 0 ? 1 - Math.abs(sourceDegree - targetDegree) / maxDegree : 1;
-	const score = overlap * .6 + correlation * .4;
-	return Math.max(epsilon, Math.min(1, score));
+	const { intersection, union } = require_utils.neighbourOverlap(require_utils.neighbourSet(graph, source, target), require_utils.neighbourSet(graph, target, source));
+	const jaccard = union > 0 ? intersection / union : 0;
+	const sourceNode = graph.getNode(source);
+	const targetNode = graph.getNode(target);
+	if (sourceNode?.type === void 0 || targetNode?.type === void 0) return Math.max(epsilon, jaccard);
+	const sourceTypeCount = require_utils.countNodesOfType(graph, sourceNode.type);
+	const targetTypeCount = require_utils.countNodesOfType(graph, targetNode.type);
+	if (sourceTypeCount === 0 || targetTypeCount === 0) return Math.max(epsilon, jaccard);
+	const sourceRarity = Math.log(graph.nodeCount / sourceTypeCount);
+	const targetRarity = Math.log(graph.nodeCount / targetTypeCount);
+	const score = jaccard * sourceRarity * targetRarity;
+	return Math.max(epsilon, score);
 }
 //#endregion
 //#region src/ranking/mi/adaptive.ts
@@ -836,7 +783,7 @@ function notch(graph, source, target, config) {
 * Compute unified adaptive MI between two connected nodes.
 *
 * Combines structural, degree, and overlap signals with
-* adaptive weighting based on graph density.
+* configurable weighting.
 *
 * @param graph - Source graph
 * @param source - Source node ID
@@ -851,17 +798,13 @@ function adaptive(graph, source, target, config) {
 		epsilon,
 		normalise: true
 	});
-	const sourceNeighbours = new Set(graph.neighbours(source));
-	const targetNeighbours = new Set(graph.neighbours(target));
-	sourceNeighbours.delete(target);
-	targetNeighbours.delete(source);
-	const sourceDegree = sourceNeighbours.size;
-	const targetDegree = targetNeighbours.size;
+	const sourceNeighbours = require_utils.neighbourSet(graph, source, target);
+	const targetNeighbours = require_utils.neighbourSet(graph, target, source);
 	let overlap;
-	if (sourceDegree > 0 && targetDegree > 0) {
-		let commonCount = 0;
-		for (const n of sourceNeighbours) if (targetNeighbours.has(n)) commonCount++;
-		overlap = commonCount / Math.min(sourceDegree, targetDegree);
+	if (sourceNeighbours.size > 0 && targetNeighbours.size > 0) {
+		const { intersection } = require_utils.neighbourOverlap(sourceNeighbours, targetNeighbours);
+		const minDegree = Math.min(sourceNeighbours.size, targetNeighbours.size);
+		overlap = minDegree > 0 ? intersection / minDegree : epsilon;
 	} else overlap = epsilon;
 	const totalWeight = structuralWeight + degreeWeight + overlapWeight;
 	const score = (structuralWeight * structural + degreeWeight * degreeComponent + overlapWeight * overlap) / totalWeight;
@@ -2238,6 +2181,8 @@ exports.bfs = require_traversal.bfs;
 exports.bfsWithPath = require_traversal.bfsWithPath;
 exports.communicability = communicability;
 exports.computeTrussNumbers = computeTrussNumbers;
+exports.countEdgesOfType = require_utils.countEdgesOfType;
+exports.countNodesOfType = require_utils.countNodesOfType;
 exports.createGPUContext = require_gpu.createGPUContext;
 exports.createResultBuffer = require_gpu.createResultBuffer;
 exports.csrToGPUBuffers = require_gpu.csrToGPUBuffers;
@@ -2271,6 +2216,9 @@ exports.localClusteringCoefficient = require_utils.localClusteringCoefficient;
 exports.localTypeEntropy = require_utils.localTypeEntropy;
 exports.maze = maze;
 exports.miniBatchKMeans = require_kmeans.miniBatchKMeans;
+exports.neighbourIntersection = require_utils.neighbourIntersection;
+exports.neighbourOverlap = require_utils.neighbourOverlap;
+exports.neighbourSet = require_utils.neighbourSet;
 exports.normaliseFeatures = require_kmeans.normaliseFeatures;
 exports.zScoreNormalise = require_kmeans.normaliseFeatures;
 exports.normalisedEntropy = require_utils.normalisedEntropy;