![\"Zakodium](\"https://www.zakodium.com/brand/zakodium-logo-white.svg\"){kind=logo}
\n \n\n \n \n\n \n Maintained by Zakodium\n
\n\n[](https://www.npmjs.com/package/ml-kmeans)\n[](https://www.npmjs.com/package/ml-kmeans)\n[](https://codecov.io/gh/mljs/kmeans)\n[](https://github.com/mljs/kmeans/blob/main/LICENSE)\n\n\n\n## Installation\n\n`npm i ml-kmeans`\n\n## [API Documentation](https://mljs.github.io/kmeans/)\n\n## Usage\n\n```js\nimport { kmeans } from 'ml-kmeans';\n\nconst data = [\n [1, 1, 1],\n [1, 2, 1],\n [-1, -1, -1],\n [-1, -1, -1.5],\n];\nconst centers = [\n [1, 2, 1],\n [-1, -1, -1],\n];\n\nconst ans = kmeans(data, 2, { initialization: centers });\nconsole.log(ans);\n/*\nKMeansResult {\n clusters: [ 0, 0, 1, 1 ],\n centroids: [ [ 1, 1.5, 1 ], [ -1, -1, -1.25 ] ],\n converged: true,\n iterations: 2,\n distance: [Function: squaredEuclidean]\n}\n*/\n\n// Compute the mean error and size of each cluster.\nconsole.log(ans.computeInformation(data));\n/*\n[\n { centroid: [ 1, 1.5, 1 ], error: 0.25, size: 2 },\n { centroid: [ -1, -1, -1.25 ], error: 0.0625, size: 2 }\n]\n*/\n\n// Assign new points to the clusters found above.\nconsole.log(ans.nearest([[1, 2, 1]]));\n// [ 0 ]\n```\n\n## API\n\n### `kmeans(data, k, options)`\n\nRuns the K-means algorithm and returns a `KMeansResult`.\n\n- `data`: array of points to cluster, each in the format `[x, y, z, ...]`.\n- `k`: number of clusters.\n- `options`: an optional object with the following properties.\n\n| Option | Type | Default | Description |\n| ------------------ | -------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `initialization` | `string` or `number[][]` | `'kmeans++'` | Either custom start centroids (`[x, y, z, ...]`), or one of the methods `'kmeans++'`, `'random'`, or `'mostDistant'`. |\n| `maxIterations` | `number` | `100` | Maximum number of iterations allowed. Set to `0` to iterate until convergence. |\n| `tolerance` | `number` | `1e-6` | Error tolerance used as the convergence criterion. |\n| `distanceFunction` | `(p, q) => number` | `squaredEuclidean` | Distance function to use between two points. |\n| `seed` | `number` | _(none)_ | Seed for the random number generator, used by the `'random'` and `'mostDistant'` initialization methods to make results reproducible. |\n\n#### Initialization methods\n\n- `'kmeans++'`: uses the [kmeans++][] seeding method.\n- `'random'`: chooses `k` random distinct points.\n- `'mostDistant'`: chooses the most distant points starting from a first random pick.\n\n### `KMeansResult`\n\nThe object returned by `kmeans`.\n\n- `clusters`: array with the cluster index of each input point.\n- `centroids`: array with the resulting centroids.\n- `converged`: whether the convergence criterion was satisfied.\n- `iterations`: number of iterations performed.\n- `result.nearest(points)`: returns the cluster index of each of the given new `points`.\n- `result.computeInformation(data)`: returns the `centroid`, mean `error`, and `size` of each cluster.\n\n### `kmeansGenerator(data, k, options)`\n\nGenerator variant of `kmeans` that yields the `KMeansResult` of each iteration, which is useful to observe the algorithm step by step.\n\n## Authors\n\n- [Miguel Asencio](https://github.com/maasencioh)\n\n## Sources\n\nD. Arthur, S. Vassilvitskii, k-means++: The Advantages of Careful Seeding, in: Proc. of the 18th Annual\nACM-SIAM Symposium on Discrete Algorithms, 2007, pp. 1027–1035.\n[Link to article](http://ilpubs.stanford.edu:8090/778/1/2006-13.pdf)\n\n## License\n\n[MIT](./LICENSE)\n\n[k-means clustering]: https://en.wikipedia.org/wiki/K-means_clustering\n[kmeans++]: http://ilpubs.stanford.edu:8090/778/1/2006-13.pdf\n","readmeFilename":"README.md","users":{"rholdren":true,"kkk123321":true,"maasencioh":true}}