npm - w-cluster - Versions diffs - 1.0.20 → 1.0.21 - Mend

w-cluster 1.0.20 → 1.0.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (72) hide show

package/.github/workflows/ci-test.yml +3 -3
package/README.md +4 -6
package/babel.config.js +4 -3
package/dist/w-cluster.umd.js +2 -2
package/dist/w-cluster.umd.js.map +1 -1
package/dist/w-cluster.wk.umd.js +1 -1
package/docs/DenseMatrix.html +202 -0
package/docs/DistancePair.html +202 -0
package/docs/LowerTriangle.html +202 -0
package/docs/Rec.html +202 -0
package/docs/Reco.html +202 -0
package/docs/WCluster.mjs.html +8 -4
package/docs/examples/ex-PCA.html +1 -1
package/docs/examples/ex-cluster-webworker.html +1 -1
package/docs/examples/ex-cluster.html +1 -1
package/docs/global.html +6799 -164
package/docs/index.html +2 -2
package/docs/k-medoids_alternating.mjs.html +144 -0
package/docs/k-medoids_arrayadapter.mjs.html +107 -0
package/docs/k-medoids_dynmsc.mjs.html +255 -0
package/docs/k-medoids_fastermsc.mjs.html +411 -0
package/docs/k-medoids_fasterpam.mjs.html +305 -0
package/docs/k-medoids_fastmsc.mjs.html +166 -0
package/docs/k-medoids_fastpam1.mjs.html +132 -0
package/docs/k-medoids_initialization.mjs.html +107 -0
package/docs/k-medoids_pam.mjs.html +275 -0
package/docs/k-medoids_pammedsil.mjs.html +307 -0
package/docs/k-medoids_pamsil.mjs.html +225 -0
package/docs/k-medoids_par_fasterpam.mjs.html +134 -0
package/docs/k-medoids_par_silhouette.mjs.html +126 -0
package/docs/k-medoids_silhouette.mjs.html +193 -0
package/docs/k-medoids_util.mjs.html +135 -0
package/g-PCA-nodeworker.mjs +1 -1
package/g-PCA.mjs +1 -1
package/g-cluster-kMeans-large.mjs +83 -0
package/g-cluster-kMeans-nodeworker.mjs +181 -0
package/g-cluster-kMeans.mjs +178 -0
package/g-cluster-kMedoids-large-suggest.mjs +95 -0
package/g-cluster-kMedoids-large.mjs +104 -0
package/{g-cluster-nodeworker.mjs → g-cluster-kMedoids-nodeworker.mjs} +1 -2
package/{g-cluster.mjs → g-cluster-kMedoids-simple.mjs} +1 -1
package/package.json +7 -7
package/script.txt +5 -7
package/src/WCluster.mjs +6 -2
package/src/WClusterCore.mjs +30 -21
package/src/WClusterMat.mjs +98 -24
package/src/jaccardBitset.mjs +63 -0
package/src/k-medoids/README.md +124 -0
package/src/k-medoids/alternating.mjs +72 -0
package/src/k-medoids/arrayadapter.mjs +35 -0
package/src/k-medoids/dynmsc.mjs +183 -0
package/src/k-medoids/fastermsc.mjs +339 -0
package/src/k-medoids/fasterpam.mjs +233 -0
package/src/k-medoids/fastmsc.mjs +94 -0
package/src/k-medoids/fastpam1.mjs +60 -0
package/src/k-medoids/index.mjs +37 -0
package/src/k-medoids/initialization.mjs +35 -0
package/src/k-medoids/package.json +8 -0
package/src/k-medoids/pam.mjs +203 -0
package/src/k-medoids/pammedsil.mjs +235 -0
package/src/k-medoids/pamsil.mjs +153 -0
package/src/k-medoids/par_fasterpam.mjs +62 -0
package/src/k-medoids/par_silhouette.mjs +54 -0
package/src/k-medoids/silhouette.mjs +121 -0
package/src/k-medoids/test.mjs +357 -0
package/src/k-medoids/util.mjs +63 -0
package/test/jaccardBitset.test.mjs +141 -0
package/test/kMeans.test.mjs +278 -0
package/test/kMedoids-large-suggest.test.mjs +140 -0
package/test/kMedoids-large.test.mjs +142 -0
package/test/{cluster.test.mjs → kMedoids-simple.test.mjs} +5 -5
package/toolg/gDocsExams.mjs +1 -1

