Common parameters for modes AUTOMATIC and BY_CLUSTER_IDS

This section applies only if the clustering mode is set to ibm_ilog.graphlayout.circular.CircularLayout.AUTOMATIC or ibm_ilog.graphlayout.circular.CircularLayout.BY_CLUSTER_IDS. Both modes work very similar. The main difference is that the clustering mode AUTOMATIC can handle graphs where clusters are not or only partially specified, while the clustering mode BY_CLUSTER_IDS requires a full specification of all clusters and throws an exception when performing a layout on a graph with incomplete cluster specification.

Cluster membership and order of the nodes on a cluster (CL)

Specifying clusters explicitly is not necessary in clustering mode BY_SUBGRAPHS, because the subgraphs form the clusters. In clustering mode AUTOMATIC however, clusters can optionally be specified, and in mode BY_CLUSTER_IDS, they even must be specified before performing the layout.
Example of specifying node cluster (CL algorithm)
To specify to which cluster each node of the graph belongs:
To specify the cluster membership, use a cluster identifier; that is, an instance of a subclass of the class ibm_ilog.graphlayout.circular.CircularClusterId (which is abstract). Two subclasses are provided:
You can combine these two types of identifiers as any other subclass of ibm_ilog.graphlayout.circular.CircularClusterId. For example, you can write:
// create identifier for first cluster (integer)
var clusterId1 = new ibm_ilog.graphlayout.circular.CircularClusterNumber(1);
// create identifier for second cluster (string)
var clusterId2 = new ibm_ilog.graphlayout.circular.CircularClusterName("R&D network");
Then, if node1 to node3 belong to the first cluster, you can write:
layout.setClusterIdAndIndex(node1, clusterId1);
layout.setClusterIdAndIndex(node2, clusterId1);
layout.setClusterIdAndIndex(node3, clusterId1);
Assume layout is an instance of ibm_ilog.graphlayout.circular.CircularLayout.
If you want the nodes to be drawn in a special order (for example, node1 -> node2 -> node3), you must also specify an index (an integer value) for each node:
layout.setClusterId(node1, clusterId1, 0);
layout.setClusterId(node2, clusterId1, 1);
layout.setClusterId(node3, clusterId1, 2);
Two methods allow you to specify the cluster to which a node belongs:
layout.setClusterId(node, clusterId)    
layout.addClusterId(node, clusterId)    
If you call the first method, the node belongs only to the cluster whose identifier is clusterId. The second method allows you to specify that a node belongs to more than one cluster.
These methods have another version with an additional argument, an integer value representing the index:
layout.setClusterIdAndIndex(node, clusterId, index)   
layout.addClusterIdAndIndex(node, clusterId, index)   
This value is used to order the nodes on the cluster. If you specify these indices, the algorithm sorts the nodes in ascending order according to the index values.
The values of the index cannot be negative. They do not need to be continuous; only the order of the values is important.
To obtain the specified index of a node in a given cluster, use the method:
var index = layout.getIndex(node, clusterId)  
If no index is specified for the node, the method returns the value ibm_ilog.graphlayout.circular.CircularLayout.NO_INDEX. It is a negative value.
To obtain an enumeration of the cluster identifiers for the clusters to which the node belongs, use the method:
var ids = layout.getNodeClusterIds(node1);
while(ids.hasNext()){
 var id = ids.next();
 console.log("id = " + id);
}
The elements of the enumeration are instances of a subclass of ibm_ilog.graphlayout.circular.CircularClusterId.
To efficiently obtain the number of clusters to which a node belongs, use the method:
var count = layout.getClusterIdsCount(node)  
To remove a node from the cluster with the specified identifier, use the method:
layout.removeClusterId(node, clusterId)  
To remove a node from all the clusters to which it belongs, use the method:
layout.removeAllClusterIds(node)  

Root clusters (CL)

The algorithm arranges the clusters of each connected component of the graph of clusters around a “root cluster”. By default, the algorithm can choose this cluster. Optionally, you can specify one or more root clusters (one for each connected component).
Example of specifying root clusters (CL algorithm)
To specify one or more root clusters (one for each connected component):
Use the methods:
layout.setRootClusterId(clusterId)  
To obtain an array containing the identifiers of the clusters that have been specified as root clusters, use the method:
var clusterIds = layout.getRootClusterIds()  
This parameter has no effect if the clustering mode is ibm_ilog.graphlayout.circular.CircularLayout.BY_SUBGRAPHS.

Star clusters (CL)

Example of specifying star center (CL algorithm)
To specify whether a node is the center of a star:
Use the method:
layout.setStarCenter(node, true)  
To know whether a node is the center of a star, use the method:
var isCenter = layout.isStarCenter(node)  
By default, a node is not the center of a star.
This parameter has no effect if the clustering mode is ibm_ilog.graphlayout.circular.CircularLayout.BY_SUBGRAPHS.

Get the contents, the position, and the size of the clusters (CL)

At times, you might need to know the position and the size of the circle on which the nodes for each cluster are drawn. This may be the case if you want to perform some reshaping operations on the links. To do so, you can obtain an array containing all the cluster identifiers after the layout is performed. In clustering mode AUTOMATIC, the array can contain generated cluster identifiers if no clusters were specified.
Example of obtaining an array that contains all the cluster identifiers (CL algorithm)
To obtain an array containing all the cluster identifiers after the layout is performed:
Use the method:
var ids = layout.getClusterIds()  
The array contains instances of a subclass of ibm_ilog.graphlayout.circular.CircularClusterId. By browsing the elements of this Array, you can get the necessary information for each cluster:
var radius = layout.getClusterRadius(clusterIndex)   
var center = layout.getClusterCenter(clusterIndex)   
var nodes = layout.getClusterNodes(clusterIndex)   
The getClusterNodes method returns the nodes that make up the cluster. The argument clusterIndex represents the position of the cluster in the Array returned by the method getClusterIds().
Do not use these methods if the clustering mode is ibm_ilog.graphlayout.circular.CircularLayout.BY_SUBGRAPHS.

Dimensional parameters (CL)

This section illustrates the dimensional parameters used in the Circular Layout algorithm. These parameters are explained in the sections that follow.
The clustering mode BY_CLUSTER_IDS also works with a disconnected graph offset. It is explained in the section Handling of disconnected graphs.
The dimensional
parameters used by the Circular Layout algorithm
Dimensional parameters for the Circular Layout algorithm

Offset (CL)

The layout algorithm tries to preserve a minimum distance between nodes (see figure Dimensional parameters for the Circular Layout algorithm).
Example of specifying the offset (CL algorithm)
To specify the offset:
Use the method:
layout.setOffset(20)  

Level offset (CL)

If the clustering mode is BY_SUBGRAPHS, the level offset parameter controls the minimal offset between nodes that belong to the same cluster.
If the clustering mode is BY_CLUSTER_IDS, the following scenario applies.
As explained in The CL algorithm, interconnected rings and clusters are drawn on concentric circles around a root cluster. The radius of each concentric circle is computed to avoid overlapping clusters. In some cases, you might want to increase this radius to obtain a clearer drawing of the network. To meet this purpose, the radius is systematically increased with a “level offset” value (see figure Dimensional parameters for the Circular Layout algorithm).
Example of specifying the level offset (CL algorithm)
To specify the level offset:
Use the method:
layout.setLevelOffset(5)  
The default value is zero.
This parameter has no effect if the clustering mode is ibm_ilog.graphlayout.circular.CircularLayout.BY_SUBGRAPHS.