New module @turf/clusters

packages/turf-clusters/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 TurfJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/turf-clusters/README.md

@@ -0,0 +1,50 @@
+# @turf/clusters
+
+# clusters
+
+Takes a set of {@link Point|points} and partition them into clusters using the k-mean.
+It uses the [k-means clustering](https://en.wikipedia.org/wiki/K-means_clustering) algorithm.
+
+**Parameters**
+-   `points` **[FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects)<[Point](http://geojson.org/geojson-spec.html#point)>** points to be clustered
+-   `numberOfClusters` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** number of clusters that will be generated (optional, default )
+
+**Examples**
+
+```javascript
+// create random points with random z-values in their properties
+var points = turf.random('point', 100, {
+  bbox: [0, 30, 20, 50]
+});
+var numberOfClusters = 7;
+var clustered = turf.clusters(points, numberOfClusters);
+//addToMap
+var addToMap = featureCollection(clustered.points);
+```
+
+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** containing a `points` [FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects)<[Point](http://geojson.org/geojson-spec.html#point)>, the input points where each [Point](http://geojson.org/geojson-spec.html#point) has given a `cluster` property with the cluster number it belongs, and a `centroids` [FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects)<[Point](http://geojson.org/geojson-spec.html#point)>, collecting all the cluster centroids each with its own `cluster` property
+
+<!-- This file is automatically generated. Please don't edit it directly:
+if you find an error, edit the source file (likely index.js), and re-run
+./scripts/generate-readmes in the turf project. -->
+
+---
+
+This module is part of the [Turfjs project](http://turfjs.org/), an open source
+module collection dedicated to geographic algorithms. It is maintained in the
+[Turfjs/turf](https://github.com/Turfjs/turf) repository, where you can create
+PRs and issues.
+
+### Installation
+
+Install this module individually:
+
+```sh
+$ npm install @turf/cluster
+```
+
+Or install the Turf module that includes it as a function:
+
+```sh
+$ npm install @turf/turf
+```

packages/turf-clusters/bench.js

@@ -0,0 +1,45 @@
+const fs = require('fs');
+const path = require('path');
+const load = require('load-json-file');
+const Benchmark = require('benchmark');
+const clusters = require('./');
+
+// Define Fixtures
+const directory = path.join(__dirname, 'test', 'in') + path.sep;
+const fixtures = fs.readdirSync(directory).map(filename => {
+    return {
+        filename,
+        name: path.parse(filename).name,
+        geojson: load.sync(directory + filename)
+    };
+});
+
+
+/**
+ * Benchmark Results
+ *
+ * fiji: 3.236ms
+ * many-points: 32.563ms
+ * points-with-properties: 0.123ms
+ * points1: 0.569ms
+ * points2: 0.119ms
+ * fiji x 112,975 ops/sec ±7.64% (70 runs sampled)
+ * many-points x 129 ops/sec ±20.10% (62 runs sampled)
+ * points-with-properties x 151,784 ops/sec ±4.47% (80 runs sampled)
+ * points1 x 44,736 ops/sec ±5.12% (77 runs sampled)
+ * points2 x 26,771 ops/sec ±4.22% (83 runs sampled)
+ */
+const suite = new Benchmark.Suite('turf-clusters');
+for (const {name, geojson} of fixtures) {
+    const {numberOfCentroids} = geojson.properties || {};
+
+    console.time(name);
+    clusters(geojson, numberOfCentroids);
+    console.timeEnd(name);
+    suite.add(name, () => clusters(geojson, numberOfCentroids));
+}
+suite
+  .on('cycle', e => console.log(String(e.target)))
+  .on('complete', () => {})
+  .run();
+

packages/turf-clusters/index.d.ts

@@ -0,0 +1,14 @@
+import {Points} from '@turf/helpers'
+
+interface Clustered {
+  points: Points
+  centroid: Points
+}
+
+/**
+ * http://turfjs.org/docs/#cluster
+ */
+declare function clusters(points: Points, numberOfClusters?: number): Clustered;
+
+declare namespace clusters { }
+export = clusters;

packages/turf-clusters/index.js

@@ -0,0 +1,63 @@
+var meta = require('@turf/meta');
+var skmeans = require('skmeans');
+var helpers = require('@turf/helpers');
+var invariant = require('@turf/invariant');
+var point = helpers.point;
+var coordEach = meta.coordEach;
+var featureEach = meta.featureEach;
+var collectionOf = invariant.collectionOf;
+var featureCollection = helpers.featureCollection;
+
+/**
+ * Takes a set of {@link Point|points} and partition them into clusters using the k-mean .
+ * It uses the [k-means algorithm](https://en.wikipedia.org/wiki/K-means_clustering)
+ *
+ * @name clusters
+ * @param {FeatureCollection<Point>} points to be clustered
+ * @param {number} [numberOfClusters=Math.sqrt(numberOfPoints/2)] numberOfClusters that will be generated
+ * @returns {Object} an object containing a `points` FeatureCollection, the input points where each Point
+ *     has given a `cluster` property with the cluster number it belongs, and a `centroids` FeatureCollection of
+ *     Points, collecting all the cluster centroids each with its own `cluster` property.
+ * @example
+ * // create random points with random z-values in their properties
+ * var points = turf.random('point', 100, {
+ *   bbox: [0, 30, 20, 50]
+ * });
+ * var numberOfClusters = 7;
+ * var clustered = turf.clusters(points, numberOfClusters);
+ *
+ * //addToMap
+ * var addToMap = featureCollection(clustered.points);
+ */
+module.exports = function (points, numberOfClusters) {
+    // Input validation
+    collectionOf(points, 'Point', 'Input must contain Points');
+    // Default Params
+    var count = points.features.length;
+    if (numberOfClusters > count) throw new Error('numberOfClusters can\'t be grated than the number of points');
+    numberOfClusters = numberOfClusters || Math.round(Math.sqrt(count / 2));
+
+    // collect points coordinates
+    var data = [];
+    coordEach(points, function (coord) {
+        data.push(coord);
+    });
+
+    // create seed to avoid skmeans to drift
+    var initialCentroids = data.slice(0, numberOfClusters);
+
+    // create clusters
+    var clastersResult = skmeans(data, numberOfClusters, initialCentroids);
+    var centroids = [];
+    clastersResult.centroids.forEach(function (coord, idx) {
+        centroids.push(point(coord, {cluster: idx}));
+    });
+    featureEach(points, function (pt, i) {
+        pt.properties.cluster = clastersResult.idxs[i];
+    });
+
+    return {
+        points: points,
+        centroids: featureCollection(centroids)
+    };
+};

packages/turf-clusters/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@turf/clusters",
+  "version": "4.4.0",
+  "description": "turf clusters module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "test": "node test.js",
+    "bench": "node bench.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/Turfjs/turf.git"
+  },
+  "keywords": [
+    "turf",
+    "geojson",
+    "cluster",
+    "clusters",
+    "clustering",
+    "k-means"
+  ],
+  "author": "Turf Authors",
+  "contributors": [
+    "Stefano Borghi <@stebogit>"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Turfjs/turf/issues"
+  },
+  "homepage": "https://github.com/Turfjs/turf",
+  "devDependencies": {
+    "@turf/random": "^4.4.0",
+    "benchmark": "^2.1.4",
+    "chromatism": "2.6.0",
+    "load-json-file": "^2.0.0",
+    "matrix-to-grid": "3.0.0",
+    "tape": "^4.6.3",
+    "write-json-file": "^2.0.0"
+  },
+  "dependencies": {
+    "@turf/helpers": "^4.4.0",
+    "@turf/invariant": "^4.4.0",
+    "@turf/meta": "^4.4.0",
+    "skmeans": "0.5.0"
+  }
+}

packages/turf-clusters/test.js

@@ -0,0 +1,75 @@
+const fs = require('fs');
+const test = require('tape');
+const path = require('path');
+const load = require('load-json-file');
+const write = require('write-json-file');
+const {featureEach} = require('@turf/meta');
+const {featureCollection, point, polygon} = require('@turf/helpers');
+const chromatism = require('chromatism');
+const clusters = require('./');
+
+const directories = {
+    in: path.join(__dirname, 'test', 'in') + path.sep,
+    out: path.join(__dirname, 'test', 'out') + path.sep
+};
+
+const fixtures = fs.readdirSync(directories.in).map(filename => {
+    return {
+        filename,
+        name: path.parse(filename).name,
+        geojson: load.sync(directories.in + filename)
+    };
+});
+
+test('clusters', t => {
+    fixtures.forEach(({name, geojson}) => {
+        const {numberOfCentroids} = geojson.properties || {};
+
+        const clustered = clusters(geojson, numberOfCentroids);
+        const result = featureCollection(colorize(clustered));
+
+        if (process.env.REGEN) write.sync(directories.out + name + '.geojson', result);
+        t.deepEqual(result, load.sync(directories.out + name + '.geojson'), name);
+    });
+
+    t.end();
+});
+
+const points = featureCollection([
+    point([0, 0], {foo: 'bar'}),
+    point([2, 4], {foo: 'bar'}),
+    point([3, 6], {foo: 'bar'})
+]);
+
+test('clusters -- throws', t => {
+    const poly = polygon([[[0, 0], [10, 10], [0, 10], [0, 0]]]);
+    t.throws(() => clusters(poly, 1), /Input must contain Points/);
+    t.throws(() => clusters(points, 5), /numberOfClusters can't be grated than the number of points/);
+    t.end();
+});
+
+test('clusters -- translate properties', t => {
+    t.equal(clusters(points, 2).points.features[0].properties.foo, 'bar');
+    t.end();
+});
+
+// style result
+function colorize(clustered) {
+    const count = clustered.centroids.features.length;
+    const colours = chromatism.adjacent(360 / count, count, '#0000FF').hex;
+    const points = [];
+    featureEach(clustered.points, function (point) {
+        point.properties['marker-color'] = colours[point.properties.cluster];
+        point.properties['marker-size'] = 'small';
+        points.push(point);
+    });
+    featureEach(clustered.centroids, function (centroid) {
+        const color = chromatism.brightness(-25, colours[centroid.properties.cluster]).hex;
+        centroid.properties['marker-color'] = color;
+        centroid.properties['marker-symbol'] = 'star-stroked';
+        centroid.properties['marker-size'] = 'large';
+        centroid.properties['marker-size'] = 'large';
+        points.push(centroid);
+    });
+    return points;
+}

packages/turf-clusters/test/in/fiji.geojson

@@ -0,0 +1,71 @@
+{
+	"type": "FeatureCollection",
+	"features": [
+		{
+			"type": "Feature",
+			"properties": {},
+			"geometry": {
+				"type": "Point",
+				"coordinates": [
+					179.439697265625,
+					-16.55196172197251
+				]
+			}
+		},
+		{
+			"type": "Feature",
+			"properties": {},
+			"geometry": {
+				"type": "Point",
+				"coordinates": [
+					179.01123046874997,
+					-16.97274101999901
+				]
+			}
+		},
+		{
+			"type": "Feature",
+			"properties": {},
+			"geometry": {
+				"type": "Point",
+				"coordinates": [
+					179.505615234375,
+					-17.035777250427184
+				]
+			}
+		},
+		{
+			"type": "Feature",
+			"properties": {},
+			"geometry": {
+				"type": "Point",
+				"coordinates": [
+					180.75805664062497,
+					-16.41500926733237
+				]
+			}
+		},
+		{
+			"type": "Feature",
+			"properties": {},
+			"geometry": {
+				"type": "Point",
+				"coordinates": [
+					181.1865234375,
+					-16.615137799987075
+				]
+			}
+		},
+		{
+			"type": "Feature",
+			"properties": {},
+			"geometry": {
+				"type": "Point",
+				"coordinates": [
+					181.03271484375,
+					-16.277960306212513
+				]
+			}
+		}
+	]
+}