w-cluster 1.0.19 → 1.0.21

package/script.txt

@@ -0,0 +1,18 @@
+#node toolg/addVersion.mjs
+node toolg/modifyReadme.mjs
+
+node toolg/cleanFolder.mjs
+./node_modules/.bin/jsdoc -c .jsdoc
+node toolg/gDocsExams.mjs
+
+node toolg/gDistRollup.mjs
+
+git add .  -A
+git commit -m 'modify: '
+git push origin master:master
+
+npm run deploy
+
+#npm test
+
+#npm publish

package/src/WCluster.mjs

@@ -25,12 +25,16 @@ async function PCA(data, opt = {}) {
  * @param {Number} [opt.kNumber=2] 輸入指定分群數整數，不能超過數據的長度，預設2
  * @param {Number} [opt.nCompNIPALS=2] 輸入指定降維的維度整數，不能超過數據的維度(各列有效元素數量)，預設2
  * @param {String} [opt.mode='k-medoids'] 輸入分群方法字串，可為'k-means'、'k-medoids'，k-means受初始隨機群中心影響較大，預設'k-medoids'
- * @return {Promise} 回傳Promise，resolve回傳分群後結果物件，keys代表分群有使用到的欄位，ginds代表分群後的指標陣列，gltdt代表分群後的物件陣列，gmat代表分群後且經過PCA處理的數據陣列，其內因是降維後的數據，可例如取最左2欄的數據代表x,y來繪製分群後二維分佈圖，reject回傳錯誤訊息
+ * @param {Boolean} [opt.usePCA=true] 輸入分群前是否先對數據做PCA降維布林值，預設true；若使用自訂非歐距離(如Jaccard對二元向量)應設為false，以保留原始數據語意
+ * @param {Function} [opt.funDist] 輸入自訂距離函數，函數接收兩數據陣列(t1,t2)並回傳兩者距離數值，僅於mode為'k-medoids'時生效，未提供時底層採用歐氏(euclidean)距離
+ * @param {String} [opt.useMethod='fasterPAM'] 輸入k-medoids分群後端字串，僅於mode為'k-medoids'時生效，'simple'為npm套件'k-medoids'(樸素PAM)，'fasterPAM'為內建./src/k-medoids之矩陣式FasterPAM(大數據較快)，預設'fasterPAM'
+ * @param {Number} [opt.seed] 輸入k-means隨機初始化種子整數，僅於mode為'k-means'時生效，給定則分群結果可重現，未提供時為隨機初始化
+ * @return {Promise} 回傳Promise，resolve回傳分群後結果物件，keys代表分群有使用到的欄位，ginds代表分群後的指標陣列，gltdt代表分群後的物件陣列，gmat代表分群後的數據陣列(usePCA為true時為PCA降維後數據，可例如取最左2欄代表x,y繪製二維分佈圖；usePCA為false時為原始數據)，reject回傳錯誤訊息
  * @example
  */
 async function cluster(data, opt = {}) {
     try {
-        return WClusterCore(data, opt)
+        return await WClusterCore(data, opt)
     }
     catch (err) {
         return Promise.reject(err)

package/src/WClusterCore.mjs

@@ -1,10 +1,10 @@
-import get from 'lodash-es/get'
-import each from 'lodash-es/each'
-import size from 'lodash-es/size'
-// import take from 'lodash-es/take'
-import map from 'lodash-es/map'
-import values from 'lodash-es/values'
+import get from 'lodash-es/get.js'
+import each from 'lodash-es/each.js'
+import size from 'lodash-es/size.js'
+import map from 'lodash-es/map.js'
+import values from 'lodash-es/values.js'
 import dtpick from 'wsemi/src/dtpick.mjs'
+import isbol from 'wsemi/src/isbol.mjs'
 import isnum from 'wsemi/src/isnum.mjs'
 import isearr from 'wsemi/src/isearr.mjs'
 import iseobj from 'wsemi/src/iseobj.mjs'
@@ -48,7 +48,7 @@ function getEffData(ltdt, ks) {
 }
 
 
-function WClusterCore(data, opt = {}) {
+async function WClusterCore(data, opt = {}) {
 
     //check
     if (!isearr(data)) {
@@ -56,14 +56,20 @@ function WClusterCore(data, opt = {}) {
     }
 
     //kNumber
-    let kNumber = get(opt, 'kNumber')
+    let kNumber = get(opt, 'kNumber', null)
     if (!isnum(kNumber)) {
         kNumber = 2
     }
     kNumber = cint(kNumber)
 
+    //usePCA
+    let usePCA = get(opt, 'usePCA', null)
+    if (!isbol(usePCA)) {
+        usePCA = true
+    }
+
     //nCompNIPALS
-    let nCompNIPALS = get(opt, 'nCompNIPALS')
+    let nCompNIPALS = get(opt, 'nCompNIPALS', null)
     if (!isnum(nCompNIPALS)) {
         nCompNIPALS = 2
     }
@@ -71,7 +77,16 @@ function WClusterCore(data, opt = {}) {
     // console.log('nCompNIPALS', nCompNIPALS)
 
     //mode, 由WDataCluster檢核與給予預設值
-    let mode = get(opt, 'mode')
+    let mode = get(opt, 'mode', null)
+
+    //seed
+    let seed = get(opt, 'seed', null)
+
+    //funDist
+    let funDist = get(opt, 'funDist', null)
+
+    //useMethod
+    let useMethod = get(opt, 'useMethod', 'fasterPAM')
 
     let type = ''
     let n = size(data)
@@ -87,11 +102,9 @@ function WClusterCore(data, opt = {}) {
     })
     if (iobj === n) {
         type = 'obj'
-        // return WClusterCore(data, opt)
     }
     else if (imat === n) {
         type = 'mat'
-        // return WClusterMat(data, opt)
     }
     else {
         throw new Error('data is not of the same type')
@@ -113,17 +126,13 @@ function WClusterCore(data, opt = {}) {
     }
 
     //WPCAMat
-    let pcad = WPCAMat(mat, { nCompNIPALS })
-
-    // //reduce
-    // pcad = map(pcad, (v) => {
-    //     v = take(v, nCompNIPALS)
-    //     return v
-    // })
-    // // console.log('pcad', pcad)
+    let pcad = mat
+    if (usePCA) {
+        pcad = WPCAMat(mat, { nCompNIPALS })
+    }
 
     //WClusterMat
-    let ginds = WClusterMat(pcad, { kNumber, mode })
+    let ginds = await WClusterMat(pcad, { kNumber, mode, seed, funDist, useMethod })
 
     //gmat
     let gmat = map(ginds, (inds) => {

package/src/WClusterMat.mjs

@@ -1,38 +1,76 @@
-import get from 'lodash-es/get'
-import each from 'lodash-es/each'
-import map from 'lodash-es/map'
-import join from 'lodash-es/join'
-import values from 'lodash-es/values'
+import get from 'lodash-es/get.js'
+import each from 'lodash-es/each.js'
+import map from 'lodash-es/map.js'
+import values from 'lodash-es/values.js'
 import isnum from 'wsemi/src/isnum.mjs'
+import isfun from 'wsemi/src/isfun.mjs'
 import cint from 'wsemi/src/cint.mjs'
 import kmeds from 'k-medoids'
 import { kmeans } from 'ml-kmeans'
+import { fasterpam, first_k } from './k-medoids/index.mjs'
 
 
-function kMedoids(data, kNumber) {
+function euclidean(a, b) {
+    //歐氏距離
+    let s = 0
+    for (let i = 0; i < a.length; i++) {
+        let d = a[i] - b[i]
+        s += d * d
+    }
+    return Math.sqrt(s)
+}
 
-    //kp
-    let kp = {}
-    each(data, (v, k) => {
-        let key = getKey(v)
-        kp[key] = k
-    })
 
-    //getKey
-    function getKey(v) {
-        let key = join(v, ':')
-        return key
+function kMedoidsFasterPAM(data, kNumber, funDist) {
+    //fasterPAM後端, 先以funDist(或預設歐氏)建一次 n×n 距離矩陣(每對只算一次), 再跑fasterpam, 把結果轉回各群原始index
+
+    let n = data.length
+    let dist = isfun(funDist) ? funDist : euclidean
+
+    //建 n×n 對稱距離矩陣
+    let D = Array.from({ length: n }, () => new Float64Array(n))
+    for (let i = 0; i < n; i++) {
+        for (let j = i + 1; j < n; j++) {
+            let d = dist(data[i], data[j])
+            D[i][j] = d
+            D[j][i] = d
+        }
     }
 
+    //fasterpam: med為初始medoid(取前kNumber個, 就地更新), 回傳assi=各點所屬medoid slot
+    let med = first_k(kNumber)
+    let r = fasterpam(D, med, 100)
+
+    //依slot把點分群 → 各群原始index
+    let gs = {}
+    each(r.assi, (slot, i) => {
+        if (!gs[slot]) {
+            gs[slot] = []
+        }
+        gs[slot].push(i)
+    })
+
+    return values(gs)
+}
+
+
+function kMedoidsSimple(data, kNumber, funDist) {
+
+    //kp, 以「元素參照」對應原始index
+    //  getClusteredData回傳原元素參照, 故可用參照反查; 同時天然避免「值相同列」碰撞
+    let kp = new Map()
+    each(data, (v, k) => {
+        kp.set(v, k)
+    })
+
     //getInstance
-    let intance = kmeds.Clusterer.getInstance(data, kNumber)
+    let intance = kmeds.Clusterer.getInstance(data, kNumber, funDist)
 
     //cluster
     let rs = intance.getClusteredData()
     rs = map(rs, (gs) => {
         return map(gs, (v) => {
-            let key = getKey(v)
-            let ind = kp[key]
+            let ind = kp.get(v)
             return ind
         })
     })
@@ -41,10 +79,34 @@ function kMedoids(data, kNumber) {
 }
 
 
-function kMeans(data, kNumber) {
+async function kMedoids(data, kNumber, opt = {}) {
+
+    //funDist
+    let funDist = get(opt, 'funDist', null)
+
+    //useMethod, 選擇k-medoids後端: 'simple'=npm套件'k-medoids'(樸素PAM); 其他(預設'fasterPAM')=./src/k-medoids矩陣式FasterPAM
+    let useMethod = get(opt, 'useMethod', 'fasterPAM')
+    if (useMethod === 'simple') {
+        return kMedoidsSimple(data, kNumber, funDist)
+    }
+    else {
+        return kMedoidsFasterPAM(data, kNumber, funDist)
+    }
+
+}
+
+
+async function kMeans(data, kNumber, opt = {}) {
+
+    //seed
+    let seed = get(opt, 'seed', null)
 
     //kmeans
-    let r = kmeans(data, kNumber)
+    let optKMeans = {}
+    if (seed !== null) {
+        optKMeans = { seed }
+    }
+    let r = kmeans(data, kNumber, optKMeans)
     //k:        [ 0, 1, 2, 3 ]
     //clusters: [ 0, 0, 1, 0 ]
 
@@ -68,8 +130,11 @@ function kMeans(data, kNumber) {
 // @param {Object} [opt={}] 輸入設定物件，預設{}
 // @param {Number} [opt.kNumber=2] 輸入指定分群數整數，不能超過數據的長度，預設2
 // @param {String} [opt.mode='k-medoids'] 輸入分群方法字串，可為'k-means'、'k-medoids'，k-means受初始隨機群中心影響較大，預設'k-medoids'
+// @param {Function} [opt.funDist] 輸入自訂距離函數，函數接收兩數據陣列(t1,t2)並回傳兩者距離數值，僅於mode為'k-medoids'時生效，未提供時底層採用歐氏(euclidean)距離
+// @param {String} [opt.useMethod='fasterPAM'] 輸入k-medoids分群後端字串，僅於mode為'k-medoids'時生效，'simple'為npm套件'k-medoids'(樸素PAM)，'fasterPAM'為內建./src/k-medoids之矩陣式FasterPAM(大數據較快)，預設'fasterPAM'
+// @param {Number} [opt.seed] 輸入k-means隨機初始化種子整數，僅於mode為'k-means'時生效，給定則分群結果可重現，未提供時為隨機初始化
 // @return {Array} 回傳分群後各群所屬items的指標陣列
-function WClusterMat(data, opt = {}) {
+async function WClusterMat(data, opt = {}) {
 
     //kNumber
     let kNumber = get(opt, 'kNumber')
@@ -86,12 +151,21 @@ function WClusterMat(data, opt = {}) {
         mode = 'k-medoids'
     }
 
+    //seed
+    let seed = get(opt, 'seed', null)
+
+    //funDist
+    let funDist = get(opt, 'funDist', null)
+
+    //useMethod
+    let useMethod = get(opt, 'useMethod', 'fasterPAM')
+
     let rs
     if (mode === 'k-medoids') {
-        rs = kMedoids(data, kNumber)
+        rs = await kMedoids(data, kNumber, { funDist, useMethod })
     }
     else if (mode === 'k-means') {
-        rs = kMeans(data, kNumber)
+        rs = await kMeans(data, kNumber, { seed })
     }
     else {
         throw new Error(`invalid mode[${mode}]`)

package/src/WPCAMat.mjs

@@ -1,6 +1,6 @@
 
-import get from 'lodash-es/get'
-import size from 'lodash-es/size'
+import get from 'lodash-es/get.js'
+import size from 'lodash-es/size.js'
 import isearr from 'wsemi/src/isearr.mjs'
 import isbol from 'wsemi/src/isbol.mjs'
 import isnum from 'wsemi/src/isnum.mjs'

package/src/jaccardBitset.mjs

@@ -0,0 +1,63 @@
+// Jaccard 距離的位元打包(bitset) + popcount 加速版。
+//
+// 對「0/1 二元向量」做 k-medoids + Jaccard 分群時, 建距離矩陣為 O(n²·D)。逐維計算
+// Jaccard 在高維很慢; 改用「把 D 個 0/1 位元打包成 ceil(D/32) 個 32-bit word, 以
+// popcount 一次處理 32 維」, 每對距離計算可加速約一個數量級(實測高維 ~14–23x)。
+//
+// 用法:
+//   import { jaccardBitset } from './jaccardBitset.mjs'
+//   let { data, funDist } = jaccardBitset(rows)   //rows: 各列為等長 0/1 陣列
+//   let rc = await WCluster.cluster(data, { mode: 'k-medoids', kNumber, usePCA: false, funDist, useMethod: 'fasterPAM' })
+//   //rc.ginds 為各群所屬「原始列 index」, 與 rows 對應
+//
+// 注意:
+//   1) 必須 usePCA:false —— 打包後的列是 word 值, 不可再做 PCA。
+//   2) funDist 必須搭配「打包後的 data」使用(兩者由本函數成對產出)。
+//   3) 兩列皆全 0(聯集為 0)時 Jaccard 距離視為相同(0), 與逐維版語意一致。
+
+
+//把單一 0/1 陣列打包成 plain Array(每元素為一個 32-bit word)。
+//  用 plain Array(非 Uint32Array)以相容 WCluster 的陣列型別檢核(isearr 只認真正 Array)。
+function packBits(v) {
+    let nw = Math.ceil(v.length / 32)
+    let w = new Array(nw).fill(0)
+    for (let i = 0; i < v.length; i++) {
+        if (v[i]) {
+            w[i >> 5] |= (1 << (i & 31))
+        }
+    }
+    return w
+}
+
+
+//32-bit popcount(SWAR); 以 >>> 確保以無號位元樣式計算。
+function popcount32(x) {
+    x = x >>> 0
+    x = x - ((x >>> 1) & 0x55555555)
+    x = (x & 0x33333333) + ((x >>> 2) & 0x33333333)
+    x = (x + (x >>> 4)) & 0x0f0f0f0f
+    return Math.imul(x, 0x01010101) >>> 24
+}
+
+
+//兩個「打包後列」的 Jaccard 距離 = 1 − |交集| / |聯集|; 聯集為 0(兩列皆空)視為相同(0)。
+function jaccardBits(wa, wb) {
+    let inter = 0
+    let uni = 0
+    for (let i = 0; i < wa.length; i++) {
+        inter += popcount32(wa[i] & wb[i])
+        uni += popcount32(wa[i] | wb[i])
+    }
+    return uni === 0 ? 0 : 1 - inter / uni
+}
+
+
+//便利函數: 輸入 0/1 列陣列, 回傳 { data:打包後列陣列, funDist:jaccardBits }, 直接餵 WCluster.cluster。
+function jaccardBitset(rows) {
+    let data = rows.map((v) => packBits(v))
+    return { data, funDist: jaccardBits }
+}
+
+
+export { packBits, popcount32, jaccardBits, jaccardBitset }
+export default jaccardBitset

package/src/k-medoids/README.md

@@ -0,0 +1,124 @@
+# k-medoids — k-Medoids Clustering in JavaScript (ES Modules)
+
+A faithful ES module port of [kno10/rust-kmedoids](https://github.com/kno10/rust-kmedoids) to JavaScript.
+
+## Requirements
+
+- Node.js >= 18
+- ES modules (`import`/`export`); all files use the `.mjs` extension.
+
+## Usage
+
+```js
+import { fasterpam, random_initialization, silhouette, LowerTriangle } from './index.mjs';
+
+const diss = [[0,1,2,3],[1,0,4,5],[2,4,0,6],[3,5,6,0]];
+const meds = random_initialization(4, 2);
+const { loss, assi, nIter, nSwaps } = fasterpam(diss, meds, 100);
+console.log('Loss:', loss);
+
+const { sil } = silhouette(diss, assi, false);
+```
+
+The `meds` array is mutated in place by all clustering functions (the final medoid indices are written back).
+
+## Input format
+
+Pass a pairwise dissimilarity matrix as:
+
+- A **2D array** `diss[i][j]` (full square matrix), or
+- A **`LowerTriangle`** instance (serialized lower-triangular data, see `arrayadapter.mjs`).
+
+All distance values are plain JS `number` (IEEE-754 double).
+
+## Return values
+
+Public clustering functions return plain objects:
+
+| Function(s) | Return shape |
+|---|---|
+| `fasterpam`, `rand_fasterpam`, `fastpam1`, `pam_swap`, `fastmsc`, `fastermsc`, `pamsil_swap`, `pammedsil_swap`, `par_fasterpam` | `{ loss, assi, nIter, nSwaps }` |
+| `alternating` | `{ loss, assi, nIter }` |
+| `pam` | `{ loss, assi, meds, nIter, nSwaps }` |
+| `pam_build` | `{ loss, assi, meds }` |
+| `pamsil`, `pammedsil` | `{ loss, assi, meds, nIter, nSwaps }` |
+| `dynmsc` | `{ loss, assi, nIter, nSwaps, meds, losses }` |
+| `silhouette`, `medoid_silhouette` | `{ sil, samples }` (`samples` is `[]` when `samples=false`) |
+| `par_silhouette` | a plain `number` |
+
+## Implemented algorithms
+
+- **FasterPAM** (Schubert and Rousseeuw, 2020, 2021) — `fasterpam`
+- **FasterPAM with shuffling** — `rand_fasterpam`
+- **Parallelized FasterPAM** (sequential equivalent in JS) — `par_fasterpam`
+- **FastPAM1** (Schubert and Rousseeuw, 2019, 2021) — `fastpam1`
+- **PAM** (Kaufman and Rousseeuw, 1987) with BUILD and SWAP — `pam`, `pam_build`, `pam_swap`
+- **Alternating optimization** (k-means-style) — `alternating`
+- **FasterMSC** (Lenssen and Schubert, 2022) — `fastermsc`
+- **FastMSC** (Lenssen and Schubert, 2022) — `fastmsc`
+- **DynMSC** (Lenssen and Schubert, 2023) — `dynmsc`
+- **PAMSIL** (Van der Laan and Pollard, 2003) — `pamsil`, `pamsil_swap`
+- **PAMMEDSIL** (Van der Laan and Pollard, 2003) — `pammedsil`, `pammedsil_swap`
+- **Silhouette index** (Rousseeuw, 1987) — `silhouette`, `medoid_silhouette`, `par_silhouette`
+
+Note: the k-means-like alternating algorithm tends to find much worse solutions than PAM-based methods.
+
+The parallel variants (`par_fasterpam`, `par_silhouette`) are sequential equivalents in this JS port (JS is single-threaded). They produce identical results to the non-parallel variants.
+
+## Random initialization
+
+`random_initialization(n, k)` returns a length-`k` array of distinct random indices in `[0, n)`.
+Because JS uses a different PRNG than the Rust crate, seeded results will differ numerically from the Rust version even on the same data.
+
+## Notes on numerical fidelity
+
+The port preserves left-to-right accumulation order of the Rust source so that IEEE-754 results match for deterministic inputs. Results may differ from the Rust crate only when random initialization differs (see above).
+
+## License
+
+GPL-3.0-or-later (same as upstream rust-kmedoids).
+
+> This program is free software: you can redistribute it and/or modify
+> it under the terms of the GNU General Public License as published by
+> the Free Software Foundation, either version 3 of the License, or
+> (at your option) any later version.
+>
+> This program is distributed in the hope that it will be useful,
+> but WITHOUT ANY WARRANTY; without even the implied warranty of
+> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+> GNU General Public License for more details.
+>
+> You should have received a copy of the GNU General Public License
+> along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+## References
+
+> Erich Schubert and Lars Lenssen
+> **Fast k-medoids Clustering in Rust and Python**
+> Journal of Open Source Software 7(75), 4183
+> <https://doi.org/10.21105/joss.04183>
+
+> Erich Schubert, Peter J. Rousseeuw
+> **Fast and Eager k-Medoids Clustering:
+> O(k) Runtime Improvement of the PAM, CLARA, and CLARANS Algorithms**
+> Information Systems (101), 2021, 101804
+> <https://doi.org/10.1016/j.is.2021.101804>
+
+> Erich Schubert, Peter J. Rousseeuw:
+> **Faster k-Medoids Clustering: Improving the PAM, CLARA, and CLARANS Algorithms**
+> In: 12th International Conference on Similarity Search and Applications (SISAP 2019), 171-187.
+> <https://doi.org/10.1007/978-3-030-32047-8_16>
+> Preprint: <https://arxiv.org/abs/1810.05691>
+
+> Lars Lenssen, Erich Schubert:
+> **Medoid silhouette clustering with automatic cluster number selection**
+> Information Systems (120), 2024, 102290
+> <https://doi.org/10.1016/j.is.2023.102290>
+> Preprint: <https://arxiv.org/abs/2309.03751>
+
+> Lars Lenssen, Erich Schubert:
+> **Clustering by Direct Optimization of the Medoid Silhouette**
+> In: 15th International Conference on Similarity Search and Applications (SISAP 2022)
+> <https://doi.org/10.1007/978-3-031-17849-8_15>
+
+If you use this code in scientific work, please cite the relevant papers above.

package/src/k-medoids/alternating.mjs

@@ -0,0 +1,72 @@
+// Alternating (k-means-style) k-medoids algorithm.
+// Ported 1:1 from src/alternating.rs
+
+import { arrayAdapter } from './arrayadapter.mjs';
+import { USIZE_MAX, choose_medoid_within_partition } from './util.mjs';
+
+/**
+ * Run the Alternating algorithm, a k-means-style alternate optimization.
+ *
+ * This is fairly fast (O(n²), like the FasterPAM method), but because the
+ * newly chosen medoid must cover the entire existing cluster, it tends to
+ * get stuck in worse local optima as the alternatives. Hence, it is not
+ * really recommended to use this algorithm (also known as "Alternate" in
+ * classic facility location literature, and re-invented by Park and Jun 2009).
+ *
+ * @param {*} mat - a pairwise distance matrix (2D array or adapter object)
+ * @param {number[]} med - the list of medoids (mutated in place)
+ * @param {number} maxiter - the maximum number of iterations allowed
+ * @returns {{ loss: number, assi: number[], nIter: number }}
+ */
+export function alternating(mat, med, maxiter) {
+  mat = arrayAdapter(mat);
+  const n = mat.len();
+  const assi = new Array(n).fill(USIZE_MAX);
+  let loss = assign_nearest(mat, med, assi);
+  let iter = 0;
+  while (iter < maxiter) {
+    iter += 1;
+    let changed = false;
+    for (let i = 0; i < med.length; i++) {
+      changed |= choose_medoid_within_partition(mat, assi, med, i)[0];
+    }
+    if (!changed) {
+      break;
+    }
+    loss = assign_nearest(mat, med, assi);
+  }
+  return { loss, assi, nIter: iter };
+}
+
+/**
+ * Assign each point to the nearest medoid, return total loss.
+ * Mutates dataArr[i] = index into med of nearest medoid.
+ *
+ * @param {*} mat - already-wrapped matrix
+ * @param {number[]} med - medoid point indices
+ * @param {number[]} dataArr - assignment array, mutated in place
+ * @returns {number} total loss
+ */
+export function assign_nearest(mat, med, dataArr) {
+  const n = mat.len();
+  const k = med.length;
+  if (!mat.isSquare()) throw new Error('Dissimilarity matrix is not square');
+  if (n > 4294967295) throw new Error('N is too large');
+  if (!(k > 0 && k < 4294967295)) throw new Error('invalid N');
+  if (k > n) throw new Error('k must be at most N');
+  const firstcenter = med[0];
+  let acc = 0;
+  for (let i = 0; i < n; i++) {
+    let best = [0, mat.get(i, firstcenter)];
+    for (let m = 1; m < k; m++) {
+      const mm = med[m];
+      const dm = mat.get(i, mm);
+      if (dm < best[1] || i === mm) {
+        best = [m, dm];
+      }
+    }
+    dataArr[i] = best[0];
+    acc += best[1];
+  }
+  return acc;
+}

package/src/k-medoids/arrayadapter.mjs

@@ -0,0 +1,35 @@
+// Array adapters, ported from src/arrayadapter.rs
+// All matrices expose: len() -> n, isSquare() -> bool, get(x, y) -> number
+
+/** Wraps a dense 2D array (array of equal-length rows). */
+export class DenseMatrix {
+  constructor(rows) { this.rows = rows; }
+  len() { return this.rows.length; }
+  isSquare() {
+    const n = this.rows.length;
+    for (let i = 0; i < n; i++) { if (this.rows[i].length !== n) return false; }
+    return true;
+  }
+  get(x, y) { return this.rows[x][y]; }
+}
+
+/** Lower triangular matrix in serial form (without diagonal). data length = n*(n-1)/2. */
+export class LowerTriangle {
+  constructor(n, data) { this.n = n; this.data = data; }
+  len() { return this.n; }
+  isSquare() { return this.data.length === ((this.n * (this.n - 1)) / 2); }
+  get(x, y) {
+    // products x*(x-1) are always even, so /2 is an exact integer (valid up to 2^53);
+    // the original >>1 truncates to int32 and overflows the index for n >= ~46342
+    if (x < y) return this.data[((y * (y - 1)) / 2) + x];
+    if (x > y) return this.data[((x * (x - 1)) / 2) + y];
+    return 0;
+  }
+}
+
+/** Normalize user input into a matrix object. Idempotent. Accepts a 2D array, DenseMatrix, or LowerTriangle. */
+export function arrayAdapter(input) {
+  if (input && typeof input.get === 'function' && typeof input.len === 'function') return input;
+  if (Array.isArray(input)) return new DenseMatrix(input);
+  throw new Error('Unsupported matrix input: provide a 2D array, a DenseMatrix, or a LowerTriangle');
+}