New @turf/clusters module (getCluster, clusterEach, clusterReduce)

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,201 @@
+# @turf/clusters
+
+# getCluster
+
+Get Cluster
+
+**Parameters**
+
+-   `geojson` **[FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects)** GeoJSON Features
+-   `filter` **Any** Filter used on GeoJSON properties to get Cluster
+
+**Examples**
+
+```javascript
+var geojson = turf.featureCollection([
+    turf.point([0, 0], {'marker-symbol': 'circle'}),
+    turf.point([2, 4], {'marker-symbol': 'star'}),
+    turf.point([3, 6], {'marker-symbol': 'star'}),
+    turf.point([5, 1], {'marker-symbol': 'square'}),
+    turf.point([4, 2], {'marker-symbol': 'circle'})
+]);
+
+// Create a cluster using K-Means (adds `cluster` to GeoJSON properties)
+var clustered = turf.clustersKmeans(geojson);
+
+// Retrieve first cluster (0)
+var cluster = turf.getCluster(clustered, {cluster: 0});
+//= cluster
+
+// Retrieve cluster based on custom properties
+turf.getCluster(clustered, {'marker-symbol': 'circle'}).length;
+//= 2
+turf.getCluster(clustered, {'marker-symbol': 'square'}).length;
+//= 1
+```
+
+Returns **[FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects)** Single Cluster filtered by GeoJSON Properties
+
+# clusterEachCallback
+
+Callback for clusterEach
+
+**Parameters**
+
+-   `cluster` **\[[FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects)]** The current cluster being processed.
+-   `clusterValue` **\[Any]** Value used to create cluster being processed.
+-   `currentIndex` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** The index of the current element being processed in the array.Starts at index 0
+-   `geojson`  
+-   `property`  
+-   `callback`  
+
+Returns **void** 
+
+# clusterEach
+
+clusterEach
+
+**Parameters**
+
+-   `geojson` **[FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects)** GeoJSON Features
+-   `property` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** GeoJSON property key/value used to create clusters
+-   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a method that takes (cluster, clusterValue, currentIndex)
+
+**Examples**
+
+```javascript
+var geojson = turf.featureCollection([
+    turf.point([0, 0]),
+    turf.point([2, 4]),
+    turf.point([3, 6]),
+    turf.point([5, 1]),
+    turf.point([4, 2])
+]);
+
+// Create a cluster using K-Means (adds `cluster` to GeoJSON properties)
+var clustered = turf.clustersKmeans(geojson);
+
+// Iterate over each cluster
+clusterEach(clustered, 'cluster', function (cluster, clusterValue, currentIndex) {
+    //= cluster
+    //= clusterValue
+    //= currentIndex
+})
+
+// Calculate the total number of clusters
+var total = 0
+turf.clusterEach(clustered, 'cluster', function () {
+    total++;
+});
+
+// Create an Array of all the values retrieved from the 'cluster' property
+var values = []
+turf.clusterEach(clustered, 'cluster', function (cluster, clusterValue) {
+    values.push(clusterValue);
+});
+```
+
+Returns **void** 
+
+# clusterReduceCallback
+
+Callback for clusterReduce
+
+The first time the callback function is called, the values provided as arguments depend
+on whether the reduce method has an initialValue argument.
+
+If an initialValue is provided to the reduce method:
+
+-   The previousValue argument is initialValue.
+-   The currentValue argument is the value of the first element present in the array.
+
+If an initialValue is not provided:
+
+-   The previousValue argument is the value of the first element present in the array.
+-   The currentValue argument is the value of the second element present in the array.
+
+**Parameters**
+
+-   `previousValue` **\[Any]** The accumulated value previously returned in the last invocation
+    of the callback, or initialValue, if supplied.
+-   `cluster` **\[[FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects)]** The current cluster being processed.
+-   `clusterValue` **\[Any]** Value used to create cluster being processed.
+-   `currentIndex` **\[[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)]** The index of the current element being processed in the
+    array. Starts at index 0, if an initialValue is provided, and at index 1 otherwise.
+-   `geojson`  
+-   `property`  
+-   `callback`  
+-   `initialValue`  
+
+# clusterReduce
+
+Reduce clusters in GeoJSON Features, similar to Array.reduce()
+
+**Parameters**
+
+-   `geojson` **[FeatureCollection](http://geojson.org/geojson-spec.html#feature-collection-objects)** GeoJSON Features
+-   `property` **([string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) \| [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number))** GeoJSON property key/value used to create clusters
+-   `callback` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** a method that takes (previousValue, cluster, clusterValue, currentIndex)
+-   `initialValue` **\[Any]** Value to use as the first argument to the first call of the callback.
+
+**Examples**
+
+```javascript
+var geojson = turf.featureCollection([
+    turf.point([0, 0]),
+    turf.point([2, 4]),
+    turf.point([3, 6]),
+    turf.point([5, 1]),
+    turf.point([4, 2])
+]);
+
+// Create a cluster using K-Means (adds `cluster` to GeoJSON properties)
+var clustered = turf.clustersKmeans(geojson);
+
+// Iterate over each cluster and perform a calculation
+var initialValue = 0
+turf.clusterReduce(clustered, 'cluster', function (previousValue, cluster, clusterValue, currentIndex) {
+    //=previousValue
+    //=cluster
+    //=clusterValue
+    //=currentIndex
+    return previousValue++;
+}, initialValue);
+
+// Calculate the total number of clusters
+var total = turf.clusterReduce(clustered, 'cluster', function (previousValue) {
+    return previousValue++;
+}, 0);
+
+// Create an Array of all the values retrieved from the 'cluster' property
+var values = turf.clusterReduce(clustered, 'cluster', function (previousValue, cluster, clusterValue) {
+    return previousValue.push(clusterValue);
+}, []);
+```
+
+Returns **Any** The value that results from the reduction.
+
+<!-- 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/clusters
+```
+
+Or install the Turf module that includes it as a function:
+
+```sh
+$ npm install @turf/turf
+```

packages/turf-clusters/bench.js

@@ -0,0 +1,46 @@
+const Benchmark = require('benchmark');
+const {featureCollection, point} = require('@turf/helpers');
+const {getCluster, clusterEach, clusterReduce} = require('./');
+const {propertiesContainsFilter, filterProperties, applyFilter, createBins} = require('./'); // Testing Purposes
+
+const geojson = featureCollection([
+    point([0, 0], {cluster: 0}),
+    point([2, 4], {cluster: 1}),
+    point([3, 6], {cluster: 1}),
+    point([5, 1], {0: 'foo'}),
+    point([4, 2], {'bar': 'foo'}),
+    point([2, 4], {}),
+    point([4, 3], undefined)
+]);
+
+/**
+ * Benchmark Results
+ *
+ * testing -- createBins x 1,909,730 ops/sec ±2.70% (83 runs sampled)
+ * testing -- propertiesContainsFilter x 10,378,738 ops/sec ±2.63% (86 runs sampled)
+ * testing -- filterProperties x 26,212,665 ops/sec ±2.49% (85 runs sampled)
+ * testing -- applyFilter x 21,368,185 ops/sec ±2.71% (84 runs sampled)
+ * getCluster -- string filter x 3,051,513 ops/sec ±1.83% (84 runs sampled)
+ * getCluster -- object filter x 673,824 ops/sec ±2.20% (86 runs sampled)
+ * getCluster -- aray filter x 2,284,972 ops/sec ±1.90% (86 runs sampled)
+ * clusterEach x 890,683 ops/sec ±1.48% (87 runs sampled)
+ * clusterReduce x 837,383 ops/sec ±1.93% (87 runs sampled)
+ */
+const suite = new Benchmark.Suite('turf-clusters');
+
+// Testing Purposes
+suite
+  .add('testing -- createBins', () => createBins(geojson, 'cluster'))
+  .add('testing -- propertiesContainsFilter', () => propertiesContainsFilter({foo: 'bar', cluster: 0}, {cluster: 0}))
+  .add('testing -- filterProperties', () => filterProperties({foo: 'bar', cluster: 0}, ['cluster']))
+  .add('testing -- applyFilter', () => applyFilter({foo: 'bar', cluster: 0}, ['cluster']));
+
+suite
+  .add('getCluster -- string filter', () => getCluster(geojson, 'cluster'))
+  .add('getCluster -- object filter', () => getCluster(geojson, {cluster: 1}))
+  .add('getCluster -- aray filter', () => getCluster(geojson, ['cluster']))
+  .add('clusterEach', () => clusterEach(geojson, 'cluster', cluster => { return cluster; }))
+  .add('clusterReduce', () => clusterReduce(geojson, 'cluster', (previousValue, cluster) => { return cluster; }))
+  .on('cycle', e => console.log(String(e.target)))
+  .on('complete', () => {})
+  .run();

packages/turf-clusters/index.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="geojson" />
+
+type FeatureCollection<T extends GeoJSON.GeometryObject> = GeoJSON.FeatureCollection<T>;
+type Feature<T extends GeoJSON.GeometryObject> = GeoJSON.Feature<T>;
+type GeometryObject = GeoJSON.GeometryObject;
+
+/**
+ * http://turfjs.org/docs/#getcluster
+ */
+export function getCluster<T extends GeometryObject>(
+    geojson: FeatureCollection<T>,
+    filter: any
+): FeatureCollection<T>;
+
+/**
+ * http://turfjs.org/docs/#clustereach
+ */
+export function clusterEach<T extends GeometryObject>(
+    geojson: FeatureCollection<T>,
+    property: number | string,
+    callback: (cluster?: FeatureCollection<T>, clusterValue?: any, currentIndex?: number) => void
+): void;
+
+/**
+ * http://turfjs.org/docs/#clusterreduce
+ */
+export function clusterReduce<T extends GeometryObject>(
+    geojson: FeatureCollection<T>,
+    property: number | string,
+    callback: (previousValue?: any, cluster?: FeatureCollection<T>, clusterValue?: any, currentIndex?: number) => void,
+    initialValue: any
+): void;