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_fasterpam.mjs.html ADDED Viewed

@@ -0,0 +1,305 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>k-medoids/fasterpam.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/fasterpam.mjs</h1>
+    <section>
+        <article>
+            <pre class="prettyprint source linenums"><code>// FasterPAM algorithm, ported 1:1 from src/fasterpam.rs
+import { arrayAdapter } from './arrayadapter.mjs';
+import { Rec, DistancePair, U32_MAX, find_min, choose_medoid_within_partition } from './util.mjs';
+import { shuffle } from './initialization.mjs';
+/**
+ * Run the FasterPAM algorithm.
+ *
+ * If used multiple times, it is better to additionally shuffle the input data,
+ * to increase randomness of the solutions found and hence increase the chance
+ * of finding a better solution.
+ *
+ * @param mat - a pairwise distance matrix
+ * @param med - the list of medoids (mutated in place)
+ * @param maxiter - the maximum number of iterations allowed
+ * @returns { loss, assi, nIter, nSwaps }
+ *
+ * Panics (throws) when the dissimilarity matrix is not square, or k is 0 or larger than N.
+ */
+export function fasterpam(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 };
+  }
+  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 >= 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);
+  return { loss, assi, nIter: iter, nSwaps: n_swaps };
+}
+/**
+ * Run the FasterPAM algorithm with additional randomization.
+ *
+ * This increases the chance of finding a better solution when used multiple times,
+ * as it decreases the dependency on the input data order.
+ *
+ * @param mat - a pairwise distance matrix
+ * @param med - the list of medoids (mutated in place)
+ * @param maxiter - the maximum number of iterations allowed
+ * @param rng - random number generator for shuffling the input data
+ * @returns { loss, assi, nIter, nSwaps }
+ */
+export function rand_fasterpam(mat, med, maxiter, rng = Math.random) {
+  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 };
+  }
+  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;
+  const seq = shuffle(rng, n); // random shuffling
+  while (iter &lt; maxiter) {
+    iter += 1;
+    const swaps_before = n_swaps, lastloss = loss;
+    for (const j of seq) {
+      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 >= 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);
+  return { loss, assi, nIter: iter, nSwaps: n_swaps };
+}
+/** Perform the initial assignment to medoids. Returns [loss, data] with data = Rec[]. */
+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 = Array.from({ length: mat.len() }, () => Rec.empty());
+  const firstcenter = med[0];
+  let loss = 0;
+  for (let i = 0; i &lt; data.length; i++) {
+    // *cur = Rec::new(...): overwrite the slot with a fresh Rec, then mutate it
+    data[i] = new Rec(0, mat.get(i, firstcenter), U32_MAX, 0);
+    const curRec = data[i];
+    for (let m = 1; m &lt; med.length; m++) {
+      const me = med[m];
+      const d = mat.get(i, me);
+      if (d &lt; curRec.near.d || i === me) {
+        curRec.seco = curRec.near.clone();
+        curRec.near = new DistancePair(m, d);
+      } else if (curRec.seco.i === U32_MAX || d &lt; curRec.seco.d) {
+        curRec.seco = new DistancePair(m, d);
+      }
+    }
+    loss += curRec.near.d;
+  }
+  return [loss, data];
+}
+/** Find the best swap for object j - FastPAM 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);
+    // New medoid is closest:
+    if (doj &lt; reco.near.d) {
+      acc += doj - reco.near.d;
+      // loss already includes ds - dn, remove
+      ploss[reco.near.i] += reco.near.d - reco.seco.d;
+    } else if (doj &lt; reco.seco.d) {
+      // loss already includes ds - dn, adjust to d(xo) - dn
+      ploss[reco.near.i] += doj - reco.seco.d;
+    }
+  }
+  const [b, bloss] = find_min(ploss);
+  return [bloss + acc, b]; // add the shared accumulator
+}
+/** Update the loss when removing each medoid. Mutates lossArr. */
+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] += rec.seco.d - rec.near.d;
+    // as N might be unsigned
+  }
+}
+/** Update the second nearest medoid information. Called after each swap. Returns a fresh DistancePair. */
+export function update_second_nearest(mat, med, n, b, o, doj) {
+  let s = new DistancePair(b, doj);
+  for (let i = 0; i &lt; med.length; i++) {
+    const mi = med[i];
+    if (i === n || i === b) {
+      continue;
+    }
+    const d = mat.get(o, mi);
+    if (d &lt; s.d) {
+      s = new DistancePair(i, d);
+    }
+  }
+  return s;
+}
+/** Perform a single swap. Returns the RAW summed loss (sum of near.d). */
+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) {
+        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 {
+        reco.near = reco.seco.clone();
+        reco.seco = update_second_nearest(mat, med, reco.near.i, b, o, doj);
+      }
+    } else {
+      // nearest not removed
+      if (doj &lt; reco.near.d) {
+        reco.seco = reco.near.clone();
+        reco.near = new DistancePair(b, doj);
+      } else if (doj &lt; reco.seco.d) {
+        reco.seco = new DistancePair(b, doj);
+      } else if (reco.seco.i === b) {
+        // second nearest was replaced
+        reco.seco = update_second_nearest(mat, med, reco.near.i, b, o, doj);
+      }
+    }
+    acc += reco.near.d;
+  }
+  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>

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

