├── .babelrc
├── .eslintrc
├── .gitignore
├── .npmignore
├── .nvmrc
├── .travis.yml
├── LICENSE
├── README.md
├── index.js
├── lib
    └── forceCluster.js
├── package.json
├── rollup.config.js
└── test
    └── forceCluster-test.js


/.babelrc:
--------------------------------------------------------------------------------
1 | {
2 |   "presets": [ "es2015" ]
3 | }
4 | 


--------------------------------------------------------------------------------
/.eslintrc:
--------------------------------------------------------------------------------
1 | {
2 |   "parser": "babel-eslint",
3 |   "extends": "eslint:recommended",
4 |   "env": {
5 |     "node": true,
6 |     "mocha": true
7 |   }
8 | }
9 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | dist
2 | coverage
3 | node_modules
4 | npm_debug.log
5 | 


--------------------------------------------------------------------------------
/.npmignore:
--------------------------------------------------------------------------------
1 | test
2 | coverage
3 | node_modules
4 | npm_debug.log
5 | 


--------------------------------------------------------------------------------
/.nvmrc:
--------------------------------------------------------------------------------
1 | 5.11.1


--------------------------------------------------------------------------------
/.travis.yml:
--------------------------------------------------------------------------------
1 | language: node_js
2 | node_js:
3 |   - 5.11.1
4 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | Copyright 2016 Eric Socolofsky
 2 | All rights reserved.
 3 | 
 4 | Redistribution and use in source and binary forms, with or without modification,
 5 | are permitted provided that the following conditions are met:
 6 | 
 7 | * Redistributions of source code must retain the above copyright notice, this
 8 |   list of conditions and the following disclaimer.
 9 | 
