Refactor API

Author: Ricky Reusser

.gitignore

@@ -0,0 +1,4 @@
+dist
+*.log
+lib-cov
+node_modules

.npmignore

@@ -0,0 +1,3 @@
+examples
+test
+www

.travis.yml

@@ -0,0 +1,12 @@
+language: node_js
+node_js:
+  - "5"
+  - "5.1"
+  - "4"
+  - "4.2"
+  - "4.1"
+  - "4.0"
+  - "0.12"
+  - "0.11"
+  - "0.10"
+  - "iojs"

README.md

@@ -1,20 +1,12 @@
-kmpp
-====
+# kmpp
 
-When dealing with lots of data points, clustering algorithms may be needed in
-order to group them. The k-means algorithm partitions _n_ data points into
-_k_ clusters and finds the centroids of these clusters incrementally.
+When dealing with lots of data points, clustering algorithms may be used to group them. The k-means algorithm partitions _n_ data points into _k_ clusters and finds the centroids of these clusters incrementally.
 
-The basic k-means algorithm is initialized with _k_ centroids at random
-positions.
+The algorithm assigns data points to the closest cluster, and the centroids of each cluster are re-calculated. These steps are repeated until the centroids do not changing anymore.
 
-It assigns data points to the closest cluster, the centroids of each
-cluster are re-calculated afterwards. These assignment/recalculating steps are
-repeated until the centroids are not changing anymore.
+The basic k-means algorithm is initialized with _k_ centroids at random positions. This implementation addresses some disadvantages of the arbitrary initialization method with the k-means++ algorithm (see "Further reading" at the end).
 
-This implementation addresses some disadvantages of the arbitrary
-initialization method with the k-means++ algorithm (see "Further reading" at the
-end).
+## Installation
 
 ## Installing via npm
 
@@ -23,83 +15,53 @@ Install kmpp as Node.js module via NPM:
 $ npm install kmpp
 ````
 
-## Setting up a new instance
-
-````js
-  // var kmpp = require('kmpp'); /* When running in Node.js */
-  var k = new kmpp();
-````
-
-## Attributes
-
-### kmpp [Boolean]
-
-Enables or disables k-means++ initialization. If disabled, the initial
-centroids are selected randomly. It is recommended to leave this setting
-enabled, as it reduces the amount of the actual algorithm's iteration steps.
-
-### k [number]
-
-This value defines the amount of clusters. You can let the module guess the
-amount by the rule of thumb with the guessK() function. It is crucial to select
-an appropriate value of clusters in order to find a good solution.
-
-### maxIterations [number]
-
-Defines the maximum amount of iterations which might be useful when performance
-is more important than accuracy. Disabled by default with the value -1.
-
-### converged
-
-Returns true when the clustering is finished, false otherwise.
-
-### iterations
-
-Returns the amount of iterations.
-
-## Methods
-
-### reset ()
-
-Clears data points and calculated results.
-
-### setPoints (points)
-
-setPoints assigns an array of data points which should be clustered and calls
-reset(). Use the format [{ x : x0, y : y0 }, ... , { x : xn, y: yn }].
-
-### guessK ()
-
-Guess the amount of clusters by the rule of thumb. (k = Math.sqrt( n * 0.5)).
-See below for advice for choosing the right value for k.
-
-### initCentroids ()
-
-The initial centroids are selected by the k-means++ algorithm or randomly. The
-latter behavior is disabled by default. k-means++ finds initial values close to
-the final result, therefore, less iterations are required for the final result
-usually.
-
-### iterate ()
-
-As k-means is an incremental algorithm, the iterate function should be called
-until the centroids do not change anymore.
-
-### cluster (callback)
-
-Convenience function which calls the iterate() function until the algorithm has
-finished.
-
-# Tests
-
-For the moment, you could open index.html or index-animated.html in your
-browser.
-
-# Todo
-
-  * remove the dependency on jQuery
-  * add build tools
-  * better testing and visualization
+## Example
+
+```javascript
+var kmpp = require('kmpp');
+
+kmpp([
+  [x1, y1, ...],
+  [x2, y2, ...],
+  [x3, y3, ...],
+  ...
+], {
+  k: 4
+});
+
+// =>
+// { converged: true,
+//   centroids: [[xm1, ym1, ...], [xm2, ym2, ...], [xm3, ym3, ...]],
+//   counts: [ 7, 6, 7 ],
+//   assignments: [ 2, 2, 2, 2, 2, 2, 2, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1 ]
+// }
+```
+
+## API
+
+### `kmpp(points[, opts)`
+
+Exectes the k-means++ algorithm on `points`.
+
+Arguments:
+- `points` (`Array`): An array-of-arrays containing the points in format `[[x1, y1, ...], [x2, y2, ...], [x3, y3, ...], ...]`
+- `opts`: object containing configuration parameters. Parameters are
+  - `distance` (`function`): Optional function that takes two points and returns the distance between them.
+  - `initialize` (`Boolean`): Perform initialization. If false, uses the initial state provided in `centroids` and `assignments`. Otherwise discards any initial state and performs initialization.
+  - `k` (`Number`): number of centroids. If not provided, `sqrt(n / 2)` is used, where `n` is the number of points.
+  - `kmpp` (`Boolean`, default: `true`): If true, uses k-means++ initialization. Otherwise uses naive random assignment.
+  - `maxIterations` (`Number`, default: `100`): Maximum allowed number of iterations.
+  - `norm` (`Number`, default: `2`): L-norm used for distance computation. `1` is Manhattan norm, `2` is Euclidean norm. Ignored if `distance` function is provided.
+  - `centroids` (`Array`): An array of centroids. If `initialize` is false, used as initialization for the algorithm, otherwise overwritten in-place if of the correct size.
+  - `assignments` (`Array`): An array of assignments. Used for initialization, otherwise overwritten.
+  - `counts` (`Array`): An output array used to avoid extra allocation. Values are discarded and overwritten.
+
+Returns an object containing information about the centroids and point assignments. Values are:
+- `converged`: `true` if the algorithm converged successfully
+- `centroids`: a list of centroids
+- `counts`: the number of points assigned to each respective centroid
+- `assignments`: a list of integer assignments of each point to the respective centroid
+- `iterations`: number of iterations used
 
 # Credits
 