@@ -0,0 +1,166 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>k-medoids/fastmsc.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/fastmsc.mjs</h1>
+    <section>
+        <article>
+            <pre class="prettyprint source linenums"><code>// Ported 1:1 from src/fastmsc.rs (FastMSC algorithm).
+import { arrayAdapter } from './arrayadapter.mjs';
+import { USIZE_MAX, choose_medoid_within_partition } from './util.mjs';
+import { initial_assignment, update_removal_loss, find_best_swap, do_swap, initial_assignment_k2, find_best_swap_k2, do_swap_k2 } from './fastermsc.mjs';
+/**
+ * Run the FastMSC algorithm, which yields the same results as the original PAMMEDSIL.
+ *
+ * This is faster than PAMMEDSIL, but slower than FasterMSC, and mostly of interest for academic reasons.
+ * This is the improved version, which costs O(n^2) per iteration to find the best swap.
+ *
+ * @param {object} mat - a pairwise distance matrix
+ * @param {number[]} med - the list of medoids (mutated in place)
+ * @param {number} maxiter - the maximum number of iterations allowed
+ * returns { loss, assi, nIter, nSwaps }
+ */
+export function fastmsc(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 fastmsc_k2(mat, med, maxiter);
+  }
+  let [loss, data] = initial_assignment(mat, med);
+  let removal_loss = new Array(k).fill(0);
+  let n_swaps = 0, iter = 0;
+  while (iter &lt; maxiter) {
+    iter += 1;
+    let best = [0, USIZE_MAX, USIZE_MAX];
+    update_removal_loss(data, removal_loss);
+    for (let j = 0; j &lt; n; j++) {
+      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;= best[0]) {
+        continue; // No improvement
+      }
+      best = [change, b, j];
+    }
+    if (best[0] > 0) {
+      n_swaps += 1;
+      // perform the swap
+      const newloss = do_swap(mat, med, data, best[1], best[2]);
+      if (newloss >= loss) {
+        break; // Probably numerically unstable now.
+      }
+      loss = newloss;
+    } else {
+      break; // No improvement, or NaN.
+    }
+  }
+  const assi = data.map((x) => x.near.i);
+  loss = 1 - loss / n;
+  return { loss, assi, nIter: iter, nSwaps: n_swaps };
+}
+/** Special case k=2 of the FastMSC algorithm. */
+function fastmsc_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 n_swaps = 0, iter = 0;
+  while (iter &lt; maxiter) {
+    iter += 1;
+    let best = [0, k, USIZE_MAX];
+    for (let j = 0; j &lt; n; j++) {
+      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 (best[2] === USIZE_MAX || newloss &lt; best[0]) {
+        best = [newloss, b, j];
+      }
+    }
+    if (!(best[0] &lt; loss)) {
+      break; // No improvement
+    }
+    // perform the swap
+    n_swaps += 1;
+    const newloss = do_swap_k2(mat, med, assi, data, best[1], best[2]);
+    if (!(newloss &lt; loss)) {
+      break; // Probably numerically unstable
+    }
+    loss = newloss;
+  }
+  loss = 1 - loss / n;
+  return { loss, assi, nIter: iter, nSwaps: n_swaps };
+}
+</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>

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

@@ -0,0 +1,132 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>k-medoids/fastpam1.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/fastpam1.mjs</h1>
+    <section>
+        <article>
+            <pre class="prettyprint source linenums"><code>import { arrayAdapter } from './arrayadapter.mjs';
+import { USIZE_MAX, choose_medoid_within_partition } from './util.mjs';
+import { initial_assignment, find_best_swap, do_swap, update_removal_loss } from './fasterpam.mjs';
+/**
+ * Run the FastPAM1 algorithm, which yields the same results as the original PAM.
+ *
+ * This is faster than PAM, but slower than FasterPAM, and mostly of interest for academic reasons.
+ * Quality-wise, FasterPAM is not worse on average, but much faster.
+ *
+ * This is the improved version from the journal version of the paper,
+ * which costs O(n²) per iteration to find the best swap.
+ *
+ * @param {object} mat - a pairwise distance matrix (array or wrapped)
+ * @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, nSwaps: number }}
+ */
+export function fastpam1(mat, med, maxiter) {
+	mat = arrayAdapter(mat);
+	const n = mat.len();
+	const 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 };
+	}
+	let [loss, data] = initial_assignment(mat, med);
+	const removal_loss = new Array(k).fill(0);
+	let n_swaps = 0;
+	let iter = 0;
+	while (iter &lt; maxiter) {
+		iter += 1;
+		let best = [0, USIZE_MAX, USIZE_MAX];
+		update_removal_loss(data, removal_loss);
+		for (let j = 0; j &lt; n; j++) {
+			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 >= best[0]) {
+				continue; // No improvement
+			}
+			best = [change, b, j];
+		}
+		if (best[0] &lt; 0) {
+			n_swaps += 1;
+			// perform the swap
+			const newloss = do_swap(mat, med, data, best[1], best[2]);
+			if (newloss >= loss) {
+				break; // Probably numerically unstable now.
+			}
+			loss = newloss;
+		} else {
+			break; // No improvement, or NaN.
+		}
+	}
+	const assi = data.map(x => x.near.i);
+	return { loss, assi, nIter: iter, nSwaps: n_swaps };
+}
+</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>