@iyulab/u-insight 0.3.1 → 0.5.0

package/README.md

@@ -243,6 +243,131 @@ C header: auto-generated via cbindgen (20 structs, 32 functions)
 - Rust 1.75+
 - Dependencies: `u-analytics`, `u-numflow`
 
+## WebAssembly / npm
+
+Available as an npm package via [wasm-pack](https://rustwasm.github.io/wasm-pack/).
+
+```bash
+npm install @iyulab/u-insight
+```
+
+### Quick Start
+
+```javascript
+import init, { describe, kmeans } from '@iyulab/u-insight';
+
+await init();
+const stats = describe({ col1: [1, 2, 3], col2: [4, 5, 6] });
+```
+
+### Functions
+
+#### `describe(data) -> [ColumnResult]`
+
+Descriptive statistics per column. Input: column-major `{ "col1": [1,2,3] }`.
+
+**Output:** Array of `{ name, data_type, numeric: { count, min, max, mean, median, std_dev, variance, skewness, kurtosis, q1, q3, iqr, p5, p95, ... } }`.
+
+#### `correlation_matrix(data) -> CorrelationResult`
+
+Pearson correlation matrix. Input: column-major `{ "col1": [1,2,3], "col2": [4,5,6] }`.
+
+**Output:**
+```json
+{ "names": ["col1","col2"], "matrix": [1,0.99,0.99,1], "n": 2, "high_pairs": [{ "col_a": "col1", "col_b": "col2", "r": 0.99, "p_value": 0.01 }] }
+```
+
+#### `kmeans(data, k) -> KMeansResult`
+
+K-Means++ clustering on row-major data `[[x,y,...], ...]`.
+
+**Output:**
+```json
+{ "k": 3, "labels": [0,0,1,1,2,2], "centroids": [[...]], "wcss": 5.2, "iterations": 12, "cluster_sizes": [2,2,2] }
+```
+
+#### `pca(data, n_components) -> PcaResult`
+
+Principal Component Analysis on row-major data.
+
+**Output:**
+```json
+{ "n_components": 2, "n_features": 4, "eigenvalues": [3.1,0.9], "explained_variance_ratio": [0.77,0.23], "cumulative_variance_ratio": [0.77,1.0], "loadings": [[...]], "scores": [[...]], "means": [...], "stds": [...] }
+```
+
+#### `dbscan(data, config) -> DbscanResult`
+
+DBSCAN density-based clustering. `config`: `{ "epsilon": 1.5, "min_samples": 3 }`.
+
+**Output:**
+```json
+{ "labels": [0,0,null,1,1], "n_clusters": 2, "noise_count": 1, "cluster_sizes": [2,2], "core_points": [true,true,false,true,true] }
+```
+
+#### `hierarchical(data, config) -> HierarchicalResult`
+
+Hierarchical agglomerative clustering. `config`: `{ "linkage": "ward", "n_clusters": 3 }` or `{ "linkage": "single", "distance_threshold": 5.0 }`.
+
+**Output:**
+```json
+{ "merges": [{ "cluster_a": 0, "cluster_b": 1, "distance": 1.2, "size": 2 }], "labels": [0,0,1,1,2], "n_clusters": 3 }
+```
+
+#### `isolation_forest(data, config) -> IsolationForestResult`
+
+Isolation Forest anomaly detection. `config`: `{ "n_estimators": 100, "contamination": 0.1, "seed": 42 }`.
+
+**Output:**
+```json
+{ "scores": [0.45, 0.82], "anomalies": [false, true], "threshold": 0.65, "anomaly_count": 1, "anomaly_fraction": 0.5 }
+```
+
+#### `lof(data, config) -> LofResult`
+
+Local Outlier Factor anomaly detection. `config`: `{ "k": 20, "threshold": 1.5 }`.
+
+**Output:**
+```json
+{ "scores": [1.0, 2.3], "anomalies": [false, true], "threshold": 1.5, "anomaly_count": 1, "anomaly_fraction": 0.5 }
+```
+
+#### `distribution_analysis(data, config) -> DistributionResult`
+
+Distribution analysis on a 1-D array. `config`: `{ "bin_method": "freedman_diaconis", "significance_level": 0.05, "compute_ecdf": true, "compute_histogram": true, "compute_qq_plot": true, "fit_distributions": false }`.
+
+**Output:**
+```json
+{ "n": 100, "ecdf": { "values": [...], "probabilities": [...] }, "histogram": { "n_bins": 10, "bin_width": 0.5, "edges": [...], "counts": [...] }, "qq_plot": { "theoretical": [...], "sample": [...] }, "normality": { "shapiro_wilk": { "statistic": 0.98, "p_value": 0.45, "rejected": false }, "is_normal": true }, "fits": [] }
+```
+
+#### `regression(data) -> RegressionResult`
+
+OLS regression analysis.
+
+**Input:**
+```json
+{ "predictors": { "x1": [1,2,3,4,5] }, "target": [2.1, 3.9, 6.1, 7.9, 10.1], "target_name": "y" }
+```
+
+**Output:**
+```json
+{ "target_name": "y", "predictor_names": ["x1"], "r_squared": 0.99, "adj_r_squared": 0.99, "coefficients": [0.1, 2.0], "p_values": [0.9, 0.0001], "vif": [1.0], "f_p_value": 0.0001 }
+```
+
+#### `feature_importance(data) -> FeatureImportanceResult`
+
+Feature importance via permutation, ANOVA, or mutual information.
+
+**Input:**
+```json
+{ "features": { "f1": [1,2,3], "f2": [5,4,3] }, "target": [0,0,1], "method": "permutation", "n_repeats": 5, "seed": 42 }
+```
+
+**Output:**
+```json
+{ "method": "permutation", "features": [{ "name": "f1", "index": 0, "score": 0.8, "std_dev": 0.1 }], "baseline_score": 0.5 }
+```
+
 ## Related
 
 - [u-analytics](https://github.com/iyulab/u-analytics) -- Statistical analytics

package/package.json

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

package/u_insight.d.ts

@@ -14,6 +14,21 @@
  */
 export function correlation_matrix(data_json: any): any;
 
+/**
+ * Runs DBSCAN density-based clustering on row-major data.
+ *
+ * # Input
+ *
+ * `data_json`: row-major points `[[x,y,...], ...]`
+ *
+ * `config_json`: `{ "epsilon": 1.5, "min_samples": 3 }`
+ *
+ * # Output
+ *
+ * `{ labels, n_clusters, noise_count, cluster_sizes, core_points }`
+ */
+export function dbscan(data_json: any, config_json: any): any;
+
 /**
  * Returns descriptive statistics for each column in a column-major dataset.
  *
@@ -27,6 +42,79 @@ export function correlation_matrix(data_json: any): any;
  */
 export function describe(data_json: any): any;
 
+/**
+ * Runs distribution analysis on a 1-D numeric array.
+ *
+ * # Input
+ *
+ * `data_json`: flat array `[1.0, 2.0, 3.0, ...]`
+ *
+ * `config_json`: `{ "bin_method": "freedman_diaconis", "significance_level": 0.05,
+ *   "compute_ecdf": true, "compute_histogram": true, "compute_qq_plot": true,
+ *   "fit_distributions": false }`
+ *
+ * # Output
+ *
+ * `{ n, ecdf, histogram, qq_plot, normality, fits }`
+ */
+export function distribution_analysis(data_json: any, config_json: any): any;
+
+/**
+ * Computes feature importance using one of three methods.
+ *
+ * # Input
+ *
+ * `data_json`:
+ * ```json
+ * {
+ *   "features": { "f1": [1,2,3,4,5], "f2": [5,4,3,2,1] },
+ *   "target": [0, 0, 1, 1, 1],
+ *   "method": "permutation",
+ *   "n_repeats": 5,
+ *   "seed": 42
+ * }
+ * ```
+ *
+ * Methods: `"permutation"` (regression target), `"anova"` (class target),
+ * `"mutual_info"` (class target).
+ *
+ * # Output
+ *
+ * `{ method, features: [{ name, index, score, std_dev?, p_value? }], baseline_score?, selected_indices? }`
+ */
+export function feature_importance(data_json: any): any;
+
+/**
+ * Runs hierarchical agglomerative clustering on row-major data.
+ *
+ * # Input
+ *
+ * `data_json`: row-major points `[[x,y,...], ...]`
+ *
+ * `config_json`: `{ "linkage": "ward", "n_clusters": 3 }` or
+ * `{ "linkage": "single", "distance_threshold": 5.0 }`
+ *
+ * # Output
+ *
+ * `{ merges, labels, n_clusters }`
+ */
+export function hierarchical(data_json: any, config_json: any): any;
+
+/**
+ * Runs Isolation Forest anomaly detection on row-major data.
+ *
+ * # Input
+ *
+ * `data_json`: row-major points `[[x,y,...], ...]`
+ *
+ * `config_json`: `{ "n_estimators": 100, "contamination": 0.1, "seed": 42 }`
+ *
+ * # Output
+ *
+ * `{ scores, anomalies, threshold, anomaly_count, anomaly_fraction }`
+ */
+export function isolation_forest(data_json: any, config_json: any): any;
+
 /**
  * Runs K-Means++ clustering on row-major data.
  *
@@ -40,6 +128,21 @@ export function describe(data_json: any): any;
  */
 export function kmeans(data_json: any, k: number): any;
 
+/**
+ * Runs Local Outlier Factor anomaly detection on row-major data.
+ *
+ * # Input
+ *
+ * `data_json`: row-major points `[[x,y,...], ...]`
+ *
+ * `config_json`: `{ "k": 20, "threshold": 1.5 }`
+ *
+ * # Output
+ *
+ * `{ scores, anomalies, threshold, anomaly_count, anomaly_fraction }`
+ */
+export function lof(data_json: any, config_json: any): any;
+
 /**
  * Runs Principal Component Analysis on row-major data.
  *
@@ -52,3 +155,23 @@ export function kmeans(data_json: any, k: number): any;
  * `{ n_components, n_features, eigenvalues, explained_variance_ratio, ... }`
  */
 export function pca(data_json: any, n_components: number): any;
+
+/**
+ * Runs OLS regression analysis.
+ *
+ * # Input
+ *
+ * `data_json`:
+ * ```json
+ * {
+ *   "predictors": { "x1": [1,2,3,4,5], "x2": [2,4,6,8,10] },
+ *   "target": [2.1, 3.9, 6.1, 7.9, 10.1],
+ *   "target_name": "y"
+ * }
+ * ```
+ *
+ * # Output
+ *
+ * `{ target_name, predictor_names, r_squared, adj_r_squared, coefficients, p_values, vif, f_p_value }`
+ */
+export function regression(data_json: any): any;

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 {
-    correlation_matrix, describe, kmeans, pca
+    correlation_matrix, dbscan, describe, distribution_analysis, feature_importance, hierarchical, isolation_forest, kmeans, lof, pca, regression
 } from "./u_insight_bg.js";

package/u_insight_bg.js

@@ -19,6 +19,30 @@ export function correlation_matrix(data_json) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Runs DBSCAN density-based clustering on row-major data.
+ *
+ * # Input
+ *
+ * `data_json`: row-major points `[[x,y,...], ...]`
+ *
+ * `config_json`: `{ "epsilon": 1.5, "min_samples": 3 }`
+ *
+ * # Output
+ *
+ * `{ labels, n_clusters, noise_count, cluster_sizes, core_points }`
+ * @param {any} data_json
+ * @param {any} config_json
+ * @returns {any}
+ */
+export function dbscan(data_json, config_json) {
+    const ret = wasm.dbscan(data_json, config_json);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Returns descriptive statistics for each column in a column-major dataset.
  *
@@ -40,6 +64,114 @@ export function describe(data_json) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Runs distribution analysis on a 1-D numeric array.
+ *
+ * # Input
+ *
+ * `data_json`: flat array `[1.0, 2.0, 3.0, ...]`
+ *
+ * `config_json`: `{ "bin_method": "freedman_diaconis", "significance_level": 0.05,
+ *   "compute_ecdf": true, "compute_histogram": true, "compute_qq_plot": true,
+ *   "fit_distributions": false }`
+ *
+ * # Output
+ *
+ * `{ n, ecdf, histogram, qq_plot, normality, fits }`
+ * @param {any} data_json
+ * @param {any} config_json
+ * @returns {any}
+ */
+export function distribution_analysis(data_json, config_json) {
+    const ret = wasm.distribution_analysis(data_json, config_json);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Computes feature importance using one of three methods.
+ *
+ * # Input
+ *
+ * `data_json`:
+ * ```json
+ * {
+ *   "features": { "f1": [1,2,3,4,5], "f2": [5,4,3,2,1] },
+ *   "target": [0, 0, 1, 1, 1],
+ *   "method": "permutation",
+ *   "n_repeats": 5,
+ *   "seed": 42
+ * }
+ * ```
+ *
+ * Methods: `"permutation"` (regression target), `"anova"` (class target),
+ * `"mutual_info"` (class target).
+ *
+ * # Output
+ *
+ * `{ method, features: [{ name, index, score, std_dev?, p_value? }], baseline_score?, selected_indices? }`
+ * @param {any} data_json
+ * @returns {any}
+ */
+export function feature_importance(data_json) {
+    const ret = wasm.feature_importance(data_json);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Runs hierarchical agglomerative clustering on row-major data.
+ *
+ * # Input
+ *
+ * `data_json`: row-major points `[[x,y,...], ...]`
+ *
+ * `config_json`: `{ "linkage": "ward", "n_clusters": 3 }` or
+ * `{ "linkage": "single", "distance_threshold": 5.0 }`
+ *
+ * # Output
+ *
+ * `{ merges, labels, n_clusters }`
+ * @param {any} data_json
+ * @param {any} config_json
+ * @returns {any}
+ */
+export function hierarchical(data_json, config_json) {
+    const ret = wasm.hierarchical(data_json, config_json);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Runs Isolation Forest anomaly detection on row-major data.
+ *
+ * # Input
+ *
+ * `data_json`: row-major points `[[x,y,...], ...]`
+ *
+ * `config_json`: `{ "n_estimators": 100, "contamination": 0.1, "seed": 42 }`
+ *
+ * # Output
+ *
+ * `{ scores, anomalies, threshold, anomaly_count, anomaly_fraction }`
+ * @param {any} data_json
+ * @param {any} config_json
+ * @returns {any}
+ */
+export function isolation_forest(data_json, config_json) {
+    const ret = wasm.isolation_forest(data_json, config_json);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Runs K-Means++ clustering on row-major data.
  *
@@ -62,6 +194,30 @@ export function kmeans(data_json, k) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Runs Local Outlier Factor anomaly detection on row-major data.
+ *
+ * # Input
+ *
+ * `data_json`: row-major points `[[x,y,...], ...]`
+ *
+ * `config_json`: `{ "k": 20, "threshold": 1.5 }`
+ *
+ * # Output
+ *
+ * `{ scores, anomalies, threshold, anomaly_count, anomaly_fraction }`
+ * @param {any} data_json
+ * @param {any} config_json
+ * @returns {any}
+ */
+export function lof(data_json, config_json) {
+    const ret = wasm.lof(data_json, config_json);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Runs Principal Component Analysis on row-major data.
  *
@@ -83,10 +239,42 @@ export function pca(data_json, n_components) {
     }
     return takeFromExternrefTable0(ret[0]);
 }
+
+/**
+ * Runs OLS regression analysis.
+ *
+ * # Input
+ *
+ * `data_json`:
+ * ```json
+ * {
+ *   "predictors": { "x1": [1,2,3,4,5], "x2": [2,4,6,8,10] },
+ *   "target": [2.1, 3.9, 6.1, 7.9, 10.1],
+ *   "target_name": "y"
+ * }
+ * ```
+ *
+ * # Output
+ *
+ * `{ target_name, predictor_names, r_squared, adj_r_squared, coefficients, p_values, vif, f_p_value }`
+ * @param {any} data_json
+ * @returns {any}
+ */
+export function regression(data_json) {
+    const ret = wasm.regression(data_json);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
 export function __wbg_Error_83742b46f01ce22d(arg0, arg1) {
     const ret = Error(getStringFromWasm0(arg0, arg1));
     return ret;
 }
+export function __wbg_Number_a5a435bd7bbec835(arg0) {
+    const ret = Number(arg0);
+    return ret;
+}
 export function __wbg_String_8564e559799eccda(arg0, arg1) {
     const ret = String(arg1);
     const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
@@ -94,6 +282,12 @@ export function __wbg_String_8564e559799eccda(arg0, arg1) {
     getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
 }
+export function __wbg___wbindgen_bigint_get_as_i64_447a76b5c6ef7bda(arg0, arg1) {
+    const v = arg1;
+    const ret = typeof(v) === 'bigint' ? v : undefined;
+    getDataViewMemory0().setBigInt64(arg0 + 8 * 1, isLikeNone(ret) ? BigInt(0) : ret, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, !isLikeNone(ret), true);
+}
 export function __wbg___wbindgen_boolean_get_c0f3f60bac5a78d1(arg0) {
     const v = arg0;
     const ret = typeof(v) === 'boolean' ? v : undefined;
@@ -106,6 +300,14 @@ export function __wbg___wbindgen_debug_string_5398f5bb970e0daa(arg0, arg1) {
     getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
 }
+export function __wbg___wbindgen_in_41dbb8413020e076(arg0, arg1) {
+    const ret = arg0 in arg1;
+    return ret;
+}
+export function __wbg___wbindgen_is_bigint_e2141d4f045b7eda(arg0) {
+    const ret = typeof(arg0) === 'bigint';
+    return ret;
+}
 export function __wbg___wbindgen_is_function_3c846841762788c1(arg0) {
     const ret = typeof(arg0) === 'function';
     return ret;
@@ -115,6 +317,14 @@ export function __wbg___wbindgen_is_object_781bc9f159099513(arg0) {
     const ret = typeof(val) === 'object' && val !== null;
     return ret;
 }
+export function __wbg___wbindgen_is_undefined_52709e72fb9f179c(arg0) {
+    const ret = arg0 === undefined;
+    return ret;
+}
+export function __wbg___wbindgen_jsval_eq_ee31bfad3e536463(arg0, arg1) {
+    const ret = arg0 === arg1;
+    return ret;
+}
 export function __wbg___wbindgen_jsval_loose_eq_5bcc3bed3c69e72b(arg0, arg1) {
     const ret = arg0 == arg1;
     return ret;
@@ -160,6 +370,10 @@ export function __wbg_get_unchecked_329cfe50afab7352(arg0, arg1) {
     const ret = arg0[arg1 >>> 0];
     return ret;
 }
+export function __wbg_get_with_ref_key_6412cf3094599694(arg0, arg1) {
+    const ret = arg0[arg1];
+    return ret;
+}
 export function __wbg_instanceof_ArrayBuffer_101e2bf31071a9f6(arg0) {
     let result;
     try {
@@ -184,6 +398,10 @@ export function __wbg_isArray_33b91feb269ff46e(arg0) {
     const ret = Array.isArray(arg0);
     return ret;
 }
+export function __wbg_isSafeInteger_ecd6a7f9c3e053cd(arg0) {
+    const ret = Number.isSafeInteger(arg0);
+    return ret;
+}
 export function __wbg_iterator_d8f549ec8fb061b1() {
     const ret = Symbol.iterator;
     return ret;