@thi.ng/k-means 1.1.1 → 2.0.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-06-14T20:56:27Z
+- **Last updated**: 2025-07-10T14:20:23Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,20 @@ 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.
 
+# [2.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/k-means@2.0.0) (2025-06-24)
+
+#### 🛑 Breaking changes
+
+- update KMeansInit & kmeansPlusPlus() ([58d7eb1](https://github.com/thi-ng/umbrella/commit/58d7eb1))
+- BREAKING CHANGE: update `KMeansInit` to return vectors not IDs
+  - update `KMeansInit` return type
+  - update `KMeansOpts.initial`
+  - rename `initKmeanspp()` => `kmeansPlusPlus()`
+
+#### 🚀 Features
+
+- add meanCut/medianCut() ([867889d](https://github.com/thi-ng/umbrella/commit/867889d))
+
 ## [1.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/k-means@1.1.0) (2025-06-14)
 
 #### 🚀 Features

package/README.md

@@ -25,7 +25,16 @@
 
 ## About
 
-Configurable k-means & k-medians (with k-means++ initialization) for n-D vectors.
+k-means & k-medians with customizable distance functions and centroid initializations for n-D vectors.
+
+In addition to the main
+[`kmeans()`](https://docs.thi.ng/umbrella/k-means/functions/kmeans.html)
+implementation, the following k-means centroid initialization functions are
+provided (can also be used in isolation to extract cluster centroids):
+
+- [`kmeansPlusPlus()`](https://docs.thi.ng/umbrella/k-means/functions/kmeansPlusPlus.html)
+- [`meanCut()`](https://docs.thi.ng/umbrella/k-means/functions/meanCut.html)
+- [`medianCut()`](https://docs.thi.ng/umbrella/k-means/functions/medianCut.html)
 
 ## Status
 
@@ -59,7 +68,7 @@ For Node.js REPL:
 const kmeans = await import("@thi.ng/k-means");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 898 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 1.10 KB
 
 ## Dependencies
 

package/api.d.ts

@@ -8,7 +8,7 @@ export interface KMeansOpts {
      * array given to {@link kmeans}) or a function producing such. If omitted,
      * {@link initKmeanspp} is used as default.
      */
-    initial: number[] | KMeansInit<ReadonlyVec>;
+    initial: ReadonlyVec[] | KMeansInit;
     /**
      * Distance function/metric to use for finding nearest centroid.
      */
@@ -42,7 +42,7 @@ export interface KMeansOpts {
 /**
  * k-means initialization function, e.g. {@link initKmeanspp}.
  */
-export type KMeansInit<T extends ReadonlyVec> = (k: number, samples: T[], dist?: IDistance<ReadonlyVec>, rnd?: IRandom) => number[];
+export type KMeansInit = (k: number, samples: ReadonlyVec[], dist?: IDistance<ReadonlyVec>, rnd?: IRandom) => ReadonlyVec[];
 export type CentroidStrategy = Fn<number, {
     update: Fn<ReadonlyVec, void>;
     finish: Fn0<Maybe<Vec>>;

package/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./api.js";
 export * from "./kmeans.js";
+export * from "./mean-cut.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,2 +1,3 @@
 export * from "./api.js";
 export * from "./kmeans.js";
+export * from "./mean-cut.js";

package/kmeans.d.ts

@@ -41,7 +41,7 @@ export declare const kmeans: <T extends ReadonlyVec>(k: number, samples: T[], op
  * @param rnd -
  * @param exponent -
  */
-export declare const initKmeanspp: <T extends ReadonlyVec>(k: number, samples: T[], dist?: IDistance<ReadonlyVec>, rnd?: IRandom, exponent?: number) => number[];
+export declare const kmeansPlusPlus: <T extends ReadonlyVec>(k: number, samples: T[], dist?: IDistance<ReadonlyVec>, rnd?: IRandom, exponent?: number) => T[];
 /**
  * Default centroid strategy forming new centroids by averaging the position of
  * participating samples.

package/kmeans.js

@@ -18,10 +18,9 @@ const kmeans = (k, samples, opts = {}) => {
     rnd
   } = opts;
   const num = samples.length;
-  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]);
+  const centroids = Array.isArray(initial) ? initial : initial ? initial(k, samples, dist, rnd) : kmeansPlusPlus(k, samples, dist, rnd, exponent);
+  assert(centroids.length > 0, `missing initial centroids`);
+  k = centroids.length;
   const clusters = new Uint32Array(num).fill(k);
   let update = true;
   while (update && maxIter-- > 0) {
@@ -38,7 +37,7 @@ const kmeans = (k, samples, opts = {}) => {
   }
   return __buildClusters(centroids, clusters);
 };
-const initKmeanspp = (k, samples, dist = DIST_SQ, rnd = SYSTEM, exponent = 2) => {
+const kmeansPlusPlus = (k, samples, dist = DIST_SQ, rnd = SYSTEM, exponent = 2) => {
   const num = samples.length;
   assert(num > 0, `missing samples`);
   k = Math.min(k, num);
@@ -61,7 +60,7 @@ const initKmeanspp = (k, samples, dist = DIST_SQ, rnd = SYSTEM, exponent = 2) =>
     centroidIDs.push(id);
     centroids.push(samples[id]);
   }
-  return centroidIDs;
+  return centroids;
 };
 const __assign = (samples, centroids, assignments, dist) => {
   let update = false;
@@ -124,8 +123,8 @@ const meansLatLon = () => {
   };
 };
 export {
-  initKmeanspp,
   kmeans,
+  kmeansPlusPlus,
   means,
   meansLatLon,
   medians

package/mean-cut.d.ts

@@ -0,0 +1,29 @@
+import type { Fn } from "@thi.ng/api";
+import type { ReadonlyVec } from "@thi.ng/vectors";
+/**
+ * Mean-cut clustering, also usable as {@link kmeans} /
+ * {@link KMeansOpts.initial} centroid initialization. Returns up to `k`
+ * centroids for given `samples`.
+ *
+ * @remarks
+ * Only recommended for low-dimensional data.
+ *
+ * @param k
+ * @param samples
+ */
+export declare const meanCut: <T extends ReadonlyVec>(k: number, samples: T[]) => import("@thi.ng/vectors").Vec<number>[];
+/**
+ * Median-cut clustering, also usable as {@link kmeans} /
+ * {@link KMeansOpts.initial} centroid initialization. Returns up to `k`
+ * centroids for given `samples`.
+ *
+ * @remarks
+ * Only recommended for low-dimensional data.
+ *
+ * @param k
+ * @param samples
+ */
+export declare const medianCut: <T extends ReadonlyVec>(k: number, samples: T[]) => import("@thi.ng/vectors").Vec<number>[];
+/** @internal */
+export declare const computeCutWith: (cut: Fn<ReadonlyVec, number>, samples: ReadonlyVec[], dim: number, depth: number) => ReadonlyVec[][];
+//# sourceMappingURL=mean-cut.d.ts.map

package/mean-cut.js

@@ -0,0 +1,44 @@
+import { mean, vmean } from "@thi.ng/vectors/mean";
+import { vmedian } from "@thi.ng/vectors/median";
+const meanCut = (k, samples) => computeCutWith(vmean, samples, samples[0].length, k).map(
+  (x) => mean([], x)
+);
+const medianCut = (k, samples) => computeCutWith(vmedian, samples, samples[0].length, k).map(
+  (x) => mean([], x)
+);
+const computeCutWith = (cut, samples, dim, depth) => {
+  if (!samples.length) return [];
+  if (depth <= 1) return [samples];
+  const channels = new Array(dim);
+  let maxRange = 0, maxRangeID = 0, i = 0, j, n = samples.length, min, max, value, range, channel;
+  for (; i < dim; i++) {
+    channel = channels[i] = new Array(n);
+    min = Infinity;
+    max = -Infinity;
+    for (j = 0; j < n; j++) {
+      value = channel[j] = samples[j][i];
+      if (value < min) min = value;
+      if (value > max) max = value;
+    }
+    range = max - min;
+    if (range > maxRange) {
+      maxRange = range;
+      maxRangeID = i;
+    }
+  }
+  channel = channels[maxRangeID];
+  const split = cut(channel);
+  const lo = [];
+  const hi = [];
+  for (j = 0; j < n; j++) {
+    (channel[j] <= split ? lo : hi).push(samples[j]);
+  }
+  return computeCutWith(cut, lo, dim, depth >> 1).concat(
+    computeCutWith(cut, hi, dim, depth + 1 >> 1)
+  );
+};
+export {
+  computeCutWith,
+  meanCut,
+  medianCut
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/k-means",
-  "version": "1.1.1",
-  "description": "Configurable k-means & k-medians (with k-means++ initialization) for n-D vectors",
+  "version": "2.0.1",
+  "description": "k-means & k-medians with customizable distance functions and centroid initializations for n-D vectors",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -39,24 +39,30 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.29",
-    "@thi.ng/distance": "^3.0.1",
-    "@thi.ng/errors": "^2.5.35",
-    "@thi.ng/random": "^4.1.20",
-    "@thi.ng/vectors": "^8.3.1"
+    "@thi.ng/api": "^8.11.30",
+    "@thi.ng/distance": "^3.0.3",
+    "@thi.ng/errors": "^2.5.36",
+    "@thi.ng/random": "^4.1.21",
+    "@thi.ng/vectors": "^8.3.2"
   },
   "devDependencies": {
-    "esbuild": "^0.25.5",
-    "typedoc": "^0.28.5",
+    "esbuild": "^0.25.6",
+    "typedoc": "^0.28.7",
     "typescript": "^5.8.3"
   },
   "keywords": [
+    "centroid",
     "cluster",
     "distance",
+    "eucledian",
+    "haversine",
     "k-means",
     "k-means++",
     "k-medians",
+    "mean",
+    "median",
     "nd",
+    "partition",
     "self-organizing",
     "typescript"
   ],
@@ -79,6 +85,9 @@
     },
     "./kmeans": {
       "default": "./kmeans.js"
+    },
+    "./mean-cut": {
+      "default": "./mean-cut.js"
     }
   },
   "thi.ng": {
@@ -87,5 +96,5 @@
     "year": 2021,
     "screenshot": "examples/kmeans-viz.jpg"
   },
-  "gitHead": "b076434a497b291ad33e81b1a15f6a71e2c82cc2\n"
+  "gitHead": "56d8f088389b22192a06e9a395b5eecebf47697a\n"
 }