d3-force-cluster

Modular force for use with D3's forceSimulation.

Pulls nodes toward a set of cluster center nodes / points. Works well with a collision force to pack nodes together in clusters with no overlap.

Adapted from Mike Bostock's Clustered Force Layout III.

Installing

npm

npm install d3-force-cluster

CDN (UNPKG), via <script>

<script src="https://unpkg.com/d3-force-cluster@latest"></script>

Local, via <script>

Download the latest release

<script src="./d3-force-cluster.min.js"></script>

Usage

Accessing the module

The install method you use determines the syntax for accessing the module in your code:

npm

Import the forceCluster() method and use it in a forceSimulation.

import { forceCluster } from 'd3-force-cluster'
// ...
d3.forceSimulation
	.force('cluster', forceCluster());

via <script> or CDN (UNPKG)

The forceCluster() method is available in the global d3 namespace.

d3.forceSimulation
	.force('cluster', d3.forceCluster());

Using the module

Add a 'cluster' force just like you would any other D3 force module:

// add a clustering force to pull nodes toward their assigned cluster center node
d3.forceSimulation()
  // cluster by section
  .force('cluster', forceCluster()	// see 'Accessing the module' above for the correct syntax
    .centers(function (d) { return clusters[d.cluster]; })
    .strength(0.2)
    .centerInertia(0.1))

More detailed examples:

• Simple cluster layout
  
• Centered cluster layout
  
• Mouse following cluster layout
  

API

The forceCluster module follows the basic interface described in d3-force, additionally implementing the following:

# cluster.initialize(nodes) <>

Assigns the array of nodes to this force. This method is called when a force is bound to a simulation via simulation.force and when the simulation’s nodes change via simulation.nodes. A force may perform necessary work during initialization, such as evaluating per-node parameters, to avoid repeatedly performing work during each application of the force.

# cluster.centers([centers]) <>

If centers is specified, specifies the center nodes or points of each force cluster. If centers is not specified, returns the current Array of centers. // TODO: finish the force centers to the specified number in the range [0,1] and returns this force.

# cluster.strength([strength]) <>

If strength is specified, sets the force strength to the specified number in the range [0,1] and returns this force. If strength is not specified, returns the current strength, which defaults to 0.1.

This parameter determines the attraction strength of each node to the specified (via cluster.centers) cluster center node/position.

# cluster.centerInertia([centerInertia]) <>

If centerInertia is specified, sets the inertia of cluster center nodes to the specified number in the range [0,1] and returns this force. If centerInertia is not specified, returns the current center inertia, which defaults to 0.

Lower values (close to 0.0) result in cluster center nodes with lower inertia: they are easily pulled around by other nodes in the cluster. Higher values (close to 1.0) result in cluster center nodes that are moved very little by other nodes in the cluster.

Building and testing

Install nvm and npm if you haven't already.

Build with the following commands:

nvm use
npm install
npm run dist

Test with npm run test.