package/docs/k-medoids_fastermsc.mjs.html ADDED Viewed

@@ -0,0 +1,411 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>k-medoids/fastermsc.mjs - Documentation</title>
+    <script src="scripts/prettify/prettify.js"></script>
+    <script src="scripts/prettify/lang-css.js"></script>
+    <!--[if lt IE 9]>
+      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
+    <![endif]-->
+    <link type="text/css" rel="stylesheet" href="styles/prettify.css">
+    <link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
+    <script src="scripts/nav.js" defer></script>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+<body>
+<input type="checkbox" id="nav-trigger" class="nav-trigger" />
+<label for="nav-trigger" class="navicon-button x">
+  <div class="navicon"></div>
+</label>
+<label for="nav-trigger" class="overlay"></label>
+<nav >
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="DenseMatrix.html">DenseMatrix</a></li><li><a href="DistancePair.html">DistancePair</a></li><li><a href="LowerTriangle.html">LowerTriangle</a></li><li><a href="Rec.html">Rec</a></li><li><a href="Reco.html">Reco</a></li></ul><h3>Global</h3><ul><li><a href="global.html#PCA">PCA</a></li><li><a href="global.html#WCluster">WCluster</a></li><li><a href="global.html#alternating">alternating</a></li><li><a href="global.html#arrayAdapter">arrayAdapter</a></li><li><a href="global.html#assign_nearest">assign_nearest</a></li><li><a href="global.html#choose_medoid_within_partition">choose_medoid_within_partition</a></li><li><a href="global.html#cluster">cluster</a></li><li><a href="global.html#do_swap">do_swap</a></li><li><a href="global.html#do_swap_k2">do_swap_k2</a></li><li><a href="global.html#dynmsc">dynmsc</a></li><li><a href="global.html#fastermsc">fastermsc</a></li><li><a href="global.html#fastermsc_k2">fastermsc_k2</a></li><li><a href="global.html#fasterpam">fasterpam</a></li><li><a href="global.html#fastmsc">fastmsc</a></li><li><a href="global.html#fastmsc_k2">fastmsc_k2</a></li><li><a href="global.html#fastpam1">fastpam1</a></li><li><a href="global.html#find_best_swap">find_best_swap</a></li><li><a href="global.html#find_best_swap_k2">find_best_swap_k2</a></li><li><a href="global.html#find_best_swap_pam">find_best_swap_pam</a></li><li><a href="global.html#find_best_swap_pammedsil">find_best_swap_pammedsil</a></li><li><a href="global.html#find_best_swap_pammedsil_k2">find_best_swap_pammedsil_k2</a></li><li><a href="global.html#find_max">find_max</a></li><li><a href="global.html#find_min">find_min</a></li><li><a href="global.html#first_k">first_k</a></li><li><a href="global.html#initial_assignment">initial_assignment</a></li><li><a href="global.html#initial_assignment_k2">initial_assignment_k2</a></li><li><a href="global.html#medoid_silhouette">medoid_silhouette</a></li><li><a href="global.html#pam">pam</a></li><li><a href="global.html#pam_build">pam_build</a></li><li><a href="global.html#pam_build_initialize">pam_build_initialize</a></li><li><a href="global.html#pam_optimize">pam_optimize</a></li><li><a href="global.html#pam_swap">pam_swap</a></li><li><a href="global.html#pammedsil">pammedsil</a></li><li><a href="global.html#pammedsil_build_initialize">pammedsil_build_initialize</a></li><li><a href="global.html#pammedsil_optimize">pammedsil_optimize</a></li><li><a href="global.html#pammedsil_swap">pammedsil_swap</a></li><li><a href="global.html#pamsil">pamsil</a></li><li><a href="global.html#pamsil_build_initialize">pamsil_build_initialize</a></li><li><a href="global.html#pamsil_optimize">pamsil_optimize</a></li><li><a href="global.html#pamsil_swap">pamsil_swap</a></li><li><a href="global.html#par_fasterpam">par_fasterpam</a></li><li><a href="global.html#par_silhouette">par_silhouette</a></li><li><a href="global.html#rand_fasterpam">rand_fasterpam</a></li><li><a href="global.html#random_initialization">random_initialization</a></li><li><a href="global.html#remove_med">remove_med</a></li><li><a href="global.html#sample">sample</a></li><li><a href="global.html#shuffle">shuffle</a></li><li><a href="global.html#silhouette">silhouette</a></li><li><a href="global.html#update_removal_loss">update_removal_loss</a></li><li><a href="global.html#update_second_nearest">update_second_nearest</a></li><li><a href="global.html#update_third_nearest">update_third_nearest</a></li><li><a href="global.html#update_third_nearest_without_new">update_third_nearest_without_new</a></li></ul>
+</nav>
+<div id="main">
+    <h1 class="page-title">k-medoids/fastermsc.mjs</h1>
+    <section>
+        <article>
+            <pre class="prettyprint source linenums"><code>// Ported 1:1 from src/fastermsc.rs (FasterMSC algorithm).
+import { arrayAdapter } from './arrayadapter.mjs';
+import { Reco, DistancePair, U32_MAX, find_min, find_max, choose_medoid_within_partition } from './util.mjs';
+// _loss(a, b): 0 if a or b is zero, else a / b.
+export function _loss(a, b) {
+  if (a === 0 || b === 0) { return 0; } else { return a / b; }
+}
+/**
+ * Run the FasterMSC algorithm.
+ * @param {object} mat - pairwise distance matrix (wrapped)
+ * @param {number[]} med - the list of medoids (mutated in place)
+ * @param {number} maxiter - maximum number of iterations
+ * returns { loss, assi, nIter, nSwaps }
+ */
+export function fastermsc(mat, med, maxiter) {
+  mat = arrayAdapter(mat);
+  const n = mat.len(), k = med.length;
+  if (k === 1) {
+    const assi = new Array(n).fill(0);
+    const [swapped, loss] = choose_medoid_within_partition(mat, assi, med, 0);
+    return { loss, assi, nIter: 1, nSwaps: swapped ? 1 : 0 };
+  }
+  if (k === 2) { // special hadling, as there is no third
+    return fastermsc_k2(mat, med, maxiter);
+  }
+  let [loss, data] = initial_assignment(mat, med);
+  let removal_loss = new Array(k).fill(0);
+  update_removal_loss(data, removal_loss);
+  let lastswap = n, n_swaps = 0, iter = 0;
+  while (iter &lt; maxiter) {
+    iter += 1;
+    const swaps_before = n_swaps, lastloss = loss;
+    for (let j = 0; j &lt; n; j++) {
+      if (j === lastswap) {
+        break;
+      }
+      if (j === med[data[j].near.i]) {
+        continue; // This already is a medoid
+      }
+      const [change, b] = find_best_swap(mat, removal_loss, data, j);
+      if (change &lt;= 0) {
+        continue; // No improvement
+      }
+      n_swaps += 1;
+      lastswap = j;
+      // perform the swap
+      loss = do_swap(mat, med, data, b, j);
+      update_removal_loss(data, removal_loss);
+    }
+    if (n_swaps === swaps_before || loss >= lastloss) {
+      break; // converged
+    }
+  }
+  const assi = data.map((x) => x.near.i);
+  loss = 1 - loss / n;
+  return { loss, assi, nIter: iter, nSwaps: n_swaps };
+}
+/** Perform the initial assignment to medoids. Returns [loss, data] (data = Reco[]). */
+export function initial_assignment(mat, med) {
+  const n = mat.len(), k = med.length;
+  if (!mat.isSquare()) throw new Error('Dissimilarity matrix is not square');
+  if (!(n &lt;= U32_MAX)) throw new Error('N is too large');
+  if (!(k > 0 &amp;&amp; k &lt; U32_MAX)) throw new Error('invalid N');
+  if (!(k &lt;= n)) throw new Error('k must be at most N');
+  const data = new Array(mat.len());
+  for (let _i = 0; _i &lt; data.length; _i++) data[_i] = Reco.empty();
+  const firstcenter = med[0];
+  let loss = 0;
+  for (let i = 0; i &lt; data.length; i++) {
+    // Rust: *cur = Reco::new(...) overwrites the slot in place.
+    const cur = new Reco(0, mat.get(i, firstcenter), U32_MAX, 0, U32_MAX, 0);
+    data[i] = cur;
+    for (let m = 1; m &lt; med.length; m++) {
+      const me = med[m];
+      const d = mat.get(i, me);
+      if (d &lt; cur.near.d || i === me) {
+        cur.third = cur.seco.clone();
+        cur.seco = cur.near.clone();
+        cur.near = new DistancePair(m, d);
+      } else if (cur.seco.i === U32_MAX || d &lt; cur.seco.d) {
+        cur.third = cur.seco.clone();
+        cur.seco = new DistancePair(m, d);
+      } else if (cur.third.i === U32_MAX || d &lt; cur.third.d) {
+        cur.third = new DistancePair(m, d);
+      }
+    }
+    loss += _loss(cur.near.d, cur.seco.d);
+  }
+  return [loss, data];
+}
+/** Find the best swap for object j - FastMSC version. Returns [change, b]. */
+export function find_best_swap(mat, removal_loss, data, j) {
+  const ploss = removal_loss.slice();
+  // Improvement from the journal version:
+  let acc = 0;
+  for (let o = 0; o &lt; data.length; o++) {
+    const reco = data[o];
+    const doj = mat.get(o, j);
+    if (doj &lt; reco.near.d) {
+      acc += _loss(reco.near.d, reco.seco.d) - _loss(doj, reco.near.d);
+      // loss already includes (dt - ds) - (ds - dn), remove
+      ploss[reco.near.i] += _loss(doj, reco.near.d) + _loss(reco.seco.d, reco.third.d) - _loss(reco.near.d + doj, reco.seco.d);
+      ploss[reco.seco.i] += _loss(reco.near.d, reco.third.d) - _loss(reco.near.d, reco.seco.d);
+    } else if (doj &lt; reco.seco.d) {
+      acc += _loss(reco.near.d, reco.seco.d) - _loss(reco.near.d, doj);
+      ploss[reco.near.i] += _loss(reco.near.d, doj) + _loss(reco.seco.d, reco.third.d) - _loss(reco.near.d + doj, reco.seco.d);
+      // loss already includes (dt - ds) - (ds - dn), adjust to 2*d(xo) - ds - dt
+      // loss already includes (dt - ds), adjust to 2*d(xo) - ds - dt
+      ploss[reco.seco.i] += _loss(reco.near.d, reco.third.d) - _loss(reco.near.d, reco.seco.d);
+    } else if (doj &lt; reco.third.d) {
+      // loss already includes (dt - ds) - (ds - dn), adjust to d(xo)- dt
+      ploss[reco.near.i] += _loss(reco.seco.d, reco.third.d) - _loss(reco.seco.d, doj);
+      // loss already includes (dt - ds), adjust to d(xo)- dt
+      ploss[reco.seco.i] += _loss(reco.near.d, reco.third.d) - _loss(reco.near.d, doj);
+    }
+  }
+  const [b, bloss] = find_max(ploss);
+  return [bloss + acc, b]; // add the shared accumulator
+}
+/** Update the loss when removing each medoid. Mutates loss in place. */
+export function update_removal_loss(data, loss) {
+  loss.fill(0); // stable since 1.50
+  for (let r = 0; r &lt; data.length; r++) {
+    const rec = data[r];
+    loss[rec.near.i] += _loss(rec.near.d, rec.seco.d) - _loss(rec.seco.d, rec.third.d);
+    loss[rec.seco.i] += _loss(rec.near.d, rec.seco.d) - _loss(rec.near.d, rec.third.d);
+    // as N might be unsigned
+  }
+}
+/** Update the third nearest medoid information. Called after each swap. Returns fresh DistancePair. */
+export function update_third_nearest(mat, med, n, s, b, o, doj) {
+  let dist = new DistancePair(b, doj);
+  for (let i = 0; i &lt; med.length; i++) {
+    const mi = med[i];
+    if (i === n || i === b || i === s) {
+      continue;
+    }
+    const d = mat.get(o, mi);
+    if (d &lt; dist.d) {
+      dist = new DistancePair(i, d);
+    }
+  }
+  return dist;
+}
+/** Perform a single swap. Returns RAW loss. */
+export function do_swap(mat, med, data, b, j) {
+  const n = mat.len();
+  if (!(b &lt; med.length)) throw new Error('invalid medoid number');
+  if (!(j &lt; n)) throw new Error('invalid object number');
+  med[b] = j;
+  let acc = 0;
+  for (let o = 0; o &lt; data.length; o++) {
+    const reco = data[o];
+    if (o === j) {
+      if (reco.near.i !== b) {
+        if (reco.seco.i !== b) {
+          reco.third = reco.seco.clone();
+        }
+        reco.seco = reco.near.clone();
+      }
+      reco.near = new DistancePair(b, 0);
+      acc += 0;
+      continue;
+    }
+    const doj = mat.get(o, j);
+    // Nearest medoid is gone:
+    if (reco.near.i === b) {
+      if (doj &lt; reco.seco.d) {
+        reco.near = new DistancePair(b, doj);
+      } else if (reco.third.i === U32_MAX || doj &lt; reco.third.d) {
+        reco.near = reco.seco.clone();
+        reco.seco = new DistancePair(b, doj);
+      } else {
+        reco.near = reco.seco.clone();
+        reco.seco = reco.third.clone();
+        reco.third = update_third_nearest(mat, med, reco.near.i, reco.seco.i, b, o, doj);
+      }
+    } else if (reco.seco.i === b) {
+      // second nearest was replaced
+      if (doj &lt; reco.near.d) {
+        reco.seco = reco.near.clone();
+        reco.near = new DistancePair(b, doj);
+      } else if (reco.third.i === U32_MAX || doj &lt; reco.third.d) {
+        reco.seco = new DistancePair(b, doj);
+      } else {
+        reco.seco = reco.third.clone();
+        reco.third = update_third_nearest(mat, med, reco.near.i, reco.seco.i, b, o, doj);
+      }
+    } else {
+      // nearest not removed
+      if (doj &lt; reco.near.d) {
+        reco.third = reco.seco.clone();
+        reco.seco = reco.near.clone();
+        reco.near = new DistancePair(b, doj);
+      } else if (doj &lt; reco.seco.d) {
+        reco.third = reco.seco.clone();
+        reco.seco = new DistancePair(b, doj);
+      } else if (reco.third.i === U32_MAX || doj &lt; reco.third.d) {
+        reco.third = new DistancePair(b, doj);
+      } else if (reco.third.i === b) {
+        reco.third = update_third_nearest(mat, med, reco.near.i, reco.seco.i, b, o, doj);
+      }
+    }
+    acc += _loss(reco.near.d, reco.seco.d);
+  }
+  return acc;
+}
+/** Special case k=2 of the FasterMSC algorithm. Returns { loss, assi, nIter, nSwaps }. */
+export function fastermsc_k2(mat, med, maxiter) {
+  const n = mat.len(), k = med.length;
+  if (!(k === 2)) throw new Error('Only valid for k=2');
+  let [loss, assi, data] = initial_assignment_k2(mat, med);
+  let lastswap = n, n_swaps = 0, iter = 0;
+  while (iter &lt; maxiter) {
+    iter += 1;
+    const swaps_before = n_swaps, lastloss = loss;
+    for (let j = 0; j &lt; n; j++) {
+      if (j === lastswap) {
+        break;
+      }
+      if (j === med[assi[j]]) {
+        continue; // This already is a medoid
+      }
+      const [newloss, b] = find_best_swap_k2(mat, data, j); // assi not used, see below
+      if (newloss >= loss) {
+        continue; // No improvement
+      }
+      n_swaps += 1;
+      lastswap = j;
+      // perform the swap
+      loss = do_swap_k2(mat, med, assi, data, b, j);
+    }
+    if (n_swaps === swaps_before || loss >= lastloss) {
+      break; // converged
+    }
+  }
+  loss = 1 - loss / n;
+  return { loss, assi, nIter: iter, nSwaps: n_swaps };
+}
+/** Perform the initial assignment to medoids, for k=2 only. Returns [loss, assi, data] (data = [d0,d1] pairs). */
+export function initial_assignment_k2(mat, med) {
+  const n = mat.len(), k = med.length;
+  if (!mat.isSquare()) throw new Error('Dissimilarity matrix is not square');
+  if (!(n &lt;= U32_MAX)) throw new Error('N is too large');
+  if (!(k === 2)) throw new Error('k must be 2');
+  const assi = new Array(mat.len()).fill(0);
+  const data = new Array(mat.len());
+  for (let _i = 0; _i &lt; data.length; _i++) data[_i] = [0, 0];
+  let loss = 0;
+  for (let i = 0; i &lt; data.length; i++) {
+    const d = data[i];
+    d[0] = mat.get(i, med[0]);
+    d[1] = mat.get(i, med[1]);
+    if (d[0] &lt; d[1]) {
+      assi[i] = 0;
+      loss += _loss(d[0], d[1]); // return
+    } else {
+      assi[i] = 1;
+      loss += _loss(d[1], d[0]); // return
+    }
+  }
+  return [loss, assi, data];
+}
+/** Find the best swap for object j - FastMSC version, k=2. Returns [loss, b]. */
+export function find_best_swap_k2(mat, data, j) {
+  const ploss = [0, 0];
+  for (let o = 0; o &lt; data.length; o++) {
+    const d = data[o];
+    const doj = mat.get(o, j);
+    // We do not use the assignment here, because we stored d0/d1 by medoid position, not closeness
+    ploss[0] += (doj &lt; d[1]) ? _loss(doj, d[1]) : _loss(d[1], doj);
+    ploss[1] += (doj &lt; d[0]) ? _loss(doj, d[0]) : _loss(d[0], doj);
+  }
+  const [b, bloss] = find_min(ploss);
+  return [bloss, b];
+}
+/** Perform a single swap, k=2. Returns RAW loss. */
+export function do_swap_k2(mat, med, assi, data, b, j) {
+  const n = mat.len();
+  if (!(b &lt; med.length)) throw new Error('invalid medoid number');
+  if (!(j &lt; n)) throw new Error('invalid object number');
+  med[b] = j;
+  // Its nicer to have the if outside, even though this looks duplicated
+  if (b === 0) {
+    let acc = 0;
+    for (let o = 0; o &lt; data.length; o++) {
+      const d = data[o];
+      if (o === j) {
+        assi[o] = 0;
+        d[0] = 0;
+        acc += 0;
+        continue;
+      }
+      const doj = mat.get(o, j);
+      d[0] = doj;
+      if (doj &lt; d[1] || (doj === d[1] &amp;&amp; assi[o] === 0)) {
+        assi[o] = 0;
+        acc += _loss(doj, d[1]); // return
+      } else {
+        assi[o] = 1;
+        acc += _loss(d[1], doj); // return
+      }
+    }
+    return acc;
+  } else { // b == 1
+    let acc = 0;
+    for (let o = 0; o &lt; data.length; o++) {
+      const d = data[o];
+      if (o === j) {
+        assi[o] = 1;
+        d[1] = 0;
+        acc += 0;
+        continue;
+      }
+      const doj = mat.get(o, j);
+      d[1] = doj;
+      if (doj &lt; d[0] || (doj === d[0] &amp;&amp; assi[o] === 1)) {
+        assi[o] = 1;
+        acc += _loss(doj, d[0]); // return
+      } else {
+        assi[o] = 0;
+        acc += _loss(d[0], doj); // return
+      }
+    }
+    return acc;
+  }
+}
+</code></pre>
+        </article>
+    </section>
+</div>
+<br class="clear">
+<footer>
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Jun 14 2026 10:59:21 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+</footer>
+<script>prettyPrint();</script>
+<script src="scripts/polyfill.js"></script>
+<script src="scripts/linenumber.js"></script>
+</body>
+</html>