@intact-ebi/cytoscape-lumina 1.0.1 → 1.1.0

package/README.md

@@ -107,6 +107,8 @@ Options are split by who uses them:
 | --- | --- | --- |
 | `weightExponent` | `2` | Stress weights are `w_ij = 1 / d_ij ^ weightExponent`; `2` is classic stress majorization. |
 
+Stress shortest paths use weighted Dijkstra. Computed edge lengths (`idealLength` plus both virtual-node radii) must be finite and non-negative; invalid lengths throw a `RangeError`.
+
 ### Structure detection
 
 | Option | Default | Description |
@@ -143,7 +145,7 @@ Set `stepByStep: true`, keep a reference to the layout, and run it:
 const layout = cy.layout({ name: 'lumina', stepByStep: true });
 layout.run();
 
-layout.listSteps();   // print and return all captured steps
+const steps = layout.listSteps(); // return all captured steps
 layout.goToStep(3);   // jump to a step
 layout.nextStep();
 layout.prevStep();

package/dist/lumina-layout.js

@@ -1,3 +1,4 @@
+import FastPriorityQueue from 'fastpriorityqueue';
 export const DEFAULT_PARAMS = {
     layoutAlgorithm: 'stress',
     // shared solver
@@ -110,6 +111,52 @@ class VEdge {
         };
     }
 }
