@intact-ebi/cytoscape-lumina 1.1.0 → 1.2.0

package/README.md

@@ -14,7 +14,7 @@ Written in TypeScript. Registered under the layout name `lumina` (the legacy nam
   - Leaves that don't belong to a chain are placed on a circle around their parent
 - **Two interchangeable solvers** for the virtual-node graph: `force` and `stress`
 - **Multiple connected components** are each laid out independently, rotated to their minimum bounding box, and packed into rows that match the canvas aspect ratio
-- **Compound parents** (`.substructure-group`) are generated for each detected substructure
+- **Optional compound parents** (`.substructure-group`) can be generated for each detected substructure using `createSubstructureGroups`. When enabled, this modifies the `parent` data of nodes belonging to these groups and may affect existing compound-node relationships.
 - **Step-by-step mode** to inspect and replay every stage of the pipeline
 
 ## How it works
@@ -45,6 +45,7 @@ registerLumina(cytoscape);
 
 const cy = cytoscape({ container: document.getElementById('cy'), elements: [/* ... */] });
 
+```ts
 cy.layout({
   name: 'lumina',
   layoutAlgorithm: 'stress',   // 'stress' (default) or 'force'
@@ -57,10 +58,17 @@ cy.layout({
   force: { repulsion: 300, springK: 0.15, useAngularForce: true },
 
   // used only when layoutAlgorithm is 'stress'
-  stress: { weightExponent: 2 }
+  stress: { weightExponent: 2 },
+
+  // create compound parent nodes for detected substructures
+  // Set to false to avoid creating substructure group parents
+  createSubstructureGroups: true
 }).run();
 ```
 
+Set `createSubstructureGroups: false` to disable the creation of compound parent nodes.
+
+
 Registration is idempotent, so it is safe to call more than once (e.g. with hot reload).
 
 ## Options
@@ -135,6 +143,7 @@ Stress shortest paths use weighted Dijkstra. Computed edge lengths (`idealLength
 | `randomizeInitialPositions` | `false` | Randomize node positions inside the bounding box before the layout starts. |
 | `spreadVNodes` | `true` | After solving, scatter real nodes slightly around their virtual node centre. |
 | `substructureLayout` | `false` | When `false` (default), each substructure is arranged internally (circle, rings, grid, ...). When `true`, that step is skipped. |
+| `createSubstructureGroups` | `true` | Whether to create compound parent nodes (`.substructure-group`) for detected substructures. When enabled, the layout modifies the `parent` data of grouped nodes, which may overwrite or alter existing compound-node relationships. Set to `false` to disable compound parent creation. |
 | `stepByStep` | `false` | Record a snapshot after each stage (see below). |
 
 ## Step-by-step debugging
@@ -164,3 +173,5 @@ Each step restores real-node positions and overlays the virtual nodes (transluce
 - Nodes with 8 or more neighbours are skipped during cycle search, for performance.
 - Self-loops and duplicate edges are ignored by the layout.
 - Generated compound parents have the class `substructure-group` and ids of the form `<componentIndex>_<groupId>`; they are removed and regenerated on each run.
+* **Node `parent` data may be modified:** When `createSubstructureGroups` is `true` (the default), LUMINA creates compound parent nodes for detected substructures and assigns child nodes to those parents by modifying their `parent` data. If your Cytoscape.js graph already uses compound nodes or existing `parent` relationships, these relationships may be changed. Set `createSubstructureGroups: false` if you do not want LUMINA to create substructure group parents or modify node `parent` data for this purpose. Check your graph's existing compound-node structure before enabling this option.
+* Generated compound parents have the class `substructure-group` and IDs of the form `<componentIndex>_<groupId>`. When enabled, they are removed and regenerated on each run.

package/dist/lumina-layout.d.ts

@@ -47,6 +47,7 @@ export interface LuminaOptions {
     stepByStep?: boolean;
     force?: LuminaForceOptions;
     stress?: LuminaStressOptions;
+    createSubstructureGroups?: boolean;
 }
 /** Options passed to `cy.layout()` for the LUMINA layout. */
 export interface LuminaLayoutOptions extends LuminaOptions, cytoscape.BaseLayoutOptions {
@@ -133,6 +134,7 @@ declare class VEdge {
  *       iterations: 600,                   // shared
  *       force:  { repulsion: 300, springK: 0.15 },   // force only
  *       stress: { weightExponent: 2 }                // stress only
+ *       createSubstructureGroups: true
  *   }).run();
  */
 export default function register(cytoscapeInstance: any): void;

package/dist/lumina-layout.js

@@ -29,11 +29,12 @@ export const DEFAULT_PARAMS = {
         coolingExponent: 2,
         useAngularForce: false,
         angularStrength: 0.2,
-        angularMaxForce: 2.0
+        angularMaxForce: 2.0,
     },
     stress: {
-        weightExponent: 2
-    }
+        weightExponent: 2,
+    },
+    createSubstructureGroups: false,
 };
 function applyDefaults(defaults, overrides) {
     const resolved = { ...defaults };
@@ -173,6 +174,7 @@ function computeStressDistances(nodes, edges, idealLength) {
  *       iterations: 600,                   // shared
  *       force:  { repulsion: 300, springK: 0.15 },   // force only
  *       stress: { weightExponent: 2 }                // stress only
+ *       createSubstructureGroups: true
  *   }).run();
  */
 export default function register(cytoscapeInstance) {
@@ -1713,7 +1715,7 @@ LuminaLayout.prototype.run = function () {
         });
     });
     this.packNetworks(networkInfos);
-    if (1) {
+    if (this.params.createSubstructureGroups) {
         networkInfos.forEach((networkInfo, index) => {
             const nodes = networkInfo.nodes;
             // All parent IDs in the current network

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intact-ebi/cytoscape-lumina",
-  "version": "1.1.0",
+  "version": "1.2.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",
@@ -71,4 +71,4 @@
   "dependencies": {
     "fastpriorityqueue": "^0.8.0"
   }
-}
+}