10 | * Redistributions in binary form must reproduce the above copyright notice,
11 |   this list of conditions and the following disclaimer in the documentation
12 |   and/or other materials provided with the distribution.
13 | 
14 | * Neither the name of the author nor the names of contributors may be used to
15 |   endorse or promote products derived from this software without specific prior
16 |   written permission.
17 | 
18 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
19 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
20 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
21 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
22 | ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
24 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
25 | ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
27 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # d3-force-cluster
  2 | 
  3 | Modular force for use with D3's [`forceSimulation`](https://github.com/d3/d3-force#forceSimulation).
  4 | 
  5 | Pulls nodes toward a set of cluster center nodes / points. Works well with a [collision force](https://github.com/d3/d3-force/blob/master/README.md#collision) to pack nodes together in clusters with no overlap.
  6 | 
  7 | Adapted from Mike Bostock's [Clustered Force Layout III](https://bl.ocks.org/mbostock/7881887).
  8 | 
  9 | [![Build Status](https://travis-ci.org/ericsoco/d3-force-cluster.svg?branch=master)](https://travis-ci.org/ericsoco/d3-force-cluster)
 10 | 
 11 | 
 12 | ## Installing
 13 | 
 14 | #### npm
 15 | 
 16 | `npm install d3-force-cluster`
 17 | 
 18 | #### CDN ([UNPKG](https://unpkg.com/)), via `<script>`
 19 | 
 20 | `<script src="https://unpkg.com/d3-force-cluster@latest"></script>`
 21 | 
 22 | #### Local, via `<script>`
 23 | 
 24 | Download the [latest release](https://github.com/ericsoco/d3-force-cluster/releases/latest)
 25 | 
 26 | `<script src="./d3-force-cluster.min.js"></script>`
 27 | 
 28 | 
 29 | ## Usage
 30 | 
 31 | ### Accessing the module
 32 | 
 33 | The install method you use determines the syntax for accessing the module in your code:
 34 | 
 35 | #### npm
 36 | 
 37 | Import the `forceCluster()` method and use it in a `forceSimulation`.
 38 | 
 39 | ```
 40 | import { forceCluster } from 'd3-force-cluster'
 41 | // ...
 42 | d3.forceSimulation
 43 | 	.force('cluster', forceCluster());
 44 | ```
 45 | 
 46 | #### via `<script>` or CDN ([UNPKG](https://unpkg.com/))
 47 | 
 48 | The `forceCluster()` method is available in the global `d3` namespace.
 49 | 
 50 | ```
 51 | d3.forceSimulation
 52 | 	.force('cluster', d3.forceCluster());
 53 | ```
 54 | 
 55 | ### Using the module
 56 | 
 57 | Add a `'cluster'` force just like you would any other D3 force module:
 58 | 
 59 | ```
 60 | // add a clustering force to pull nodes toward their assigned cluster center node
 61 | d3.forceSimulation()
 62 |   // cluster by section
 63 |   .force('cluster', forceCluster()	// see 'Accessing the module' above for the correct syntax
 64 |     .centers(function (d) { return clusters[d.cluster]; })
 65 |     .strength(0.2)
 66 |     .centerInertia(0.1))
 67 | ```
 68 | 
 69 | More detailed examples:
 70 | - [Simple cluster layout<br>![Simple cluster layout](http://bl.ocks.org/ericsoco/raw/4e1b7b628771ae77753842e6dabfcef3/thumbnail.png)](http://bl.ocks.org/ericsoco/4e1b7b628771ae77753842e6dabfcef3)
 71 | - [Centered cluster layout<br>![Centered cluster layout](http://bl.ocks.org/ericsoco/raw/d2d49d95d2f75552ac64f0125440b35e/thumbnail.png)](http://bl.ocks.org/ericsoco/d2d49d95d2f75552ac64f0125440b35e)
 72 | - [Mouse following cluster layout<br>![Mouse following cluster layout](http://bl.ocks.org/ericsoco/raw/11d5013dee991b219b205a4ecd558d7c/thumbnail.png)](http://bl.ocks.org/ericsoco/11d5013dee991b219b205a4ecd558d7c)
 73 | 
 74 | 
 75 | 
 76 | ## API
 77 | 
 78 | The [`forceCluster`](https://github.com/ericsoco/d3-force-cluster/blob/master/lib/forceCluster.js) module follows the [basic interface described in d3-force](https://github.com/d3/d3-force/blob/master/README.md#forces), additionally implementing the following:
 79 | 
 80 | <a name="cluster_initialize" href="#cluster_initialize">#</a> <i>cluster</i>.<b>initialize</b>(<i>nodes</i>) [<>](https://github.com/ericsoco/d3-force-cluster/blob/master/lib/forceCluster.js#L52 "Source")
 81 | 
 82 | Assigns the array of *nodes* to this force. This method is called when a force is bound to a simulation via [*simulation*.force](https://github.com/d3/d3-force/blob/master/README.md#simulation_force) and when the simulation’s nodes change via [*simulation*.nodes](https://github.com/d3/d3-force/blob/master/README.md#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.
 83 | 
 84 | <a name="cluster_centers" href="#cluster_centers">#</a> <i>cluster</i>.<b>centers</b>([<i>centers</i>]) [<>](https://github.com/ericsoco/d3-force-cluster/blob/master/lib/forceCluster.js#L62 "Source")
 85 | 
 86 | 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.
 87 | `// TODO: finish`
 88 | the force centers to the specified number in the range [0,1] and returns this force. 
 89 | 
 90 | <a name="cluster_strength" href="#cluster_strength">#</a> <i>cluster</i>.<b>strength</b>([<i>strength</i>]) [<>](https://github.com/ericsoco/d3-force-cluster/blob/master/lib/forceCluster.js#L79 "Source")
 91 | 
 92 | 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.
 93 | 
 94 | This parameter determines the attraction strength of each node to the specified (via [*cluster*.centers](#cluster_centers)) cluster center node/position.
 95 | 
 96 | <a name="cluster_centerInertia" href="#cluster_centerInertia">#</a> <i>cluster</i>.<b>centerInertia</b>([<i>centerInertia</i>]) [<>](https://github.com/ericsoco/d3-force-cluster/blob/master/lib/forceCluster.js#L91 "Source")
 97 | 
 98 | 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.
 99 | 
100 | 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.
101 | 
102 | 
103 | ## Building and testing
104 | 
105 | Install [nvm](http://nvm.sh) and [npm](http://npmjs.com) if you haven't already.
106 | 
107 | Build with the following commands:
108 | 
109 | ```bash
110 | nvm use
111 | npm install
112 | npm run dist
113 | ```
114 | 
115 | Test with `npm run test`.
116 | 


--------------------------------------------------------------------------------
/index.js:
--------------------------------------------------------------------------------
1 | export { default as forceCluster } from './lib/forceCluster';


--------------------------------------------------------------------------------
/lib/forceCluster.js:
--------------------------------------------------------------------------------
 1 | /**
 2 |  * Pulls nodes toward a set of cluster center nodes / points.
 3 |  * Adapted from Mike Bostock's Clustered Force Layout III:
 4 |  * https://bl.ocks.org/mbostock/7881887
 5 |  */
 6 | function cluster (centers) {
 7 | 
 8 |   let nodes,
 9 |     centerpoints = [],
10 |     strength = 0.1,
11 |     centerInertia = 0.0;
12 | 
13 |   // coerce centers accessor into a function
14 |   if (typeof centers !== 'function') centers = () => centers;
15 | 
16 |   function force (alpha) {
17 |     // scale + curve alpha value
18 |     alpha *= strength * alpha;
19 | 
20 |     let c, x, y, l, r;
21 |     nodes.forEach((d, i) => {
22 |       c = centerpoints[i];
23 |       if (!c || c === d) return;
24 |       
25 |       x = d.x - c.x,
26 |       y = d.y - c.y,
27 |       l = Math.sqrt(x * x + y * y),
28 |       r = d.radius + (c.radius || 0);
29 | 
30 |       if (l && l != r) {
31 |         l = (l - r) / l * alpha;
32 |         d.x -= x *= l;
33 |         d.y -= y *= l;
34 |         c.x += (1 - centerInertia) * x;
35 |         c.y += (1 - centerInertia) * y;
36 |       }
37 |     });
38 |   }
39 | 
40 |   function initialize () {
41 |     if (!nodes) return;
42 | 
43 |     // populate local `centerpoints` using `centers` accessor
44 |     let i, n = nodes.length;
45 |     centerpoints = new Array(n);
46 |     for (i = 0; i < n; i++) centerpoints[i] = centers(nodes[i], i, nodes);
47 |   }
48 |   
49 |   /**
50 |    * Reinitialize the force with the specified nodes.
51 |    */
52 |   force.initialize = _ => {
53 |     nodes = _;
54 |     initialize();
55 |   };
56 | 
57 |   /**
58 |    * An array of objects representing the centerpoint of each cluster,
59 |    * or a function that returns such an array.
60 |    * Each object must have `x` and `y` values, and optionally `radius`.
61 |    */
62 |   force.centers = _ => {
63 |     // return existing value if no value passed
64 |     if (_ == null) return centers;
65 | 
66 |     // coerce centers accessor into a function
67 |     centers = typeof _ === 'function' ? _ : (n, i) => _[i];
68 | 
69 |     // reinitialize
70 |     initialize();
71 | 
72 |     // allow chaining
73 |     return force;
74 |   };
75 | 
76 |   /**
77 |    * Strength of attraction to the cluster center node/position.
78 |    */
79 |   force.strength = _ => {
80 |     return _ == null ? strength : (strength = +_, force);
81 |   };
82 | 
83 |   /**
84 |    * Inertia of cluster center nodes/positions.
85 |    * Higher values mean the cluster center moves less;
86 |    * lower values mean the cluster center is more easily
87 |    * pulled around by other nodes in the cluster.
88 |    * Typical values range from 0.0 (cluster centers move as much as all other nodes)
89 |    * to 1.0 (cluster centers are not moved at all by the clustering force).
90 |    */
91 |   force.centerInertia = _ => {
92 |     return _ == null ? centerInertia : (centerInertia = +_, force);
93 |   };
94 | 
95 |   return force;
96 | 
97 | }
98 | 
99 | export default cluster;


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "d3-force-cluster",
 3 |   "version": "0.1.2",
 4 |   "description": "Clustering force for d3.forceSimulation.",
 5 |   "keywords": [
 6 |     "d3",
 7 |     "d3-module",
 8 |     "d3-force",
 9 |     "layout",
10 |     "graph",
11 |     "cluster",
12 |     "infovis",
13 |     "dataviz"
14 |   ],
15 |   "homepage": "http://ericsoco.github.io/d3-force-cluster/",
16 |   "license": "BSD-3-Clause",
17 |   "author": {
18 |     "name": "Eric Socolofsky",
19 |     "url": "http://transmote.com/"
20 |   },
21 |   "main": "dist/d3-force-cluster.js",
22 |   "module": "dist/d3-force-cluster.mjs",
23 |   "jsnext:main": "dist/d3-force-cluster.mjs",
24 |   "repository": {
25 |     "type": "git",
26 |     "url": "https://github.com/ericsoco/d3-force-cluster.git"
27 |   },
28 |   "scripts": {
29 |     "lint": "eslint lib",
30 |     "test": "tape 'test/**/*-test.js' | tap-min",
31 |     "predist": "npm run lint",
32 |     "dist": "rollup -c",
33 |     "postdist": "npm run test",
34 |     "watch": "rollup -c -w",
35 |     "prepublish": "npm run dist && uglifyjs dist/d3-force-cluster.js -c -m -o dist/d3-force-cluster.min.js",
36 |     "publish-patch": "npm version patch && npm publish"
37 |   },
38 |   "pre-push": [
39 |     "dist"
40 |   ],
41 |   "dependencies": {},
42 |   "devDependencies": {
43 |     "babel-eslint": "^7.0.0",
44 |     "babel-plugin-external-helpers": "^6.8.0",
45 |     "babel-preset-es2015": "^6.16.0",
46 |     "babelrc-rollup": "^3.0.0",
47 |     "eslint": "^3.8.1",
48 |     "rollup": "^0.36.3",
49 |     "rollup-plugin-babel": "^2.6.1",
50 |     "rollup-watch": "^2.5.0",
51 |     "sinon": "^1.17.6",
52 |     "tap-min": "^1.1.0",
53 |     "tape": "^4.6.2",
54 |     "uglify-js": "^2.7.3"
55 |   }
56 | }
57 | 


--------------------------------------------------------------------------------
/rollup.config.js:
--------------------------------------------------------------------------------
 1 | import babel from 'rollup-plugin-babel';
 2 | import babelrc from 'babelrc-rollup';
 3 | // import istanbul from 'rollup-plugin-istanbul';
 4 | 
 5 | let pkg = require('./package.json');
 6 | let external = Object.keys(pkg.dependencies);
 7 | 
 8 | export default {
 9 |   entry: 'index.js',
10 |   plugins: [
11 |     babel(babelrc())
12 |     // istanbul({
13 |     //   exclude: ['test/**/*', 'node_modules/**/*']
14 |     // })
15 |   ],
16 |   external: external,
17 |   targets: [
18 |     {
19 |       dest: pkg['main'],
20 |       format: 'umd',
21 |       moduleName: 'd3',
22 |       sourceMap: true
23 |     },
24 |     {
25 |       dest: pkg['jsnext:main'],
26 |       format: 'es',
27 |       sourceMap: true
28 |     }
29 |   ]
30 | };


--------------------------------------------------------------------------------
/test/forceCluster-test.js:
--------------------------------------------------------------------------------
 1 | var tape = require('tape'),
 2 |   sinon = require('sinon'),
 3 |   forceCluster = require('../');
 4 | 
 5 | tape('forceCluster() returns a valid force module.', function (test) {
 6 |   var unit = forceCluster.forceCluster();
 7 |   test.equal(typeof forceCluster, 'object');
 8 |   test.equal(typeof forceCluster.forceCluster, 'function');
 9 |   test.equal(typeof unit, 'function');
10 |   test.equal(typeof unit.initialize, 'function');
11 |   test.equal(typeof unit.centers, 'function');
12 |   test.equal(typeof unit.strength, 'function');
13 |   test.equal(typeof unit.centerInertia, 'function');
14 |   test.end();
15 | });
16 | 
17 | tape('initialize(nodes) calls center accessor once for each node', function (test) {
18 |   var stub = sinon.stub(),
19 |     nodes = [{}, {}, {}],
20 |     unit = forceCluster.forceCluster();
21 |   unit.centers(stub);
22 |   unit.initialize(nodes);
23 |   test.equal(stub.callCount, nodes.length);
24 |   test.end();
25 | });
26 | 
27 | tape('centers(const) wraps in a function and returns the force', function (test) {
28 |   var unit = forceCluster.forceCluster();
29 |   test.equal(unit.centers([0, 0]), unit);
30 |   test.equal(typeof unit.centers(), 'function');
31 |   test.end();
32 | });
33 | 
34 | tape('centers(fn) calls fn once for each node and returns the force', function (test) {
35 |   var stub = sinon.stub(),
36 |     nodes = [{}, {}, {}],
37 |     unit = forceCluster.forceCluster();
38 |   unit.initialize(nodes);
39 |   test.equal(unit.centers(stub), unit);
40 |   test.equal(stub.callCount, nodes.length);
41 |   test.end();
42 | });
43 | 
44 | tape('centers() returns the accessor', function (test) {
45 |   var unit = forceCluster.forceCluster();
46 |   test.equal(typeof unit.centers(), 'function');
47 |   test.end();
48 | });
49 | 
50 | tape('strength(const) sets the value and returns the force', function (test) {
51 |   var unit = forceCluster.forceCluster(),
52 |     value = 1;
53 |   test.equal(unit.strength(value), unit);
54 |   test.equal(unit.strength(), value);
55 |   test.end();
56 | });
57 | 
58 | tape('centerInertia(const) sets the value and returns the force', function (test) {
59 |   var unit = forceCluster.forceCluster(),
60 |     value = 1;
61 |   test.equal(unit.centerInertia(value), unit);
62 |   test.equal(unit.centerInertia(), value);
63 |   test.end();
64 | });
65 | 


--------------------------------------------------------------------------------