@@ -108,6 +70,8 @@ browser.
   for measurements and improved the random initialization by choosing from
   points
 
+* [Ricky Reusser](https://github.com/rreusser) refactored API
+
 # Further reading
 
 * [Wikipedia: k-means clustering](https://en.wikipedia.org/wiki/K-means_clustering)
@@ -117,4 +81,4 @@ browser.
 
 # License
 
-MIT License
+© 2017. MIT License.

docs/index.html

@@ -0,0 +1,192 @@
+var regl = require('regl');
+var failNicely = require('fail-nicely');
+var panel = require('control-panel');
+var hsl = require('float-hsl2rgb');
+var css = require('insert-css');
+var kmpp = require('../');
+var h = require('h');
+
+css(`
+.control-panel {
+  z-index: 100;
+  position: relative;
+}
+
+.progress {
+  background: rgba(255, 255, 255, 0.8);
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  z-index: 1;
+}
+`);
+
+var progress = h('pre.progress');
+document.body.appendChild(progress);
+
+regl({
+  onDone: failNicely((regl) => {
+    var pointBuf = regl.buffer();
+    var pointColorBuf = regl.buffer();
+    var centroidBuf = regl.buffer();
+    var centroidColorBuf = regl.buffer();
+
+    var x, iteration;
+    var km = {};
+    var settings = {
+      norm: 2,
+      points: 5000,
+      k: 0,
+      kmpp: true,
+      uniformity: 0.5,
+      periodicity: 4
+    };
+
+    function distribution (x, y) {
+      var w = Math.PI * settings.periodicity;
+      return Math.abs(
+        Math.cos(x * w) *
+        Math.sin((y - x / 2) * w) *
+        Math.sin((y + x / 2) * w)
+      );
+    }
+
+    function restart () {
+      iteration = 0;
+      progress.textContent = '';
+      delete km.assignments;
+      delete km.centroids;
+      km.converged = false;
+    }
+
+    function initialize () {
+      var ar = window.innerWidth / window.innerHeight;
+      var i = 0;
+      x = [];
+      while (i < settings.points) {
+        // Random points; we'll scale these to the viewport:
+        var xp = 2.0 * (Math.random() - 0.5) * (ar > 1 ? ar : 1);
+        var yp = 2.0 * (Math.random() - 0.5) * (ar > 1 ? 1 : 1 / ar);
+
+        if (Math.pow(distribution(xp, yp), (1.0 - settings.uniformity) * 2.0) > Math.random()) {
+          x[i++] = [xp, yp];
+        }
+      }
+      restart();
+    }
+
+    var drawPoints = regl({
+      vert: `
+        precision mediump float;
+        attribute vec2 xy;
+        attribute vec3 color;
+        uniform float size;
+        uniform vec2 aspect;
+        varying vec3 col;
+        void main () {
+          col = color;
+          gl_Position = vec4(xy * aspect, 0, 1);
+          gl_PointSize = size;
+        }
+      `,
+      frag: `
+        precision mediump float;
+        uniform float alpha;
+        varying vec3 col;
+        uniform float size;
+        void main () {
+          vec2 uv = gl_PointCoord - 0.5;
+          float r = length(uv) * size * 2.0;
+
+          gl_FragColor = vec4(col, alpha * smoothstep(size, size - 2.0, r));
+        }
+      `,
+      depth: {enable: false},
+      blend: {
+        enable: true,
+        func: {srcRGB: 'src alpha', srcAlpha: 1, dstRGB: 1, dstAlpha: 1},
+        equation: {rgb: 'reverse subtract', alpha: 'add'}
+      },
+      attributes: {
+        xy: regl.prop('xy'),
+        color: regl.prop('color')
+      },
+      uniforms: {
+        size: (ctx, props) => ctx.pixelRatio * props.size,
+        alpha: regl.prop('alpha'),
+        aspect: ctx => {
+          var w = ctx.viewportWidth;
+          var h = ctx.viewportHeight;
+          return w / h > 1 ? [h / w, 1] : [1, w / h];
+        }
+      },
+      primitive: 'points',
+      count: (ctx, props) => props.xy._buffer.byteLength / 8
+    });
+
+    panel([
+      {label: 'norm', type: 'range', min: 0.5, max: 4, step: 0.5, initial: settings.norm},
+      {label: 'k', type: 'range', min: 0, max: 100, step: 1, initial: settings.k},
+      {label: 'points', type: 'range', min: 1000, max: 20000, step: 100, initial: settings.points},
+      {label: 'uniformity', type: 'range', min: 0, max: 1, step: 0.1, initial: settings.uniformity},
+      {label: 'periodicity', type: 'range', min: 1, max: 10, step: 0.5, initial: settings.periodicity},
+      {label: 'kmpp', type: 'checkbox', initial: settings.kmpp},
+      {label: 'restart', type: 'button', action: restart}
+    ], {position: 'top-left', width: 350}).on('input', (data) => {
+      var needsInitialize = false;
+      var needsRestart = false;
+      if ((data.points !== settings.points) || (data.uniformity !== settings.uniformity) || (data.periodicity !== settings.periodicity)) {
+        needsInitialize = true;
+      } else if ((data.k !== settings.k) || (data.kmpp !== settings.kmpp)) {
+        needsRestart = true;
+      } else if (data.norm !== settings.norm) {
+        km.converged = false;
+      }
+      Object.assign(settings, data);
+      if (needsRestart) restart();
+      if (needsInitialize) initialize();
+    });
+
+    initialize();
+
+    window.addEventListener('resize', initialize, false);
+
+    iteration = 0;
+    regl.frame(({tick}) => {
+      if (km.converged) return;
+
+      iteration++;
+
+      km = kmpp(x, Object.assign({maxIterations: 1,
+        norm: settings.norm,
+        k: settings.k === 0 ? undefined : settings.k,
+        kmpp: settings.kmpp
+      }, km));
+
+      progress.textContent = km.converged ? ('converged after ' + iteration + ' iterations') : ('iteration: ' + iteration);
+
+      var colorList = new Array(km.centroids.length).fill(0).map((d, i) => hsl([i / km.centroids.length, 0.5, 0.5]));
+
+      pointColorBuf({data: km.assignments.map(i => colorList[i])});
+      centroidColorBuf({data: colorList});
+      pointBuf({data: x});
+      centroidBuf({data: km.centroids});
+
+      regl.clear({color: [1, 1, 1, 1]});
+
+      drawPoints({
+        xy: pointBuf,
+        size: 5,
+        color: pointColorBuf,
+        alpha: 0.25 * Math.sqrt(5000 / settings.points * window.innerWidth * window.innerHeight / 600 / 600)
+      });
+
+      drawPoints({
+        xy: centroidBuf,
+        size: 15,
+        color: centroidColorBuf,
+        alpha: 1.0
+      });
+    });
+  })
+});