Merge pull request #41 from iVis-at-Bilkent/develop

Merge develop branch to master

README.md

@@ -6,21 +6,58 @@ cytoscape.js-cise
 
 CiSE(Circular Spring Embedder) is an algorithm based on the traditional force-directed layout scheme with extensions to move and rotate nodes in the same cluster as a group. Further local improvements may be obtained by flipping clusters and by swapping neighboring node pairs in the same cluster, reducing the edge crossing number.
 
-The algorithm is implemented as a Cytoscape.js extension by [i-Vis Lab](http://cs.bilkent.edu.tr/~ivis/) in Bilkent University ([demo](https://ivis-at-bilkent.github.io/cytoscape.js-cise/demo.html))
+The algorithm is implemented as a Cytoscape.js extension by [i-Vis Lab](http://cs.bilkent.edu.tr/~ivis/) in Bilkent University.
+Here is a demo:
+<p align="center">
+<a href="https://raw.githack.com/iVis-at-Bilkent/cytoscape.js-cise/develop/demo/demo.html"><img src="https://www.cs.bilkent.edu.tr/~ivis/images/demo1.png" height=42px></a>
+</p>
 
 Please cite the following when using this layout:
 
 M. Belviranli, A. Dilek and U. Dogrusoz, "[CiSE: A Circular Spring Embedder Layout Algorithm](https://dlnext.acm.org/doi/abs/10.1109/TVCG.2012.178)" in IEEE Transactions on Visualization & Computer Graphics, vol. 19, no. 06, pp. 953-966, 2013.
 
-<p align="center"><img src="demo.gif" width="526" height="411"></p>
+<p align="center"><img src="demo/demo.gif" width="526" height="411"></p>
 
 A detailed illustration of CiSE can also be found [here.](https://www.youtube.com/watch?v=SMDAQajK-E8)
 
+In cases where there is no domain-specific way to cluster graphs, Markov Clustering in the Cytoscape.js core library may be used for clustering, based solely on the topology of the graph. You need to set the "clusterID" of the nodes according to their clusters and create an array of arrays where each array is a cluster that contains node IDs. For example:
+
+```js
+let clusters = window.cy.elements().markovClustering( options );
+
+for(var i = 0; i<clusters.length; i++){
+  for(var j = 0; j<clusters[i].length; j++){
+    clusters[i][j]._private.data.clusterID = i;
+  }
+}
+
+let arrayOfClusterArrays;
+window.cy.nodes().forEach(function (node) {
+ let clusterID = node.data('clusterID');
+ if (uniqueClusterIDs.includes(clusterID)) {
+   if(arrayOfClusterArrays[clusterID] == undefined){
+     arrayOfClusterArrays[clusterID] = [];
+   }
+   else{
+     arrayOfClusterArrays[clusterID].push(node.data('id'));
+   }
+ }
+ else {
+   arrayOfClusterArrays.push([node.data('id')]);
+ }
+
+var layout = window.cy.layout({name: 'cise',clusters: arrayOfClusterArrays});
+
+```
+
 ## Dependencies
 
  * Cytoscape.js: ^3.2.0
  * avsdf-base: ^1.0.0
  * cose-base: ^1.0.0
+ 
+## Optional Dependencies
+ * cytoscape-layout-utilities: ^1.0.0 (only needed if `packComponents` is true)
 
 ## Usage instructions
 
@@ -57,8 +94,14 @@ require(['cytoscape', 'cytoscape-cise'], function( cytoscape, cise ){
 });
 ```
 
-Plain HTML/JS has the extension registered for you automatically, because no `require()` is needed.
+Plain HTML/JS has the extension registered for you automatically, because no `require()` is needed. Just add the following files:
 
+```
+<script src="https://unpkg.com/layout-base/layout-base.js"></script>
+<script src="https://unpkg.com/avsdf-base/avsdf-base.js"></script>
+<script src="https://unpkg.com/cose-base/cose-base.js"></script>
+<script src="https://unpkg.com/cytoscape-cise/cytoscape-cise.js"></script>
+```
 
 ## API
 
@@ -79,13 +122,19 @@ var default = {
     // corresponding to that node. Returning negative numbers, null or undefined is fine for unclustered
     // nodes.  
     // e.g
-    // Array:                                     OR          function(node){
-    //  [ ['n1','n2','n3'],                                       ...
-    //    ['n5','n6']                                         }
-    //    ['n7', 'n8', 'n9', 'n10'] ]                         
-    clusters: clusterInfo,
+    // Array:                                     OR          function(node){ ...
+    //  [ ['n1','n2','n3'],                                     return "1";    // or any cluster ID assosiated with node
+    //    ['n5','n6']                                           return node.data("clusterID"); // If the cluster IDs are stored in Data element of nodes
+    //    ['n7', 'n8', 'n9', 'n10'] ]                         ... }
+    clusters: clusterInfo,                                    
+
 
     // -------- Optional parameters --------
+
+    // Use random node positions at beginning of layout
+    // if this is set to false, the layout will be incremental
+    randomize: true, 
+
     // Whether to animate the layout
     // - true : Animate while the layout is running
     // - false : Just show the end result
@@ -107,6 +156,9 @@ var default = {
 
     // Padding in rendered co-ordinates around the layout
     padding: 30,
+
+    // Whether to include labels in node dimensions
+    nodeDimensionsIncludeLabels: false,
 
     // separation amount between nodes in a cluster
     // note: increasing this amount will also increase the simulation time 
@@ -124,22 +176,28 @@ var default = {
 
     // - Lower values give looser springs
     // - Higher values give tighter springs
-    springCoeff: 0.45,
+    springCoeff: edge => 0.45,
 
     // Node repulsion (non overlapping) multiplier
-    nodeRepulsion: 4500,
+    nodeRepulsion: node => 4500,
 
     // Gravity force (constant)
     gravity: 0.25,
 
     // Gravity range (constant)
     gravityRange: 3.8, 
 
+    // whether to pack components of the graph, if set to true, you should import cytoscape.js-layout-utilities
+    packComponents: false
+
     // Layout event callbacks; equivalent to `layout.one('layoutready', callback)` for example
     ready: function(){}, // on layoutready
     stop: function(){}, // on layoutstop
 }
 ```
+To be able to use `packComponents` option, `cytoscape-layout-utilities` extension should also be registered in the application. 
+Packing related [options](https://github.com/iVis-at-Bilkent/cytoscape.js-layout-utilities#default-options) should be set via `cytoscape-layout-utilities` extension.
+If they are not set, CiSE uses default options.
 
 ## Build targets
 
@@ -166,4 +224,8 @@ This project is set up to automatically be published to npm and bower.  To publi
 
 ## Team
 
-  * [Alihan Okka](https://github.com/alihanokka) and [Ugur Dogrusoz](https://github.com/ugurdogrusoz) of [i-Vis at Bilkent University](http://www.cs.bilkent.edu.tr/~ivis)
+  * [H. Eren Calik](https://github.com/herencalik), [Ugur Dogrusoz](https://github.com/ugurdogrusoz) of [i-Vis at Bilkent University](http://www.cs.bilkent.edu.tr/~ivis)
+
+### Alumni
+
+  * [Alihan Okka](https://github.com/alihanokka)