# Network - clustering

Handles the HTML part of the canvas.

### Options

Clustering has no options, everything is done with methods.

### Methods

This is a list of all the methods in the public API. Options can be set directly to the module or you can use the setOptions method of the network itself and use the module name as an object name.

name | returns | description
findNode( `String nodeId` ) | Array | Nodes can be in clusters. Clusters can also be in clusters. This function returns and array of nodeIds showing where the node is. Example: cluster 'A' contains cluster 'B', cluster 'B' contains cluster 'C', cluster 'C' contains node 'fred'. `network.clustering.findNode('fred')` will return `['A','B','C','fred']`.
isCluster( `String nodeId` ) | Boolean | Returns true if the node whose ID has been supplied is a cluster.
openCluster( `String nodeId` ) | none | Opens the cluster, releases the contained nodes and edges, removing the cluster node and cluster edges.
cluster( `Object options` ) | none | The options object is explained in full below. The joinCondition function is presented with all nodes.
clusterByConnection( `String nodeId`, `[Object options]` ) | none | This method looks at the provided node and makes a cluster of it and all it's connected nodes. The behaviour can be customized by proving the options object. All options of this object are explained below. The joinCondition is only presented with the connected nodes.
clusterByHubsize( `Number hubsize`, `[Object options]` ) | none | This method checks all nodes in the network and those with a equal or higher amount of edges than specified with the `hubsize` qualify. Cluster by connection is performed on each of them. The options object is described for `clusterByConnection` and does the same here.
clusterOutliers( `[Object options]` ) | none | This method will cluster all nodes with 1 edge with their respective connected node.

#### Cluster options object

The options object supplied to the cluster functions can contain these properties:

name | Type | description
joinCondition( `Object nodeOptions` ) | Function | Optional for all but the cluster method. The cluster module loops over all nodes that are selected to be in the cluster and calls this function with their data as argument. If this function returns true, this node will be added to the cluster. You have access to all options (including the default) as well as any custom fields you may have added to the node to determine whether or not to include it in the cluster. Example:
    var nodes = [
      {id: 4, label: 'Node 4'},
      {id: 5, label: 'Node 5'},
      {id: 6, label: 'Node 6', cid:1},
      {id: 7, label: 'Node 7', cid:1}
    ]

    var options = {
      joinCondition:function(nodeOptions) {
        return nodeOptions.cid === 1;
      }
    }

    network.clustering.cluster(options);
processProperties( `Object nodeOptions` ) | Function | Optional. Before creating the new cluster node, this (optional) function will be called with the properties supplied by you (`clusterNodeProperties`), all contained nodes and all contained edges. You can use this to update the properties of the cluster based on which items it contains. The function should return the properties to create the cluster node. In the example below, we ensure preservation of mass and value when forming the cluster:
    var options = {
      processProperties: function (clusterOptions, childNodes, childEdges) {
        var totalMass = 0;
        var totalValue = 0;
        for (var i = 0; i < childNodes.length; i++) {
            totalMass += childNodes[i].mass;
            totalValue = childNodes[i].value ? totalValue + childNodes[i].value : totalValue;
        }
        clusterOptions.mass = totalMass;
        if (totalValue > 0) {
          clusterOptions.value = totalValue;
        }
        return clusterOptions;
      },
    }
clusterNodeProperties | Object | Optional. This is an object containing the options for the cluster node. All options described in the nodes module are allowed. This allows you to style your cluster node any way you want. This is also the style object that is provided in the processProperties function for fine tuning. If undefined, default node options will be used.
clusterEdgeProperties | Object | Optional. This is an object containing the options for the edges connected to the cluster. All options described in the edges module are allowed. Using this, you can style the edges connecting to the cluster any way you want. If none are provided, the optoins from the edges that are replaced are used. If undefined, default edge options will be used.

### Events

The clustering module does not have any events.