@turf/clusters-kmeans

What is @turf/clusters-kmeans?

@turf/clusters-kmeans is a module from the Turf.js library that provides functionality for clustering geographical points using the K-means algorithm. This is particularly useful for spatial analysis and geographic data visualization.

What are @turf/clusters-kmeans's main functionalities?

Basic K-means Clustering

This feature allows you to perform K-means clustering on a set of geographical points. The code sample demonstrates how to cluster six points into two clusters.

const turf = require('@turf/turf');
const points = turf.featureCollection([
  turf.point([0, 0]),
  turf.point([2, 2]),
  turf.point([3, 3]),
  turf.point([8, 8]),
  turf.point([8, 9]),
  turf.point([7, 8])
]);
const clustered = turf.clustersKmeans(points, {numberOfClusters: 2});
console.log(clustered);

Custom Number of Clusters

This feature allows you to specify the number of clusters you want to create. The code sample demonstrates clustering the same six points into three clusters.

const turf = require('@turf/turf');
const points = turf.featureCollection([
  turf.point([0, 0]),
  turf.point([2, 2]),
  turf.point([3, 3]),
  turf.point([8, 8]),
  turf.point([8, 9]),
  turf.point([7, 8])
]);
const clustered = turf.clustersKmeans(points, {numberOfClusters: 3});
console.log(clustered);

Cluster Properties

This feature allows you to retain and inspect the properties of the original points after clustering. The code sample demonstrates how to cluster points and then log the properties of each clustered point.

const turf = require('@turf/turf');
const points = turf.featureCollection([
  turf.point([0, 0], {name: 'A'}),
  turf.point([2, 2], {name: 'B'}),
  turf.point([3, 3], {name: 'C'}),
  turf.point([8, 8], {name: 'D'}),
  turf.point([8, 9], {name: 'E'}),
  turf.point([7, 8], {name: 'F'})
]);
const clustered = turf.clustersKmeans(points, {numberOfClusters: 2});
console.log(clustered.features.map(f => f.properties));

Other packages similar to @turf/clusters-kmeans

kmeans-js

kmeans-js is a simple JavaScript implementation of the K-means clustering algorithm. Unlike @turf/clusters-kmeans, it is not specifically designed for geographical data but can be used for general clustering tasks.

ml-kmeans

ml-kmeans is a machine learning library for Node.js that provides K-means clustering. It is more general-purpose compared to @turf/clusters-kmeans and can be used for a variety of data types, not just geographical points.

simple-statistics

simple-statistics is a JavaScript library that provides a variety of statistical methods, including K-means clustering. It is a more comprehensive library for statistical analysis compared to @turf/clusters-kmeans, which is focused on geographical data.

README

@turf/clusters-kmeans

clustersKmeans

Takes a set of points and partition them into clusters using the k-mean . It uses the k-means algorithm

Parameters

• points FeatureCollection<Point> to be clustered
• options Object Optional parameters (optional, default {})
  • options.numberOfClusters number numberOfClusters that will be generated (optional, default Math.sqrt(numberOfPoints/2))
  • options.mutate boolean allows GeoJSON input to be mutated (significant performance increase if true) (optional, default false)

Examples

// create random points with random z-values in their properties
var points = turf.randomPoint(100, {bbox: [0, 30, 20, 50]});
var options = {numberOfClusters: 7};
var clustered = turf.clustersKmeans(points, options);

//addToMap
var addToMap = [clustered];

Returns FeatureCollection<Point> Clustered Points with an additional two properties associated to each Feature:- {number} cluster - the associated clusterId

• {[number, number]} centroid - Centroid of the cluster [Longitude, Latitude]

---

This module is part of the Turfjs project, an open source module collection dedicated to geographic algorithms. It is maintained in the Turfjs/turf repository, where you can create PRs and issues.

Installation

Install this module individually:

$ npm install @turf/clusters-kmeans

Or install the Turf module that includes it as a function:

$ npm install @turf/turf

Changelog

6.5.0

🏅 New Features/Enhancements

• @turf/points-with-polygon Add MultiPoint support (PR https://github.com/Turfjs/turf/pull/2137 - Author @twelch)

🐛 Bug Fixes

• @turf/dissolve Complete rewrite of the dissolve module to resolve many bugs (PR https://github.com/Turfjs/turf/pull/2110 - Author @rowanwins)

• @turf/mask Complete rewrite of the mask module to resolve many bugs (PR https://github.com/Turfjs/turf/pull/2130 - Author @rowanwins)

• @turf/boolean-valid Add missing dependency to (PR https://github.com/Turfjs/turf/pull/2094 - Author @rycgar)

📖 Documentation

• @turf/boolean-overlap Improve clarity (PR https://github.com/Turfjs/turf/pull/2133 - Author @patrickbrett)

🔔 Misc

• Enable TS Strict Mode (PR https://github.com/Turfjs/turf/pull/2126 - Author @mfedderly)