graphwise 1.3.2 → 1.4.0

package/dist/index/index.js

@@ -235,7 +235,7 @@ function emptyResult(algorithm, startTime) {
 */
 function dome(graph, seeds, config) {
 	const domePriority = (nodeId, context) => {
-		return graph.degree(nodeId);
+		return context.degree;
 	};
 	return base(graph, seeds, {
 		...config,
@@ -247,7 +247,7 @@ function dome(graph, seeds, config) {
 */
 function domeHighDegree(graph, seeds, config) {
 	const domePriority = (nodeId, context) => {
-		return -graph.degree(nodeId);
+		return -context.degree;
 	};
 	return base(graph, seeds, {
 		...config,
@@ -256,23 +256,26 @@ function domeHighDegree(graph, seeds, config) {
 }
 //#endregion
 //#region src/expansion/edge.ts
+var EPSILON$1 = 1e-10;
 /**
-* EDGE priority function.
-*
-* Priority = degree(source) + degree(target)
-* Lower values = higher priority (explored first)
+* Priority function using local type entropy.
+* Lower values = higher priority (expanded first).
 */
 function edgePriority(nodeId, context) {
 	const graph = context.graph;
-	let totalDegree = context.degree;
-	for (const neighbour of graph.neighbours(nodeId)) totalDegree += graph.degree(neighbour);
-	return totalDegree;
+	const neighbours = graph.neighbours(nodeId);
+	const neighbourTypes = [];
+	for (const neighbour of neighbours) {
+		const node = graph.getNode(neighbour);
+		neighbourTypes.push(node?.type ?? "default");
+	}
+	return 1 / (localTypeEntropy(neighbourTypes) + EPSILON$1) * Math.log(context.degree + 1);
 }
 /**
-* Run EDGE expansion algorithm.
+* Run EDGE expansion (Entropy-Driven Graph Expansion).
 *
-* Expands from seeds prioritising low-degree edges first.
-* Useful for avoiding hubs and exploring sparse regions.
+* Discovers paths by prioritising nodes with diverse neighbour types,
+* deferring nodes with homogeneous neighbourhoods.
 *
 * @param graph - Source graph
 * @param seeds - Seed nodes for expansion
@@ -286,6 +289,123 @@ function edge(graph, seeds, config) {
 	});
 }
 //#endregion
+//#region src/expansion/hae.ts
+var EPSILON = 1e-10;
+/**
+* Default type mapper - uses node.type property.
+*/
+function defaultTypeMapper(node) {
+	return node.type ?? "default";
+}
+/**
+* Create a priority function using the given type mapper.
+*/
+function createHAEPriority(typeMapper) {
+	return function haePriority(nodeId, context) {
+		const graph = context.graph;
+		const neighbours = graph.neighbours(nodeId);
+		const neighbourTypes = [];
+		for (const neighbour of neighbours) {
+			const node = graph.getNode(neighbour);
+			if (node !== void 0) neighbourTypes.push(typeMapper(node));
+		}
+		return 1 / (localTypeEntropy(neighbourTypes) + EPSILON) * Math.log(context.degree + 1);
+	};
+}
+/**
+* Run HAE expansion (Heterogeneity-Aware Expansion).
+*
+* Discovers paths by prioritising nodes with diverse neighbour types,
+* using a custom type mapper for flexible type extraction.
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - HAE configuration with optional typeMapper
+* @returns Expansion result with discovered paths
+*/
+function hae(graph, seeds, config) {
+	const typeMapper = config?.typeMapper ?? defaultTypeMapper;
+	return base(graph, seeds, {
+		...config,
+		priority: createHAEPriority(typeMapper)
+	});
+}
+//#endregion
+//#region src/expansion/pipe.ts
+/**
+* Priority function using path potential.
+* Lower values = higher priority (expanded first).
+*
+* Path potential measures how many of a node's neighbours have been
+* visited by OTHER frontiers (not the current frontier).
+*/
+function pipePriority(nodeId, context) {
+	const graph = context.graph;
+	const neighbours = new Set(graph.neighbours(nodeId));
+	let pathPotential = 0;
+	for (const [visitedId, frontierIdx] of context.visitedByFrontier) if (frontierIdx !== context.frontierIndex && neighbours.has(visitedId)) pathPotential++;
+	return context.degree / (1 + pathPotential);
+}
+/**
+* Run PIPE expansion (Path-Potential Informed Priority Expansion).
+*
+* Discovers paths by prioritising nodes that bridge multiple frontiers,
+* identifying connecting points between seed regions.
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - Expansion configuration
+* @returns Expansion result with discovered paths
+*/
+function pipe(graph, seeds, config) {
+	return base(graph, seeds, {
+		...config,
+		priority: pipePriority
+	});
+}
+//#endregion
+//#region src/expansion/sage.ts
+/**
+* Run SAGE expansion algorithm.
+*
+* Salience-aware multi-frontier expansion with two phases:
+* - Phase 1: Degree-based priority (early exploration)
+* - Phase 2: Salience feedback (path-aware frontier steering)
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - Expansion configuration
+* @returns Expansion result with discovered paths
+*/
+function sage(graph, seeds, config) {
+	const salienceCounts = /* @__PURE__ */ new Map();
+	let inPhase2 = false;
+	let lastPathCount = 0;
+	/**
+	* SAGE priority function with phase transition logic.
+	*/
+	function sagePriority(nodeId, context) {
+		const pathCount = context.discoveredPaths.length;
+		if (pathCount > 0 && !inPhase2) {
+			inPhase2 = true;
+			for (const path of context.discoveredPaths) for (const node of path.nodes) salienceCounts.set(node, (salienceCounts.get(node) ?? 0) + 1);
+		}
+		if (pathCount > lastPathCount) {
+			for (let i = lastPathCount; i < pathCount; i++) {
+				const path = context.discoveredPaths[i];
+				if (path !== void 0) for (const node of path.nodes) salienceCounts.set(node, (salienceCounts.get(node) ?? 0) + 1);
+			}
+			lastPathCount = pathCount;
+		}
+		if (!inPhase2) return Math.log(context.degree + 1);
+		return -((salienceCounts.get(nodeId) ?? 0) * 1e3 - context.degree);
+	}
+	return base(graph, seeds, {
+		...config,
+		priority: sagePriority
+	});
+}
+//#endregion
 //#region src/ranking/mi/jaccard.ts
 /**
 * Compute Jaccard similarity between neighbourhoods of two nodes.
@@ -304,14 +424,133 @@ function jaccard(graph, source, target, config) {
 	return Math.max(epsilon, score);
 }
 //#endregion
-//#region src/expansion/hae.ts
+//#region src/expansion/reach.ts
 /**
-* HAE priority function.
+* Run REACH expansion algorithm.
+*
+* Mutual information-aware multi-frontier expansion with two phases:
+* - Phase 1: Degree-based priority (early exploration)
+* - Phase 2: Structural similarity feedback (MI-guided frontier steering)
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - Expansion configuration
+* @returns Expansion result with discovered paths
+*/
+function reach(graph, seeds, config) {
+	let inPhase2 = false;
+	/**
+	* REACH priority function with MI estimation.
+	*/
+	function reachPriority(nodeId, context) {
+		if (context.discoveredPaths.length > 0 && !inPhase2) inPhase2 = true;
+		if (!inPhase2) return Math.log(context.degree + 1);
+		let totalMI = 0;
+		let endpointCount = 0;
+		for (const path of context.discoveredPaths) {
+			const fromNodeId = path.fromSeed.id;
+			const toNodeId = path.toSeed.id;
+			totalMI += jaccard(graph, nodeId, fromNodeId);
+			totalMI += jaccard(graph, nodeId, toNodeId);
+			endpointCount += 2;
+		}
+		const miHat = endpointCount > 0 ? totalMI / endpointCount : 0;
+		return Math.log(context.degree + 1) * (1 - miHat);
+	}
+	return base(graph, seeds, {
+		...config,
+		priority: reachPriority
+	});
+}
+//#endregion
+//#region src/expansion/maze.ts
+/** Default threshold for switching to phase 2 (after M paths) */
+var DEFAULT_PHASE2_THRESHOLD = 1;
+/** Salience weighting factor */
+var SALIENCE_WEIGHT = 1e3;
+/**
+* Run MAZE expansion algorithm.
+*
+* Multi-phase expansion combining path potential and salience with
+* adaptive frontier steering.
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - Expansion configuration
+* @returns Expansion result with discovered paths
+*/
+function maze(graph, seeds, config) {
+	const salienceCounts = /* @__PURE__ */ new Map();
+	let inPhase2 = false;
+	let lastPathCount = 0;
+	/**
+	* MAZE priority function with path potential and salience feedback.
+	*/
+	function mazePriority(nodeId, context) {
+		const pathCount = context.discoveredPaths.length;
+		if (pathCount >= DEFAULT_PHASE2_THRESHOLD && !inPhase2) {
+			inPhase2 = true;
+			for (const path of context.discoveredPaths) for (const node of path.nodes) salienceCounts.set(node, (salienceCounts.get(node) ?? 0) + 1);
+		}
+		if (inPhase2 && pathCount > lastPathCount) {
+			for (let i = lastPathCount; i < pathCount; i++) {
+				const path = context.discoveredPaths[i];
+				if (path !== void 0) for (const node of path.nodes) salienceCounts.set(node, (salienceCounts.get(node) ?? 0) + 1);
+			}
+			lastPathCount = pathCount;
+		}
+		const nodeNeighbours = new Set(graph.neighbours(nodeId));
+		let pathPotential = 0;
+		for (const [visitedId, frontierIdx] of context.visitedByFrontier) if (frontierIdx !== context.frontierIndex && nodeNeighbours.has(visitedId)) pathPotential++;
+		if (!inPhase2) return context.degree / (1 + pathPotential);
+		const salience = salienceCounts.get(nodeId) ?? 0;
+		return context.degree / (1 + pathPotential) * (1 / (1 + SALIENCE_WEIGHT * salience));
+	}
+	return base(graph, seeds, {
+		...config,
+		priority: mazePriority
+	});
+}
+//#endregion
+//#region src/expansion/tide.ts
+/**
+* TIDE priority function.
+*
+* Priority = degree(source) + degree(target)
+* Lower values = higher priority (explored first)
+*/
+function tidePriority(nodeId, context) {
+	const graph = context.graph;
+	let totalDegree = context.degree;
+	for (const neighbour of graph.neighbours(nodeId)) totalDegree += graph.degree(neighbour);
+	return totalDegree;
+}
+/**
+* Run TIDE expansion algorithm.
+*
+* Expands from seeds prioritising low-degree edges first.
+* Useful for avoiding hubs and exploring sparse regions.
+*
+* @param graph - Source graph
+* @param seeds - Seed nodes for expansion
+* @param config - Expansion configuration
+* @returns Expansion result with discovered paths
+*/
+function tide(graph, seeds, config) {
+	return base(graph, seeds, {
+		...config,
+		priority: tidePriority
+	});
+}
+//#endregion
+//#region src/expansion/lace.ts
+/**
+* LACE priority function.
 *
 * Priority = 1 - MI(source, neighbour)
 * Higher MI = lower priority value = explored first
 */
-function haePriority(nodeId, context, mi) {
+function lacePriority(nodeId, context, mi) {
 	const graph = context.graph;
 	const frontierIndex = context.frontierIndex;
 	let maxMi = 0;
@@ -326,7 +565,7 @@ function haePriority(nodeId, context, mi) {
 	return 1 - (count > 0 ? totalMi / count : 0);
 }
 /**
-* Run HAE expansion algorithm.
+* Run LACE expansion algorithm.
 *
 * Expands from seeds prioritising high-MI edges.
 * Useful for finding paths with strong semantic associations.
@@ -336,16 +575,16 @@ function haePriority(nodeId, context, mi) {
 * @param config - Expansion configuration with MI function
 * @returns Expansion result with discovered paths
 */
-function hae(graph, seeds, config) {
+function lace(graph, seeds, config) {
 	const { mi = jaccard, ...restConfig } = config ?? {};
-	const priority = (nodeId, context) => haePriority(nodeId, context, mi);
+	const priority = (nodeId, context) => lacePriority(nodeId, context, mi);
 	return base(graph, seeds, {
 		...restConfig,
 		priority
 	});
 }
 //#endregion
-//#region src/expansion/pipe.ts
+//#region src/expansion/warp.ts
 /**
 * PIPE priority function.
 *
@@ -353,7 +592,7 @@ function hae(graph, seeds, config) {
 * Bridge score = neighbourhood overlap with other frontiers
 * Higher bridge score = more likely to be on paths = explored first
 */
-function pipePriority(nodeId, context) {
+function warpPriority(nodeId, context) {
 	const graph = context.graph;
 	const currentFrontier = context.frontierIndex;
 	const nodeNeighbours = new Set(graph.neighbours(nodeId));
@@ -363,7 +602,7 @@ function pipePriority(nodeId, context) {
 	return 1 / (1 + bridgeScore);
 }
 /**
-* Run PIPE expansion algorithm.
+* Run WARP expansion algorithm.
 *
 * Expands from seeds prioritising bridge nodes.
 * Useful for finding paths through structurally important nodes.
@@ -373,14 +612,14 @@ function pipePriority(nodeId, context) {
 * @param config - Expansion configuration
 * @returns Expansion result with discovered paths
 */
-function pipe(graph, seeds, config) {
+function warp(graph, seeds, config) {
 	return base(graph, seeds, {
 		...config,
-		priority: pipePriority
+		priority: warpPriority
 	});
 }
 //#endregion
-//#region src/expansion/sage.ts
+//#region src/expansion/fuse.ts
 /**
 * SAGE priority function.
 *
@@ -388,7 +627,7 @@ function pipe(graph, seeds, config) {
 * Priority = (1 - w) * degree + w * (1 - avg_salience)
 * Lower values = higher priority
 */
-function sagePriority(nodeId, context, mi, salienceWeight) {
+function fusePriority(nodeId, context, mi, salienceWeight) {
 	const graph = context.graph;
 	const degree = context.degree;
 	const frontierIndex = context.frontierIndex;
@@ -402,7 +641,7 @@ function sagePriority(nodeId, context, mi, salienceWeight) {
 	return (1 - salienceWeight) * degree + salienceWeight * (1 - avgSalience);
 }
 /**
-* Run SAGE expansion algorithm.
+* Run FUSE expansion algorithm.
 *
 * Combines structural exploration with semantic salience.
 * Useful for finding paths that are both short and semantically meaningful.
@@ -412,22 +651,22 @@ function sagePriority(nodeId, context, mi, salienceWeight) {
 * @param config - Expansion configuration with MI function
 * @returns Expansion result with discovered paths
 */
-function sage(graph, seeds, config) {
+function fuse(graph, seeds, config) {
 	const { mi = jaccard, salienceWeight = .5, ...restConfig } = config ?? {};
-	const priority = (nodeId, context) => sagePriority(nodeId, context, mi, salienceWeight);
+	const priority = (nodeId, context) => fusePriority(nodeId, context, mi, salienceWeight);
 	return base(graph, seeds, {
 		...restConfig,
 		priority
 	});
 }
 //#endregion
-//#region src/expansion/reach.ts
+//#region src/expansion/sift.ts
 /**
 * REACH priority function (phase 2).
 *
 * Uses learned MI threshold to prioritise high-MI edges.
 */
-function reachPriority(nodeId, context, mi, miThreshold) {
+function siftPriority(nodeId, context, mi, miThreshold) {
 	const graph = context.graph;
 	const frontierIndex = context.frontierIndex;
 	let totalMi = 0;
@@ -441,7 +680,7 @@ function reachPriority(nodeId, context, mi, miThreshold) {
 	else return context.degree + 100;
 }
 /**
-* Run REACH expansion algorithm.
+* Run SIFT expansion algorithm.
 *
 * Two-phase adaptive expansion that learns MI thresholds
 * from initial sampling, then uses them for guided expansion.
@@ -451,16 +690,16 @@ function reachPriority(nodeId, context, mi, miThreshold) {
 * @param config - Expansion configuration
 * @returns Expansion result with discovered paths
 */
-function reach(graph, seeds, config) {
+function sift(graph, seeds, config) {
 	const { mi = jaccard, miThreshold = .25, ...restConfig } = config ?? {};
-	const priority = (nodeId, context) => reachPriority(nodeId, context, mi, miThreshold);
+	const priority = (nodeId, context) => siftPriority(nodeId, context, mi, miThreshold);
 	return base(graph, seeds, {
 		...restConfig,
 		priority
 	});
 }
 //#endregion
-//#region src/expansion/maze.ts
+//#region src/expansion/flux.ts
 /**
 * Compute local density around a node.
 */
@@ -495,7 +734,7 @@ function bridgeScore(nodeId, context) {
 * - Low density + low bridge: DOME mode
 * - High bridge score: PIPE mode
 */
-function mazePriority(nodeId, context, densityThreshold, bridgeThreshold) {
+function fluxPriority(nodeId, context, densityThreshold, bridgeThreshold) {
 	const graph = context.graph;
 	const degree = context.degree;
 	const density = localDensity(graph, nodeId);
@@ -506,7 +745,7 @@ function mazePriority(nodeId, context, densityThreshold, bridgeThreshold) {
 	else return degree;
 }
 /**
-* Run MAZE expansion algorithm.
+* Run FLUX expansion algorithm.
 *
 * Adaptively switches between expansion strategies based on
 * local graph structure. Useful for heterogeneous graphs
@@ -517,9 +756,9 @@ function mazePriority(nodeId, context, densityThreshold, bridgeThreshold) {
 * @param config - Expansion configuration
 * @returns Expansion result with discovered paths
 */
-function maze(graph, seeds, config) {
+function flux(graph, seeds, config) {
 	const { densityThreshold = .5, bridgeThreshold = .3, ...restConfig } = config ?? {};
-	const priority = (nodeId, context) => mazePriority(nodeId, context, densityThreshold, bridgeThreshold);
+	const priority = (nodeId, context) => fluxPriority(nodeId, context, densityThreshold, bridgeThreshold);
 	return base(graph, seeds, {
 		...restConfig,
 		priority
@@ -703,8 +942,8 @@ function scale(graph, source, target, config) {
 	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;
+	const possibleEdges = n * (n - 1);
+	const density = possibleEdges > 0 ? (graph.directed ? m : 2 * m) / possibleEdges : 0;
 	if (density === 0) return epsilon;
 	const score = jaccard / density;
 	return Math.max(epsilon, score);
@@ -875,7 +1114,7 @@ function degreeSum(graph, paths, config) {
 	return {
 		paths: scored.map(({ path, score }) => ({
 			...path,
-			score: includeScores ? score / maxScore : score / maxScore
+			score: includeScores ? score / maxScore : score
 		})).sort((a, b) => b.score - a.score),
 		method: "degree-sum"
 	};
@@ -977,7 +1216,7 @@ function jaccardArithmetic(graph, paths, config) {
 	return {
 		paths: scored.map(({ path, score }) => ({
 			...path,
-			score: includeScores ? score / maxScore : score / maxScore
+			score: includeScores ? score / maxScore : score
 		})).sort((a, b) => b.score - a.score),
 		method: "jaccard-arithmetic"
 	};
@@ -2164,6 +2403,6 @@ function filterSubgraph(graph, options) {
 	return result;
 }
 //#endregion
-export { AdjacencyMapGraph, GPUContext, GPUNotAvailableError, PriorityQueue, _computeMean, adamicAdar, adaptive, approximateClusteringCoefficient, assertWebGPUAvailable, base, batchClusteringCoefficients, betweenness, bfs, bfsWithPath, communicability, computeTrussNumbers, countEdgesOfType, countNodesOfType, createGPUContext, createResultBuffer, csrToGPUBuffers, degreeSum, detectWebGPU, dfs, dfsWithPath, dome, domeHighDegree, edge, entropyFromCounts, enumerateMotifs, enumerateMotifsWithInstances, etch, extractEgoNetwork, extractInducedSubgraph, extractKCore, extractKTruss, filterSubgraph, frontierBalanced, getGPUContext, getMotifName, graphToCSR, grasp, hae, isWebGPUAvailable, jaccard, jaccardArithmetic, katz, localClusteringCoefficient, localTypeEntropy, maze, miniBatchKMeans, neighbourIntersection, neighbourOverlap, neighbourSet, normaliseFeatures, normaliseFeatures as zScoreNormalise, normalisedEntropy, notch, pagerank, parse, pipe, randomPriority, randomRanking, reach, readBufferToCPU, resistanceDistance, sage, scale, shannonEntropy, shortest, skew, span, standardBfs, stratified, widestPath };
+export { AdjacencyMapGraph, GPUContext, GPUNotAvailableError, PriorityQueue, _computeMean, adamicAdar, adaptive, approximateClusteringCoefficient, assertWebGPUAvailable, base, batchClusteringCoefficients, betweenness, bfs, bfsWithPath, communicability, computeTrussNumbers, countEdgesOfType, countNodesOfType, createGPUContext, createResultBuffer, csrToGPUBuffers, degreeSum, detectWebGPU, dfs, dfsWithPath, dome, domeHighDegree, edge, entropyFromCounts, enumerateMotifs, enumerateMotifsWithInstances, etch, extractEgoNetwork, extractInducedSubgraph, extractKCore, extractKTruss, filterSubgraph, flux, frontierBalanced, fuse, getGPUContext, getMotifName, graphToCSR, grasp, hae, isWebGPUAvailable, jaccard, jaccardArithmetic, katz, lace, localClusteringCoefficient, localTypeEntropy, maze, miniBatchKMeans, neighbourIntersection, neighbourOverlap, neighbourSet, normaliseFeatures, normaliseFeatures as zScoreNormalise, normalisedEntropy, notch, pagerank, parse, pipe, randomPriority, randomRanking, reach, readBufferToCPU, resistanceDistance, sage, scale, shannonEntropy, shortest, sift, skew, span, standardBfs, stratified, tide, warp, widestPath };
 
 //# sourceMappingURL=index.js.map