@thi.ng/k-means 1.0.22 → 1.1.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-05-28T12:02:40Z
+- **Last updated**: 2025-06-14T20:56:27Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,14 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [1.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/k-means@1.1.0) (2025-06-14)
+
+#### 🚀 Features
+
+- update initKmeanspp(), add configurable distance exponent ([2aed319](https://github.com/thi-ng/umbrella/commit/2aed319))
+  - add KMeansOpts.exponent
+  - update doc strings
+
 ### [0.7.10](https://github.com/thi-ng/umbrella/tree/@thi.ng/k-means@0.7.10) (2024-10-05)
 
 #### ♻️ Refactoring

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 208 standalone projects, maintained as part
+> This is one of 209 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -59,7 +59,7 @@ For Node.js REPL:
 const kmeans = await import("@thi.ng/k-means");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 884 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 898 bytes
 
 ## Dependencies
 

package/api.d.ts

@@ -13,6 +13,10 @@ export interface KMeansOpts {
      * Distance function/metric to use for finding nearest centroid.
      */
     dist: IDistance<ReadonlyVec>;
+    /**
+     * Sample dimensions. If omitted uses length of first sample vector.
+     */
+    dim: number;
     /**
      * Max. iteration count
      */
@@ -25,6 +29,15 @@ export interface KMeansOpts {
      * Centroid refinement strategy (default: {@link means}).
      */
     strategy: CentroidStrategy;
+    /**
+     * Only used if no {@link KMeansOpts.initial} is given and the
+     * {@link initKmeanspp} default is used. There the `exponent` is applied to
+     * scale the distances to nearest centroid, which will be used to control
+     * the weight distribution for choosing next centroid. A higher exponent
+     * means that points with larger distances will be more prioritized in the
+     * random selection.
+     */
+    exponent: number;
 }
 /**
  * k-means initialization function, e.g. {@link initKmeanspp}.

package/kmeans.d.ts

@@ -24,6 +24,11 @@ export declare const kmeans: <T extends ReadonlyVec>(k: number, samples: T[], op
  * fulfilled (e.g. due to lower number of samples and/or distance metric).
  * Throws an error if `samples` are empty.
  *
+ * The optional `exponent` (default: 2) is applied to scale the distances to
+ * nearest centroid, which will be used to control the weight distribution for
+ * choosing next centroid. A higher exponent means that points with larger
+ * distances will be more prioritized in the random selection.
+ *
  * References:
  *
  * - https://en.wikipedia.org/wiki/K-means%2B%2B
@@ -34,8 +39,9 @@ export declare const kmeans: <T extends ReadonlyVec>(k: number, samples: T[], op
  * @param samples -
  * @param dist -
  * @param rnd -
+ * @param exponent -
  */
-export declare const initKmeanspp: <T extends ReadonlyVec>(k: number, samples: T[], dist?: IDistance<ReadonlyVec>, rnd?: IRandom) => number[];
+export declare const initKmeanspp: <T extends ReadonlyVec>(k: number, samples: T[], dist?: IDistance<ReadonlyVec>, rnd?: IRandom, exponent?: number) => number[];
 /**
  * Default centroid strategy forming new centroids by averaging the position of
  * participating samples.

package/kmeans.js

@@ -7,16 +7,18 @@ import { add } from "@thi.ng/vectors/add";
 import { median } from "@thi.ng/vectors/median";
 import { mulN } from "@thi.ng/vectors/muln";
 import { zeroes } from "@thi.ng/vectors/setn";
-const kmeans = (k, samples, opts) => {
-  let { dist, initial, maxIter, rnd, strategy } = {
-    dist: DIST_SQ,
-    maxIter: 32,
-    strategy: means,
-    ...opts
-  };
+const kmeans = (k, samples, opts = {}) => {
+  let {
+    dim = samples[0].length,
+    dist = DIST_SQ,
+    maxIter = 32,
+    strategy = means,
+    exponent,
+    initial,
+    rnd
+  } = opts;
   const num = samples.length;
-  const dim = samples[0].length;
-  const centroidIDs = Array.isArray(initial) ? initial : initial ? initial(k, samples, dist, rnd) : initKmeanspp(k, samples, dist, rnd);
+  const centroidIDs = Array.isArray(initial) ? initial : initial ? initial(k, samples, dist, rnd) : initKmeanspp(k, samples, dist, rnd, exponent);
   assert(centroidIDs.length > 0, `missing initial centroids`);
   k = centroidIDs.length;
   const centroids = centroidIDs.map((i) => samples[i]);
@@ -36,7 +38,7 @@ const kmeans = (k, samples, opts) => {
   }
   return __buildClusters(centroids, clusters);
 };
-const initKmeanspp = (k, samples, dist = DIST_SQ, rnd = SYSTEM) => {
+const initKmeanspp = (k, samples, dist = DIST_SQ, rnd = SYSTEM, exponent = 2) => {
   const num = samples.length;
   assert(num > 0, `missing samples`);
   k = Math.min(k, num);
@@ -47,7 +49,7 @@ const initKmeanspp = (k, samples, dist = DIST_SQ, rnd = SYSTEM) => {
   while (centroidIDs.length < k) {
     let psum = 0;
     const probs = samples.map((p) => {
-      const d = dist.from(metric(p, centroids[argmin(p, centroids, dist)])) ** 2;
+      const d = dist.from(metric(p, centroids[argmin(p, centroids, dist)])) ** exponent;
       psum += d;
       return d;
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/k-means",
-  "version": "1.0.22",
+  "version": "1.1.0",
   "description": "Configurable k-means & k-medians (with k-means++ initialization) for n-D vectors",
   "type": "module",
   "module": "./index.js",
@@ -39,11 +39,11 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.28",
-    "@thi.ng/distance": "^2.4.120",
-    "@thi.ng/errors": "^2.5.34",
-    "@thi.ng/random": "^4.1.19",
-    "@thi.ng/vectors": "^8.2.1"
+    "@thi.ng/api": "^8.11.29",
+    "@thi.ng/distance": "^3.0.0",
+    "@thi.ng/errors": "^2.5.35",
+    "@thi.ng/random": "^4.1.20",
+    "@thi.ng/vectors": "^8.3.0"
   },
   "devDependencies": {
     "esbuild": "^0.25.5",
@@ -87,5 +87,5 @@
     "year": 2021,
     "screenshot": "examples/kmeans-viz.jpg"
   },
-  "gitHead": "61c3833b7ef7d044621454b5ea4af885d39f065e\n"
+  "gitHead": "14e994e531d32053e948768998324d443436a542\n"
 }