@iyulab/u-insight 0.9.1 → 0.10.0

package/README.md

@@ -303,6 +303,17 @@ K-Means++ clustering on row-major data `[[x,y,...], ...]`.
 { "k": 3, "labels": [0,0,1,1,2,2], "centroids": [[...]], "wcss": 5.2, "iterations": 12, "cluster_sizes": [2,2,2] }
 ```
 
+#### `silhouette(data, labels, k) -> SilhouetteResult`
+
+Silhouette analysis for an existing clustering assignment. Works with any clustering output (`kmeans`, `dbscan`, `hierarchical`, etc.). `data` is row-major `[[x,y,...], ...]`, `labels` is one cluster id per row (each `< k`), `k` is the number of distinct clusters. O(n²) — use sparingly on very large inputs.
+
+**Output:**
+```json
+{ "avg": 0.74, "per_sample": [0.81, 0.79, 0.62, ...] }
+```
+
+`avg` ranges from -1 (wrong cluster) to +1 (well-separated); singleton-cluster points report 0.0 in `per_sample`.
+
 #### `pca(data, n_components) -> PcaResult`
 
 Principal Component Analysis on row-major data.

package/package.json

@@ -5,7 +5,7 @@
     "iyulab"
   ],
   "description": "Statistical analysis and data profiling engine with C FFI bindings.",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/u_insight.d.ts

@@ -221,6 +221,23 @@ export function pca(data_json: any, n_components: number): any;
  */
 export function regression(data_json: any): any;
 
+/**
+ * Computes silhouette scores for an existing clustering assignment.
+ *
+ * # Input
+ * `data_json`: row-major points `[[x,y,...], ...]`
+ * `labels_json`: cluster id per sample `[0, 0, 1, 1, ...]` (each value `< k`)
+ * `k`: number of distinct clusters
+ *
+ * # Output
+ * `{ avg, per_sample }` — `avg` is the mean silhouette across samples that
+ * had a defined silhouette; `per_sample[i]` is the silhouette of sample `i`
+ * (0.0 for singleton-cluster points).
+ *
+ * O(n²) — use sparingly on very large inputs.
+ */
+export function silhouette(data_json: any, labels_json: any, k: number): any;
+
 /**
  * Variance Inflation Factor diagnostics for column-major numeric data.
  *

package/u_insight.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./u_insight_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    condition_number_diagnostic, correlation_matrix, dbscan, describe, detect_univariate_outliers, distribution_analysis, feature_importance, hierarchical, isolation_forest, kmeans, lof, pca, regression, vif_diagnostic
+    condition_number_diagnostic, correlation_matrix, dbscan, describe, detect_univariate_outliers, distribution_analysis, feature_importance, hierarchical, isolation_forest, kmeans, lof, pca, regression, silhouette, vif_diagnostic
 } from "./u_insight_bg.js";

package/u_insight_bg.js

@@ -329,6 +329,33 @@ export function regression(data_json) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Computes silhouette scores for an existing clustering assignment.
+ *
+ * # Input
+ * `data_json`: row-major points `[[x,y,...], ...]`
+ * `labels_json`: cluster id per sample `[0, 0, 1, 1, ...]` (each value `< k`)
+ * `k`: number of distinct clusters
+ *
+ * # Output
+ * `{ avg, per_sample }` — `avg` is the mean silhouette across samples that
+ * had a defined silhouette; `per_sample[i]` is the silhouette of sample `i`
+ * (0.0 for singleton-cluster points).
+ *
+ * O(n²) — use sparingly on very large inputs.
+ * @param {any} data_json
+ * @param {any} labels_json
+ * @param {number} k
+ * @returns {any}
+ */
+export function silhouette(data_json, labels_json, k) {
+    const ret = wasm.silhouette(data_json, labels_json, k);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Variance Inflation Factor diagnostics for column-major numeric data.
  *