+/** Dense stress distances from repeated weighted Dijkstra. */
+function computeStressDistances(nodes, edges, idealLength) {
+    const numNodes = nodes.length;
+    const nodeIndexMap = new Map();
+    nodes.forEach((node, index) => nodeIndexMap.set(node.id, index));
+    const adjacency = Array.from({ length: numNodes }, () => []);
+    edges.forEach(edge => {
+        if (!edge.source || !edge.target) {
+            return;
+        }
+        const source = nodeIndexMap.get(edge.source.id);
+        const target = nodeIndexMap.get(edge.target.id);
+        if (source === undefined || target === undefined) {
+            return;
+        }
+        const distance = idealLength + edge.source.radius + edge.target.radius;
+        if (distance < 0 || !Number.isFinite(distance)) {
+            throw new RangeError('cytoscape-lumina: stress edge lengths must be finite and non-negative');
+        }
+        adjacency[source].push({ node: target, distance });
+        adjacency[target].push({ node: source, distance });
+    });
+    const distances = Array.from({ length: numNodes }, (_, index) => {
+        const row = new Array(numNodes).fill(Infinity);
+        row[index] = 0;
+        return row;
+    });
+    for (let source = 0; source < numNodes; source++) {
+        const row = distances[source];
+        const heap = new FastPriorityQueue((a, b) => a.distance < b.distance || (a.distance === b.distance && a.node < b.node));
+        heap.add({ node: source, distance: 0 });
+        let current;
+        while ((current = heap.poll()) !== undefined) {
+            if (current.distance !== row[current.node])
+                continue;
+            for (const neighbor of adjacency[current.node]) {
+                const candidate = current.distance + neighbor.distance;
+                if (candidate < row[neighbor.node]) {
+                    row[neighbor.node] = candidate;
+                    heap.add({ node: neighbor.node, distance: candidate });
+                }
+            }
+        }
+    }
+    return distances;
+}
 /**
  * Register this layout as a Cytoscape.js layout extension.
  *
@@ -203,18 +250,8 @@ LuminaLayout.prototype.captureStep = function (stepName, description, metadata)
     };
     this.steps.push(step);
     this.currentStepIndex = this.steps.length - 1;
-    console.log(`[Step ${step.stepNumber}] ${stepName}: ${description}`);
+    console.debug(`[Step ${step.stepNumber}] ${stepName}: ${description}`);
 };
-/////////////// Check whether two node arrays are identical, ignoring order
-function areNodesEqual(arr1, arr2) {
-    // 1. Different lengths mean they are definitely different
-    if (arr1.length !== arr2.length)
-        return false;
-    // 2. Extract all IDs and put them into a Set
-    const ids1 = new Set(arr1.map((node) => node.id()));
-    // 3. Check whether every ID in arr2 exists in the Set
-    return arr2.every(node => ids1.has(node.id()));
-}
 ////////////////sum length of all edges ////////////////
 function totalEdgeLength(edges) {
     let total = 0;
@@ -293,6 +330,17 @@ function layoutRectangular(nodes, center, dirVector, rowSpacing = 60, colSpacing
 }
 LuminaLayout.prototype.identifyStructures = function (nodes) {
     const params = this.params;
+    // Topology stays fixed during detection; structure markers are filtered dynamically.
+    const neighborhoodCache = new Map();
+    const neighborsOf = (node) => {
+        const id = node.id();
+        let neighbors = neighborhoodCache.get(id);
+        if (neighbors === undefined) {
+            neighbors = node.neighborhood().nodes();
+            neighborhoodCache.set(id, neighbors);
+        }
+        return neighbors;
+    };
     // 0. Reset all markers
     nodes.data('structType', 'Normal');
     // nodes.data('structColor', '#999999');
@@ -304,7 +352,7 @@ LuminaLayout.prototype.identifyStructures = function (nodes) {
     ///////////////////////////// 2. detecting Cycle - by DFS algorithm /////////////////
     const allCycles = []; // each sub-array represents an independent cycle
     if (1) {
-        const normalNodes = nodes.toArray().filter((n) => n.data('structType') === 'Normal' && n.neighborhood().nodes().length >= 2);
+        const normalNodes = nodes.toArray().filter((n) => n.data('structType') === 'Normal' && neighborsOf(n).length >= 2);
         const seenCycles = new Set();
         // To avoid duplicate cycles (like A-B-C and B-C-A), we sort and stringify for a check
         normalNodes.forEach((startNode, startIndex) => {
@@ -312,7 +360,7 @@ LuminaLayout.prototype.identifyStructures = function (nodes) {
             // This is a massive optimization to prevent finding the same cycle N times
             const startId = startNode.id();
             const findCycles = (u, parent, path) => {
-                const neighbors = u.neighborhood().nodes().toArray().filter((n) => n.data('structType') === 'Normal');
+                const neighbors = neighborsOf(u).toArray().filter((n) => n.data('structType') === 'Normal');
                 if (neighbors.length < 8) { // If a node has too many neighbors, it is unlikely to be part of a cycle; this mainly improves efficiency and prevents the search from getting stuck here
                     for (const v of neighbors) {
                         const vId = v.id();
@@ -393,11 +441,10 @@ LuminaLayout.prototype.identifyStructures = function (nodes) {
         });
         circleIndex++;
     });
-    console.log("num of cycles: ", filteredCycles.length);
     const chains = [];
     const processedNodeIds = new Set(); // avoid processing nodes more than once
     // 2. Find all leaf nodes (Normal type with degree 1)
-    const leafNodes = nodes.filter((n) => n.data('structType') === 'Normal' && n.neighborhood().nodes().length === 1);
+    const leafNodes = nodes.filter((n) => n.data('structType') === 'Normal' && neighborsOf(n).length === 1);
     let chainId = 0;
     leafNodes.forEach((leaf) => {
         if (processedNodeIds.has(leaf.id()))
@@ -410,8 +457,7 @@ LuminaLayout.prototype.identifyStructures = function (nodes) {
             currentChainNodes.push(currentNode);
             processedNodeIds.add(currentNode.id());
             // Find the next neighbor
-            const neighbors = currentNode
-                .neighborhood('node')
+            const neighbors = neighborsOf(currentNode)
                 .filter((n) => n.id() !== currentNode.id() &&
                 n.data('structType') === 'Normal' &&
                 !processedNodeIds.has(n.id()));
@@ -420,8 +466,7 @@ LuminaLayout.prototype.identifyStructures = function (nodes) {
             // 2. The neighbor must not have a high degree (if degree > 2, a branching point has been reached and the chain ends)
             if (neighbors.length === 1) {
                 const nextNode = neighbors[0];
-                const nextNodeNeighborCount = nextNode
-                    .neighborhood('node')
+                const nextNodeNeighborCount = neighborsOf(nextNode)
                     .filter((n) => n.id() !== nextNode.id())
                     .length;
                 if (nextNodeNeighborCount > 2) {
@@ -475,11 +520,11 @@ LuminaLayout.prototype.identifyStructures = function (nodes) {
     ///////////////////////////////// Star structure ///////////
     let starIndex = 0;
     nodes.forEach((node) => {
-        const neighbors = node.neighborhood().nodes();
+        const neighbors = neighborsOf(node);
         // Number of distinct neighbors
         const neighborCount = neighbors.length;
         // Check whether the neighbors consist only of distinct neighbor nodes
-        const leafNeighbors = neighbors.filter((n) => n.neighborhood().nodes().length === 1);
+        const leafNeighbors = neighbors.filter((n) => neighborsOf(n).length === 1);
         if (leafNeighbors.length >= params.minStarLeaves && neighborCount >= params.minStarLeaves) {
             if (node.data('structType') !== 'Cycle' && node.data('structType') !== 'Chain') {
                 const groupId = 'Star_' + starIndex;
@@ -508,56 +553,57 @@ LuminaLayout.prototype.identifyStructures = function (nodes) {
         }
     });
     /////////////////////////////// Find parallel/diamond structures ///////////////////////////////////
-    // let diamonds = [];
-    let parallelId = 0;
-    // Whether any two nodes have common neighbors
-    for (let i = 0; i < nodes.length; i++) {
-        let nodeVecParallel = [];
-        const u = nodes[i];
-        const u1 = u.neighborhood().nodes();
-        if (u.data('structType') === 'Normal') {
-            for (let j = 0; j < nodes.length; j++) {
-                if (i === j)
-                    continue;
-                const v = nodes[j];
-                if (v.data('structType') === 'Normal') {
-                    const v1 = v.neighborhood().nodes();
-                    if (areNodesEqual(v1, u1) && v1.length >= params.minParallelNeighbors && u1.length >= params.minParallelNeighbors) {
-                        if (nodeVecParallel.length === 0) {
-                            nodeVecParallel.push(u.id());
-                        }
-                        nodeVecParallel.push(v.id());
-                    }
-                }
-            }
+    const nodesById = new Map();
+    const parallelGroups = new Map();
+    nodes.forEach((node) => {
+        nodesById.set(node.id(), node);
+        if (node.data("structType") !== "Normal") {
+            return;
         }
-        if (nodeVecParallel.length >= 2) {
-            nodeVecParallel.forEach(v => {
-                nodes.forEach((node) => {
-                    if (node.id() == v) {
-                        node.addClass('substructure-parallel');
-                        node.data('structType', 'Parallel');
-                        // node.data('structColor', '#50C878');
-                        node.data('groupId', 'Parallel' + parallelId);
-                        node.data('structs', {
-                            ...node.data('structs'), Parallel: {
-                                color: '#50C878', groupId: `Parallel_${parallelId}`
-                            }
-                        });
-                    }
-                });
-            });
-            u1.forEach((v1) => {
-                nodes.forEach((node) => {
-                    if (node.id() == v1.id()) {
-                        node.data('parallelGroupIdVec', [...node.data('parallelGroupIdVec'), 'Parallel' + parallelId]);
-                    }
-                });
-            });
-            parallelId++;
+        const neighbors = neighborsOf(node);
+        if (!(neighbors.length >= params.minParallelNeighbors)) {
+            return;
+        }
+        // Encode a sorted copy so IDs cannot collide and cached neighbor order stays intact.
+        const signature = JSON.stringify(neighbors.map((neighbor) => neighbor.id()).sort());
+        const group = parallelGroups.get(signature);
+        if (group) {
+            group.push(node);
+        }
+        else {
+            parallelGroups.set(signature, [node]);
         }
+    });
+    // Map insertion order preserves group numbering by the first eligible member.
+    let parallelId = 0;
+    for (const group of parallelGroups.values()) {
+        if (group.length < 2)
+            continue;
+        const groupId = "Parallel" + parallelId;
+        group.forEach((node) => {
+            node.addClass("substructure-parallel");
+            node.data("structType", "Parallel");
+            node.data("groupId", groupId);
+            node.data("structs", {
+                ...node.data("structs"),
+                Parallel: {
+                    color: "#50C878",
+                    groupId: `Parallel_${parallelId}`,
+                },
+            });
+        });
+        neighborsOf(group[0]).forEach((neighbor) => {
+            // Neighborhoods may include nodes outside the supplied collection.
+            const node = nodesById.get(neighbor.id());
+            if (node) {
+                node.data("parallelGroupIdVec", [
+                    ...node.data("parallelGroupIdVec"),
+                    groupId,
+                ]);
+            }
+        });
+        parallelId++;
     }
-    console.log("num of chains: ", chains.length);
 };
 LuminaLayout.prototype.run = function () {
     this.stopped = false;
@@ -583,7 +629,6 @@ LuminaLayout.prototype.run = function () {
     components.forEach((component, index) => {
         this.vnodes = [];
         this.vedges = [];
-        console.log(`independent net: ${index + 1}`);
         // 1. get user defined boundingBox，if not then default cy container
         const bb = this.boundingBox || this.cy.extent();
         const width = bb.x2 - bb.x1;
@@ -612,8 +657,6 @@ LuminaLayout.prototype.run = function () {
                 });
             });
         }
-        console.log("num of nodes: " + nodes.length);
-        console.log("num of edges: " + edgeSet.length);
         // Capture initial state
         this.captureStep('Initial', 'Initial node positions before any layout', {
             nodeCount: nodes.length, edgeCount: edgeSet.length
@@ -1089,6 +1132,7 @@ LuminaLayout.prototype.run = function () {
                 numOfCollision = 0;
                 const padding = params.collisionPadding;
                 let iter = 0;
+                let overlapLimitReached = false;
                 while (colisionFlag) {
                     if (this.stopped) {
                         break;
@@ -1131,12 +1175,17 @@ LuminaLayout.prototype.run = function () {
                     }
                     // [Optimization 3] Safety valve: exit directly if the iteration count becomes too large (typically when nodes are extremely dense)
                     if (numOfCollision > 10000) {
-                        console.warn("avoid dead loop");
+                        overlapLimitReached = true;
                         break;
                     }
-                    // this.captureStep('Anti-collision', 'Eliminate all collisions ' + iter, {iterations});
                 }
-                this.captureStep('Anti-collision', 'Eliminate all collisions', { iterations });
+                this.captureStep("Anti-collision", overlapLimitReached
+                    ? "Overlap removal stopped at safety limit"
+                    : "Eliminate all collisions", {
+                    iterations,
+                    overlapIterations: iter,
+                    overlapLimitReached,
+                });
                 if (1) {
                     numOfCollision = 0;
                     for (let i = 0; i < this.vnodes.length; i++) {
@@ -1169,8 +1218,7 @@ LuminaLayout.prototype.run = function () {
             if (numNodes === 0)
                 return;
             // Index mapping: ID -> array index, for matrix operations
-            const nodeIndexMap = new Map();
-            this.vnodes.forEach((v, i) => nodeIndexMap.set(v.id, i));
+            // The distance helper builds the index alongside its weighted adjacency.
             // Extract the adjacency list for reuse during initialization
             const adj = new Map();
             this.vedges.forEach((e) => {
@@ -1184,34 +1232,10 @@ LuminaLayout.prototype.run = function () {
                 adj.get(e.target.id).push(e.source);
             });
             // -------------------------------------------------------------
-            // [Preprocessing 1] Calculate the shortest-path distance matrix between every pair of nodes in the graph (APSP - Floyd Warshall)
+            // [Preprocessing 1] Calculate all-pairs shortest paths using weighted Dijkstra
             // -------------------------------------------------------------
-            const distMatrix = Array.from({ length: numNodes }, () => new Array(numNodes).fill(Infinity));
+            const distMatrix = computeStressDistances(this.vnodes, this.vedges, idealLength);
             const weightMatrix = Array.from({ length: numNodes }, () => new Array(numNodes).fill(0));
-            for (let i = 0; i < numNodes; i++)
-                distMatrix[i][i] = 0;
-            // Assign the ideal distance baseline based on real edges
-            this.vedges.forEach((e) => {
-                if (!e.source || !e.target)
-                    return;
-                const u = nodeIndexMap.get(e.source.id);
-                const v = nodeIndexMap.get(e.target.id);
-                if (u !== undefined && v !== undefined) {
-                    const idealDist = idealLength + e.source.radius + e.target.radius;
-                    distMatrix[u][v] = Math.min(distMatrix[u][v], idealDist);
-                    distMatrix[v][u] = Math.min(distMatrix[v][u], idealDist);
-                }
-            });
-            // Use Floyd-Warshall to compute shortest paths between all node pairs
-            for (let k = 0; k < numNodes; k++) {
-                for (let i = 0; i < numNodes; i++) {
-                    for (let j = 0; j < numNodes; j++) {
-                        if (distMatrix[i][k] + distMatrix[k][j] < distMatrix[i][j]) {
-                            distMatrix[i][j] = distMatrix[i][k] + distMatrix[k][j];
-                        }
-                    }
-                }
-            }
             // Calculate the weight matrix W_ij = 1 / (d_ij ^ weightExponent)
             for (let i = 0; i < numNodes; i++) {
                 for (let j = 0; j < numNodes; j++) {
@@ -1321,6 +1345,7 @@ LuminaLayout.prototype.run = function () {
                 let numOfCollision = 0;
                 const padding = params.collisionPadding;
                 let overlapIter = 0;
+                let overlapLimitReached = false;
                 while (colisionFlag) {
                     if (this.stopped) {
                         break;
@@ -1354,11 +1379,17 @@ LuminaLayout.prototype.run = function () {
                         }
                     }
                     if (numOfCollision > 10000 || overlapIter > params.maxOverlapIterations) {
-                        console.warn("Avoid dead loop in overlap removal");
+                        overlapLimitReached = true;
                         break;
                     }
                 }
-                this.captureStep('Anti-collision', 'Eliminate all collisions', { iterations });
+                this.captureStep("Anti-collision", overlapLimitReached
+                    ? "Overlap removal stopped at safety limit"
+                    : "Eliminate all collisions", {
+                    iterations,
+                    overlapIterations: overlapIter,
+                    overlapLimitReached,
+                });
             }
             this.captureStep('Virtual Node Layout', 'Stress Majorization layout applied to virtual nodes', { iterations });
         }
@@ -1670,34 +1701,6 @@ LuminaLayout.prototype.run = function () {
             nodes[2].position().y = 90;
         }
         rotateNetworkToMinimumBoundingBox(nodes);
-        if (1) {
-            let maxDis = 0;
-            let maxS = 0;
-            let maxT = 0;
-            let minDist = 10e10;
-            let minS = 0;
-            let minT = 0;
-            let avgDis = 0;
-            edgeSet.forEach((e) => {
-                const s = e.source();
-                const t = e.target();
-                const distance = Math.sqrt(Math.pow(s.position().x - t.position().x, 2) + Math.pow(s.position().y - t.position().y, 2));
-                if (maxDis < distance) {
-                    maxDis = distance;
-                    maxS = s.id();
-                    maxT = t.id();
-                }
-                if (minDist > distance) {
-                    minDist = distance;
-                    minS = s.id();
-                    minT = t.id();
-                }
-                avgDis += distance;
-            });
-            console.log("maxDis:", maxDis, " ", maxS, "->", maxT);
-            console.log("minDist:", minDist, " ", minS, "->", minT);
-            console.log("avgDis:", avgDis / edgeSet.length);
-        }
         const bb2 = nodes.boundingBox();
         networkInfos.push({
             component: component,
@@ -2289,7 +2292,7 @@ LuminaLayout.prototype.goToStep = function (stepIndex) {
     });
     // Visualize virtual nodes if they exist at this step
     this.visualizeVirtualNodes(step);
-    console.log(`[Step ${step.stepNumber}/${this.steps.length - 1}] ${step.stepName}: ${step.description}`);
+    console.debug(`[Step ${step.stepNumber}/${this.steps.length - 1}] ${step.stepName}: ${step.description}`);
     this.cy.fit(null, 50);
     return this;
 };
@@ -2301,7 +2304,7 @@ LuminaLayout.prototype.nextStep = function () {
         return this.goToStep(this.currentStepIndex + 1);
     }
     else {
-        console.log('Already at the last step');
+        console.debug("Already at the last step");
         return this;
     }
 };
@@ -2313,7 +2316,7 @@ LuminaLayout.prototype.prevStep = function () {
         return this.goToStep(this.currentStepIndex - 1);
     }
     else {
-        console.log('Already at the first step');
+        console.debug("Already at the first step");
         return this;
     }
 };
@@ -2322,14 +2325,9 @@ LuminaLayout.prototype.prevStep = function () {
  */
 LuminaLayout.prototype.listSteps = function () {
     if (!this.params.stepByStep || this.steps.length === 0) {
-        console.log('No steps available');
+        console.debug("No steps available");
         return [];
     }
-    console.log(`Total steps: ${this.steps.length}`);
-    this.steps.forEach((step, index) => {
-        const current = index === this.currentStepIndex ? ' ← CURRENT' : '';
-        console.log(`  [${index}] ${step.stepName}: ${step.description}${current}`);
-    });
     return this.steps.map((s) => ({
         stepNumber: s.stepNumber,
         stepName: s.stepName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intact-ebi/cytoscape-lumina",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "LUMINA: a structure-aware Cytoscape.js layout that detects cycles, chains, stars and parallel groups and lays them out with force-directed or stress-majorization solvers.",
   "type": "module",
   "main": "dist/index.js",
@@ -26,8 +26,9 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "tsc && cp demo/favicon.ico dist/favicon.ico && cp demo/index.html dist/index.html && cp node_modules/cytoscape/dist/cytoscape.min.js dist/ && if [ -d demo/data ]; then cp -r demo/data dist/data; fi && touch dist/.nojekyll",
-    "dev": "npm run build && concurrently \"tsc --watch\" \"node watch.cjs\" \"http-server dist -p 8080 -c-1\"",
+    "build": "npm run build:lib && npm run build:browser && cp demo/favicon.ico dist/favicon.ico && cp demo/index.html dist/index.html && cp node_modules/cytoscape/dist/cytoscape.min.js dist/ && if [ -d demo/data ]; then cp -r demo/data dist/data; fi && touch dist/.nojekyll",
+    "build:browser": "esbuild src/index.ts --bundle --format=esm --platform=browser --target=es2020 --external:cytoscape --outfile=dist/lumina-browser.js",
+    "dev": "npm run build && concurrently \"tsc --watch\" \"npm run build:browser -- --watch\" \"node watch.cjs\" \"http-server dist -p 8080 -c-1\"",
     "deploy": "./deploy.sh",
     "build:lib": "tsc",
     "local-publish": "npm run build:lib && yalc push",
@@ -37,6 +38,7 @@
   "devDependencies": {
     "concurrently": "^9.2.4",
     "cytoscape": "^3.33.1",
+    "esbuild": "^0.28.2",
     "gh-pages": "^6.3.0",
     "http-server": "^14.1.1",
     "typescript": "^5.9.3",
@@ -65,5 +67,8 @@
   },
   "allowScripts": {
     "fsevents@2.3.3": true
+  },
+  "dependencies": {
+    "fastpriorityqueue": "^0.8.0"
   }
-}
+}