@graphty/algorithms 1.2.0 → 1.4.2

package/dist/src/clustering/hierarchical.js

@@ -5,8 +5,39 @@
  * or division (top-down). Useful for understanding multi-scale
  * structure in graphs.
  */
+/**
+ * Convert Graph to adjacency set representation for clustering
+ * @param graph - The input graph to convert
+ * @returns Map of node IDs to sets of neighbor node IDs
+ */
+function graphToAdjacencySet(graph) {
+    const adjacency = new Map();
+    // Initialize all nodes
+    for (const node of graph.nodes()) {
+        adjacency.set(String(node.id), new Set());
+    }
+    // Add edges
+    for (const edge of graph.edges()) {
+        const source = String(edge.source);
+        const target = String(edge.target);
+        const sourceSet = adjacency.get(source);
+        if (sourceSet) {
+            sourceSet.add(target);
+        }
+        // For undirected graphs, add reverse edge
+        if (!graph.isDirected) {
+            const targetSet = adjacency.get(target);
+            if (targetSet) {
+                targetSet.add(source);
+            }
+        }
+    }
+    return adjacency;
+}
 /**
  * Compute distance between two nodes based on graph structure
+ * @param graph - Adjacency map representation of the graph
+ * @param distances - Map to store computed distances between nodes
  */
 function computeGraphDistance(graph, distances) {
     // Use BFS to compute shortest path distances
@@ -23,10 +54,7 @@ function computeGraphDistance(graph, distances) {
             if (neighbors) {
                 for (const neighbor of neighbors) {
                     if (!dist.has(neighbor)) {
-                        const nodeDistance = dist.get(node);
-                        if (nodeDistance !== undefined) {
-                            dist.set(neighbor, nodeDistance + 1);
-                        }
+                        dist.set(neighbor, (dist.get(node) ?? 0) + 1);
                         queue.push(neighbor);
                     }
                 }
@@ -36,46 +64,55 @@ function computeGraphDistance(graph, distances) {
     }
 }
 /**
- * Compute distance between clusters based on linkage method
+ * Compute distance between two clusters based on linkage method
+ * @param cluster1 - First cluster node
+ * @param cluster2 - Second cluster node
+ * @param distances - Precomputed distance matrix between nodes
+ * @param linkage - Linkage method to use for computing cluster distance
+ * @returns The distance between the two clusters
  */
-function clusterDistance(cluster1, cluster2, distances, method) {
-    if (cluster1.size === 0 || cluster2.size === 0) {
-        return Infinity;
-    }
+function clusterDistance(cluster1, cluster2, distances, linkage) {
     const allDistances = [];
-    for (const node1 of cluster1) {
-        for (const node2 of cluster2) {
-            const dist = distances.get(node1)?.get(node2) ?? Infinity;
-            allDistances.push(dist);
+    for (const node1 of cluster1.members) {
+        const node1Distances = distances.get(node1);
+        if (!node1Distances) {
+            continue;
         }
+        for (const node2 of cluster2.members) {
+            const dist = node1Distances.get(node2);
+            if (dist !== undefined) {
+                allDistances.push(dist);
+            }
+        }
+    }
+    if (allDistances.length === 0) {
+        return Infinity;
     }
-    switch (method) {
+    switch (linkage) {
         case "single":
             return Math.min(...allDistances);
         case "complete":
             return Math.max(...allDistances);
         case "average":
             return allDistances.reduce((a, b) => a + b, 0) / allDistances.length;
-        case "ward":
-            // Ward's method minimizes within-cluster variance
-            // For simplicity, we use average here
-            return allDistances.reduce((a, b) => a + b, 0) / allDistances.length;
+        case "ward": {
+            // Simplified Ward's method - minimize within-cluster variance
+            const size1 = cluster1.members.size;
+            const size2 = cluster2.members.size;
+            const avgDist = allDistances.reduce((a, b) => a + b, 0) / allDistances.length;
+            return avgDist * ((size1 * size2) / (size1 + size2));
+        }
         default:
             return Math.min(...allDistances);
     }
 }
 /**
- * Agglomerative hierarchical clustering
- * Builds clusters bottom-up by merging closest pairs
- *
- * @param graph - Undirected graph
- * @param linkage - Linkage method for cluster distance
- * @returns Hierarchical clustering result
- *
- * Time Complexity: O(n³) naive, O(n² log n) with heap
- * Space Complexity: O(n²)
+ * Internal implementation of agglomerative hierarchical clustering
+ * @param graph - Adjacency map representation of the graph
+ * @param linkage - Linkage method for cluster distance computation
+ * @returns Hierarchical clustering result with dendrogram and cluster assignments
  */
-export function hierarchicalClustering(graph, linkage = "single") {
+function hierarchicalClusteringImpl(graph, linkage = "single") {
     const nodes = Array.from(graph.keys());
     const n = nodes.length;
     if (n === 0) {
@@ -101,152 +138,111 @@ export function hierarchicalClustering(graph, linkage = "single") {
     const clusterDistances = new Map();
     // Initialize cluster distances
     for (let i = 0; i < clusters.length; i++) {
-        const clusterI = clusters[i];
-        if (!clusterI) {
+        const cluster1 = clusters[i];
+        if (!cluster1) {
             continue;
         }
-        clusterDistances.set(clusterI.id, new Map());
+        const distMap = new Map();
         for (let j = i + 1; j < clusters.length; j++) {
-            const clusterJ = clusters[j];
-            if (!clusterJ) {
+            const cluster2 = clusters[j];
+            if (!cluster2) {
                 continue;
             }
-            const dist = clusterDistance(clusterI.members, clusterJ.members, distances, linkage);
-            const clusterIDistances = clusterDistances.get(clusterI.id);
-            if (clusterIDistances) {
-                clusterIDistances.set(clusterJ.id, dist);
-            }
+            const dist = clusterDistance(cluster1, cluster2, distances, linkage);
+            distMap.set(cluster2.id, dist);
         }
+        clusterDistances.set(cluster1.id, distMap);
     }
+    // Active clusters
+    const activeClusters = new Set(clusters);
     // Merge clusters until only one remains
-    while (clusters.length > 1) {
+    while (activeClusters.size > 1) {
         // Find closest pair of clusters
         let minDist = Infinity;
-        let merge1 = 0;
-        let merge2 = 0;
-        for (let i = 0; i < clusters.length; i++) {
-            for (let j = i + 1; j < clusters.length; j++) {
-                const clusterI = clusters[i];
-                const clusterJ = clusters[j];
-                if (!clusterI || !clusterJ) {
+        let mergeCluster1 = null;
+        let mergeCluster2 = null;
+        for (const cluster1 of activeClusters) {
+            const distMap = clusterDistances.get(cluster1.id);
+            if (!distMap) {
+                continue;
+            }
+            for (const cluster2 of activeClusters) {
+                if (cluster1.id >= cluster2.id) {
                     continue;
                 }
-                const dist = clusterDistances.get(clusterI.id)?.get(clusterJ.id) ??
-                    clusterDistances.get(clusterJ.id)?.get(clusterI.id) ??
-                    Infinity;
+                const dist = distMap.get(cluster2.id) ?? clusterDistances.get(cluster2.id)?.get(cluster1.id) ?? Infinity;
                 if (dist < minDist) {
                     minDist = dist;
-                    merge1 = i;
-                    merge2 = j;
+                    mergeCluster1 = cluster1;
+                    mergeCluster2 = cluster2;
                 }
             }
         }
-        // Check if we found a valid merge
-        if (minDist === Infinity || merge1 === merge2) {
-            // No more clusters can be merged (disconnected components)
+        if (!mergeCluster1 || !mergeCluster2 || minDist === Infinity) {
+            // No valid merge found - create forest
+            const trees = Array.from(activeClusters);
+            const forestRoot = {
+                id: `forest-${String(clusterCount++)}`,
+                members: new Set(nodes),
+                distance: Infinity,
+                height: Math.max(...trees.map((t) => t.height)) + 1,
+                trees,
+            };
+            dendrogram.push(forestRoot);
+            activeClusters.clear();
+            activeClusters.add(forestRoot);
             break;
         }
         // Create new cluster
-        const cluster1 = clusters[merge1];
-        const cluster2 = clusters[merge2];
-        if (!cluster1 || !cluster2) {
-            continue;
-        }
         const newCluster = {
             id: `cluster-${String(clusterCount++)}`,
-            members: new Set([...cluster1.members, ...cluster2.members]),
-            left: cluster1,
-            right: cluster2,
+            members: new Set([...mergeCluster1.members, ...mergeCluster2.members]),
+            left: mergeCluster1,
+            right: mergeCluster2,
             distance: minDist,
-            height: Math.max(cluster1.height, cluster2.height) + 1,
+            height: Math.max(mergeCluster1.height, mergeCluster2.height) + 1,
         };
         dendrogram.push(newCluster);
-        // Update cluster distances for new cluster
-        clusterDistances.set(newCluster.id, new Map());
-        for (let i = 0; i < clusters.length; i++) {
-            if (i !== merge1 && i !== merge2) {
-                const clusterI = clusters[i];
-                if (!clusterI) {
-                    continue;
-                }
-                const newDist = clusterDistance(newCluster.members, clusterI.members, distances, linkage);
-                const newClusterDistances = clusterDistances.get(newCluster.id);
-                if (newClusterDistances) {
-                    newClusterDistances.set(clusterI.id, newDist);
-                }
+        // Update distances to new cluster
+        const newDistMap = new Map();
+        for (const cluster of activeClusters) {
+            if (cluster.id === mergeCluster1.id || cluster.id === mergeCluster2.id) {
+                continue;
+            }
+            const dist = clusterDistance(newCluster, cluster, distances, linkage);
+            newDistMap.set(cluster.id, dist);
+            // Update reverse direction
+            const clusterDistMap = clusterDistances.get(cluster.id);
+            if (clusterDistMap) {
+                clusterDistMap.set(newCluster.id, dist);
             }
         }
-        // Remove old clusters and their distances
-        clusterDistances.delete(cluster1.id);
-        clusterDistances.delete(cluster2.id);
-        for (const [, dists] of clusterDistances) {
-            dists.delete(cluster1.id);
-            dists.delete(cluster2.id);
+        clusterDistances.set(newCluster.id, newDistMap);
+        // Remove merged clusters
+        activeClusters.delete(mergeCluster1);
+        activeClusters.delete(mergeCluster2);
+        clusterDistances.delete(mergeCluster1.id);
+        clusterDistances.delete(mergeCluster2.id);
+        // Clean up references
+        for (const distMap of clusterDistances.values()) {
+            distMap.delete(mergeCluster1.id);
+            distMap.delete(mergeCluster2.id);
         }
-        // Remove merged clusters and add new one
-        clusters.splice(Math.max(merge1, merge2), 1);
-        clusters.splice(Math.min(merge1, merge2), 1);
-        clusters.push(newCluster);
+        activeClusters.add(newCluster);
     }
-    // Generate clusters at different levels
+    // Root is the last remaining cluster
+    const root = activeClusters.size > 0 ? Array.from(activeClusters)[0] : dendrogram[dendrogram.length - 1];
+    // Generate clusters at different heights
     const clustersByLevel = new Map();
-    function extractClustersAtHeight(node, height, clusters) {
-        if (node.height <= height || !node.left || !node.right) {
-            clusters.push(node.members);
-        }
-        else {
-            extractClustersAtHeight(node.left, height, clusters);
-            extractClustersAtHeight(node.right, height, clusters);
-        }
-    }
-    // Handle the case where we have multiple disconnected components
-    let root;
-    if (clusters.length === 0) {
+    if (!root) {
         return {
             root: { id: "empty", members: new Set(), distance: 0, height: 0 },
             dendrogram: [],
             clusters: new Map(),
         };
     }
-    else if (clusters.length === 1 && clusters[0]) {
-        root = clusters[0];
-    }
-    else {
-        // Create a root that combines all remaining clusters (forest)
-        const allMembers = new Set();
-        let maxHeight = 0;
-        for (const cluster of clusters) {
-            for (const member of cluster.members) {
-                allMembers.add(member);
-            }
-            maxHeight = Math.max(maxHeight, cluster.height);
-        }
-        root = {
-            id: "root-forest",
-            members: allMembers,
-            distance: Infinity,
-            height: maxHeight + 1,
-            // Store references to the individual trees
-            trees: [...clusters],
-        };
-        dendrogram.push(root);
-    }
     for (let h = 0; h <= root.height; h++) {
-        const clustersAtHeight = [];
-        if (clusters.length > 1 && h === root.height) {
-            // At forest root height, return single cluster with all members
-            clustersAtHeight.push(root.members);
-        }
-        else if (clusters.length > 1 && h < root.height) {
-            // For forest, extract from each tree separately
-            for (const tree of clusters) {
-                extractClustersAtHeight(tree, h, clustersAtHeight);
-            }
-        }
-        else {
-            extractClustersAtHeight(root, h, clustersAtHeight);
-        }
-        clustersByLevel.set(h, clustersAtHeight);
+        clustersByLevel.set(h, cutDendrogram(root, h));
     }
     return {
         root,
@@ -255,39 +251,42 @@ export function hierarchicalClustering(graph, linkage = "single") {
     };
 }
 /**
- * Cut dendrogram at specified height to get clusters
+ * Cut dendrogram at specific height to get clusters
+ * @param root - Root node of the dendrogram
+ * @param height - Height at which to cut the dendrogram
+ * @returns Array of sets representing clusters at the specified height
  */
 export function cutDendrogram(root, height) {
     const clusters = [];
     function traverse(node) {
-        // Handle forest root specially
-        if (node.trees) {
-            if (node.height <= height) {
-                // If we're at or below the requested height, return the whole forest as one cluster
-                clusters.push(node.members);
-            }
-            else {
-                // Otherwise, traverse each tree in the forest
+        if (node.height <= height || (!node.left && !node.right)) {
+            clusters.push(node.members);
+        }
+        else {
+            if (node.trees) {
+                // Handle forest nodes
                 for (const tree of node.trees) {
                     traverse(tree);
                 }
             }
-            return;
-        }
-        // Normal binary tree traversal
-        if (node.height <= height || !node.left || !node.right) {
-            clusters.push(node.members);
-        }
-        else {
-            traverse(node.left);
-            traverse(node.right);
+            else {
+                if (node.left) {
+                    traverse(node.left);
+                }
+                if (node.right) {
+                    traverse(node.right);
+                }
+            }
         }
     }
     traverse(root);
     return clusters;
 }
 /**
- * Cut dendrogram to get k clusters
+ * Cut dendrogram to get exactly k clusters
+ * @param root - Root node of the dendrogram
+ * @param k - Target number of clusters
+ * @returns Array of sets representing exactly k clusters
  */
 export function cutDendrogramKClusters(root, k) {
     if (k <= 0) {
@@ -296,7 +295,7 @@ export function cutDendrogramKClusters(root, k) {
     if (k === 1) {
         return [root.members];
     }
-    // Find the height that gives us k clusters
+    // Binary search for the right height
     let low = 0;
     let high = root.height;
     while (low < high) {
@@ -317,9 +316,12 @@ export function cutDendrogramKClusters(root, k) {
 /**
  * Compute modularity-based hierarchical clustering
  * Uses modularity gain to decide merges
+ * @param graph - The input graph to cluster
+ * @returns Hierarchical clustering result with dendrogram and cluster assignments
  */
 export function modularityHierarchicalClustering(graph) {
-    const nodes = Array.from(graph.keys());
+    const adjacencySet = graphToAdjacencySet(graph);
+    const nodes = Array.from(adjacencySet.keys());
     const n = nodes.length;
     if (n === 0) {
         return {
@@ -328,12 +330,15 @@ export function modularityHierarchicalClustering(graph) {
             clusters: new Map(),
         };
     }
-    // Calculate total edges
-    let m = 0;
-    for (const neighbors of graph.values()) {
-        m += neighbors.size;
+    // Compute degrees
+    const degrees = new Map();
+    let totalEdges = 0;
+    for (const [node, neighbors] of adjacencySet) {
+        degrees.set(node, neighbors.size);
+        totalEdges += neighbors.size;
     }
-    m = m / 2; // Each edge counted twice
+    // For undirected graphs
+    totalEdges = totalEdges / 2;
     // Initialize clusters
     const clusters = nodes.map((node, i) => ({
         id: `leaf-${String(i)}`,
@@ -343,83 +348,65 @@ export function modularityHierarchicalClustering(graph) {
     }));
     const dendrogram = [...clusters];
     let clusterCount = n;
-    // Track community assignments
-    const communityMap = new Map();
-    nodes.forEach((node, i) => communityMap.set(node, i));
-    // Compute modularity gain for merging communities
-    function modularityGain(comm1, comm2) {
-        let edgesBetween = 0;
-        let degree1 = 0;
-        let degree2 = 0;
-        for (const node1 of comm1) {
-            const neighbors = graph.get(node1);
-            if (!neighbors) {
-                continue;
-            }
-            degree1 += neighbors.size;
-            for (const neighbor of neighbors) {
-                if (comm2.has(neighbor)) {
-                    edgesBetween++;
-                }
-            }
-        }
-        for (const node2 of comm2) {
-            const node2Neighbors = graph.get(node2);
-            if (node2Neighbors) {
-                degree2 += node2Neighbors.size;
-            }
-        }
-        // Modularity gain formula
-        const gain = (edgesBetween / m) - ((degree1 * degree2) / (4 * m * m));
-        return gain;
-    }
-    // Merge clusters based on modularity
-    while (clusters.length > 1) {
+    // Active clusters
+    const activeClusters = new Set(clusters);
+    // Community assignments
+    const communities = new Map();
+    nodes.forEach((node, i) => communities.set(node, i));
+    // Merge clusters based on modularity gain
+    while (activeClusters.size > 1) {
         let maxGain = -Infinity;
-        let merge1 = 0;
-        let merge2 = 0;
-        for (let i = 0; i < clusters.length; i++) {
-            for (let j = i + 1; j < clusters.length; j++) {
-                const clusterI = clusters[i];
-                const clusterJ = clusters[j];
-                if (!clusterI || !clusterJ) {
+        let mergeCluster1 = null;
+        let mergeCluster2 = null;
+        for (const cluster1 of activeClusters) {
+            for (const cluster2 of activeClusters) {
+                if (cluster1.id >= cluster2.id) {
                     continue;
                 }
-                const gain = modularityGain(clusterI.members, clusterJ.members);
+                // Calculate modularity gain
+                let edgesBetween = 0;
+                let degreeProduct = 0;
+                for (const node1 of cluster1.members) {
+                    const neighbors = adjacencySet.get(node1);
+                    const degree1 = degrees.get(node1) ?? 0;
+                    for (const node2 of cluster2.members) {
+                        if (neighbors?.has(node2)) {
+                            edgesBetween++;
+                        }
+                        const degree2 = degrees.get(node2) ?? 0;
+                        degreeProduct += degree1 * degree2;
+                    }
+                }
+                const gain = edgesBetween / totalEdges - degreeProduct / (4 * totalEdges * totalEdges);
                 if (gain > maxGain) {
                     maxGain = gain;
-                    merge1 = i;
-                    merge2 = j;
+                    mergeCluster1 = cluster1;
+                    mergeCluster2 = cluster2;
                 }
             }
         }
-        // Create new cluster
-        const cluster1 = clusters[merge1];
-        const cluster2 = clusters[merge2];
-        if (!cluster1 || !cluster2) {
-            continue;
+        if (!mergeCluster1 || !mergeCluster2) {
+            break;
         }
+        // Create new cluster
         const newCluster = {
             id: `cluster-${String(clusterCount++)}`,
-            members: new Set([...cluster1.members, ...cluster2.members]),
-            left: cluster1,
-            right: cluster2,
+            members: new Set([...mergeCluster1.members, ...mergeCluster2.members]),
+            left: mergeCluster1,
+            right: mergeCluster2,
             distance: -maxGain, // Use negative gain as distance
-            height: Math.max(cluster1.height, cluster2.height) + 1,
+            height: Math.max(mergeCluster1.height, mergeCluster2.height) + 1,
         };
         dendrogram.push(newCluster);
-        // Update community assignments
-        for (const node of newCluster.members) {
-            communityMap.set(node, clusterCount - 1);
-        }
-        // Remove merged clusters
-        clusters.splice(Math.max(merge1, merge2), 1);
-        clusters.splice(Math.min(merge1, merge2), 1);
-        clusters.push(newCluster);
+        // Remove old and add new
+        activeClusters.delete(mergeCluster1);
+        activeClusters.delete(mergeCluster2);
+        activeClusters.add(newCluster);
     }
-    // Generate clusters at different levels
+    // Root is the last remaining cluster
+    const root = Array.from(activeClusters)[0] ?? dendrogram[dendrogram.length - 1];
+    // Generate clusters at different heights
     const clustersByLevel = new Map();
-    const root = clusters[0];
     if (!root) {
         return {
             root: { id: "empty", members: new Set(), distance: 0, height: 0 },
@@ -436,4 +423,19 @@ export function modularityHierarchicalClustering(graph) {
         clusters: clustersByLevel,
     };
 }
+/**
+ * Agglomerative hierarchical clustering
+ * Builds clusters bottom-up by merging closest pairs
+ * @param graph - Undirected graph - accepts Graph class or Map<T, Set<T>>
+ * @param linkage - Linkage method for cluster distance
+ * @returns Hierarchical clustering result
+ *
+ * Time Complexity: O(n³) naive, O(n² log n) with heap
+ * Space Complexity: O(n²)
+ */
+export function hierarchicalClustering(graph, linkage = "single") {
+    // Convert Graph to adjacency set representation
+    const adjacencySet = graphToAdjacencySet(graph);
+    return hierarchicalClusteringImpl(adjacencySet, linkage);
+}
 //# sourceMappingURL=hierarchical.js.map