@danielsimonjr/mathts-functions 0.30.0 → 0.31.0

package/dist/ml/dbscan-knn.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Density-based clustering (DBSCAN) + k-nearest-neighbour classifier/regressor
+ * (Phase 3 Task 4 — ML primitives).
+ *
+ * All three functions share brute-force Euclidean-distance neighbour search.
+ * The library's exported `kdTree` (`typed/geometry.ts`) has no radius-query
+ * method, so DBSCAN's ε-neighborhoods are computed O(n²) brute-force here —
+ * correct, just not the asymptotically fastest option. A kd-tree range-search
+ * (and a kd-tree-backed k-NN search) is future work if this becomes a hot path.
+ */
+/**
+ * DBSCAN density-based clustering. A point is a **core point** if its
+ * ε-neighborhood (including itself) has at least `minPts` members; clusters
+ * are grown by expanding outward from core points through their neighbors
+ * (density-reachability). Points reached only from a core point's
+ * neighborhood but that are not themselves core are labeled as border points
+ * of that cluster; points never reached are **noise** (`-1`).
+ *
+ * @param points - Row-vectors (n × d)
+ * @param eps - Neighborhood radius (Euclidean)
+ * @param minPts - Minimum neighborhood size (including the point itself) for a core point
+ * @returns 0-based cluster label per point; `-1` marks noise
+ *
+ * @example
+ * dbscan([[0, 0], [0.1, 0.1], [10, 10], [50, 50]], 1.0, 2)
+ * // => [0, 0, -1, -1]  (one 2-point cluster, two noise points)
+ */
+export declare function dbscan(points: number[][], eps: number, minPts: number): number[];
+/**
+ * k-nearest-neighbour classifier: majority vote of the `k` closest training
+ * points (Euclidean distance). Ties are broken by the label of the single
+ * nearest point among the tied labels.
+ *
+ * @param train - Training row-vectors (n × d)
+ * @param labels - Training labels (length n)
+ * @param query - Query row-vectors (m × d)
+ * @param k - Number of neighbors
+ * @returns Predicted label per query row
+ */
+export declare function knnClassify(train: number[][], labels: (number | string)[], query: number[][], k: number): (number | string)[];
+/**
+ * k-nearest-neighbour regressor: mean of the `k` closest training targets
+ * (Euclidean distance).
+ *
+ * @param train - Training row-vectors (n × d)
+ * @param targets - Training targets (length n)
+ * @param query - Query row-vectors (m × d)
+ * @param k - Number of neighbors
+ * @returns Predicted (mean) target per query row
+ */
+export declare function knnRegress(train: number[][], targets: number[], query: number[][], k: number): number[];
+//# sourceMappingURL=dbscan-knn.d.ts.map

package/dist/ml/dbscan-knn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dbscan-knn.d.ts","sourceRoot":"","sources":["../../src/ml/dbscan-knn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAoBH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAoChF;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EAAE,EAAE,EACjB,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EAC3B,KAAK,EAAE,MAAM,EAAE,EAAE,EACjB,CAAC,EAAE,MAAM,GACR,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAwBrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EAAE,EAAE,EACjB,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,MAAM,EAAE,EAAE,EACjB,CAAC,EAAE,MAAM,GACR,MAAM,EAAE,CAMV"}

package/dist/ml/kde.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 1-D Gaussian kernel density estimation (Wave — ML primitives, Phase 3 Task 5).
+ *
+ * The first nonparametric density estimator in the library. Given samples
+ * `s_1..s_n`, estimates the density at query points via a sum of Gaussian
+ * "bumps" centered on each sample:
+ *
+ *   density(x) = (1 / (n * h)) * sum_i phi((x - s_i) / h)
+ *
+ * where `phi` is the standard normal pdf and `h` is the bandwidth. Bandwidth
+ * defaults to Silverman's rule of thumb, which balances bias (too smooth)
+ * against variance (too noisy) using the sample spread.
+ */
+export interface GaussianKDEOptions {
+    /** Bandwidth (smoothing parameter). Defaults to Silverman's rule of thumb. */
+    bandwidth?: number;
+}
+export interface GaussianKDEResult {
+    /** Evaluate the estimated density at each of `xs`. */
+    evaluate: (xs: number[]) => number[];
+    /** The bandwidth actually used (either supplied or Silverman's rule). */
+    bandwidth: number;
+}
+/**
+ * 1-D Gaussian kernel density estimation.
+ *
+ * @param samples - Observed sample values (n >= 2 for the default bandwidth;
+ *   a single sample requires an explicit `opts.bandwidth`)
+ * @param opts - `bandwidth` (default: Silverman's rule of thumb)
+ * @returns `evaluate(xs)` — density at each query point — and the chosen `bandwidth`
+ *
+ * @example
+ * const kde = gaussianKDE([-1, 0, 0, 1]);
+ * kde.evaluate([0]); // => density near the sample center (a single peak)
+ */
+export declare function gaussianKDE(samples: number[], opts?: GaussianKDEOptions): GaussianKDEResult;
+//# sourceMappingURL=kde.d.ts.map

package/dist/ml/kde.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kde.d.ts","sourceRoot":"","sources":["../../src/ml/kde.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;IACrC,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;CACnB;AAqDD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,kBAAuB,GAAG,iBAAiB,CAoB/F"}

package/dist/ml/logistic-regression.d.ts

@@ -0,0 +1,34 @@
+export interface LogisticRegressionOptions {
+    /** Prepend a column of ones (default true). */
+    intercept?: boolean;
+    /** Convergence tolerance on the max-norm of the Newton step (default 1e-8). */
+    tol?: number;
+    /** Maximum IRLS iterations (default 100). */
+    maxIter?: number;
+}
+export interface LogisticRegressionResult {
+    /** Fitted coefficients for the original predictors (excludes the intercept). */
+    coefficients: number[];
+    /** Fitted intercept (0 if `opts.intercept === false`). */
+    intercept: number;
+    /** Predict class probabilities (P(y=1|x)) for new rows. */
+    predictProba: (x: number[][]) => number[];
+    /** Predict class labels (threshold 0.5) for new rows. */
+    predict: (x: number[][]) => number[];
+}
+/**
+ * Binary logistic regression `P(y=1|x) = sigmoid(xᵀβ)` fit by IRLS (Newton-Raphson
+ * on the Bernoulli log-likelihood).
+ *
+ * @param X - Design matrix (rows = observations, cols = predictors)
+ * @param y - Binary labels, each in {0, 1}
+ * @param opts - `intercept` (default true) prepends a column of ones to X;
+ *   `tol` (default 1e-8) convergence tolerance; `maxIter` (default 100)
+ * @returns Fitted coefficients/intercept plus `predict`/`predictProba`
+ *
+ * @example
+ * const m = logisticRegression([[-2], [-1], [1], [2]], [0, 0, 1, 1]);
+ * m.predict([[3]]) // => [1]
+ */
+export declare function logisticRegression(X: number[][], y: number[], opts?: LogisticRegressionOptions): LogisticRegressionResult;
+//# sourceMappingURL=logistic-regression.d.ts.map

package/dist/ml/logistic-regression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logistic-regression.d.ts","sourceRoot":"","sources":["../../src/ml/logistic-regression.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,yBAAyB;IACxC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,gFAAgF;IAChF,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,KAAK,MAAM,EAAE,CAAC;IAC1C,yDAAyD;IACzD,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,KAAK,MAAM,EAAE,CAAC;CACtC;AAkBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,MAAM,EAAE,EAAE,EACb,CAAC,EAAE,MAAM,EAAE,EACX,IAAI,CAAC,EAAE,yBAAyB,GAC/B,wBAAwB,CAiG1B"}

package/dist/ml/ols.d.ts

@@ -0,0 +1,37 @@
+export interface OlsOptions {
+    /** Prepend a column of ones (default true). */
+    intercept?: boolean;
+}
+export interface OlsResult {
+    /** Fitted coefficients (intercept first, if included). */
+    coefficients: number[];
+    /** Standard error of each coefficient. */
+    stderr: number[];
+    /** t-statistic for each coefficient (H0: coefficient = 0). */
+    tValues: number[];
+    /** Two-sided p-value for each coefficient's t-statistic. */
+    pValues: number[];
+    /** Coefficient of determination. */
+    r2: number;
+    /** R² adjusted for the number of predictors. */
+    adjR2: number;
+    /** Overall model F-statistic (H0: all slope coefficients = 0). */
+    fStat: number;
+    /** Residuals y - Xβ. */
+    residuals: number[];
+}
+/**
+ * Multiple linear regression `y ≈ Xβ` by ordinary least squares (normal equations),
+ * with full inference: standard errors, t/p-values per coefficient, R²/adjusted-R²,
+ * the overall model F-statistic, and residuals.
+ *
+ * @param X - Design matrix (rows = observations, cols = predictors)
+ * @param y - Response vector (length = number of observations)
+ * @param opts - `intercept` (default true) prepends a column of ones to X
+ *
+ * @example
+ * ols([[1, 1], [2, 0], [3, 1], [4, 0]], [6, 5, 10, 9])
+ * // => coefficients ~= [1, 2, 3] (y = 1 + 2*x1 + 3*x2), r2 = 1
+ */
+export declare function ols(X: number[][], y: number[], opts?: OlsOptions): OlsResult;
+//# sourceMappingURL=ols.d.ts.map

package/dist/ml/ols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ols.d.ts","sourceRoot":"","sources":["../../src/ml/ols.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oCAAoC;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAqED;;;;;;;;;;;;GAYG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,SAAS,CAmC5E"}

package/dist/ml/regularized-regression.d.ts

@@ -0,0 +1,65 @@
+export interface RidgeOptions {
+    /** Center X/y and fit an unpenalized intercept (default true). */
+    intercept?: boolean;
+}
+export interface CoordinateDescentOptions extends RidgeOptions {
+    /** Maximum coordinate-descent sweeps (default 1000). */
+    maxIter?: number;
+    /** Convergence tolerance on the max coefficient change per sweep (default 1e-7). */
+    tol?: number;
+}
+export interface RegularizedRegressionResult {
+    /** Fitted coefficients, one per predictor column (intercept excluded). */
+    coefficients: number[];
+    /** Fitted intercept (0 if `opts.intercept === false`). */
+    intercept: number;
+}
+/**
+ * Ridge regression (L2-penalized least squares) with a closed-form solution on
+ * centered data: `β = (XᵀX + αI)⁻¹Xᵀy`. The intercept is never penalized.
+ *
+ * @param X - Design matrix (rows = observations, cols = predictors)
+ * @param y - Response vector (length = number of observations)
+ * @param alpha - L2 penalty strength (`alpha >= 0`; `alpha = 0` is OLS)
+ * @param opts - `intercept` (default true)
+ *
+ * @example
+ * ridge([[1], [2], [3], [4]], [2, 4, 6, 8], 0)
+ * // => { coefficients: [2], intercept: 0 } (recovers the exact OLS fit)
+ */
+export declare function ridge(X: number[][], y: number[], alpha: number, opts?: RidgeOptions): RegularizedRegressionResult;
+/**
+ * Lasso regression (L1-penalized least squares) via cyclic coordinate descent
+ * with soft-thresholding on standardized columns. Unlike ridge, large enough
+ * penalties drive coefficients to exactly 0 (sparse solutions). The intercept
+ * is never penalized.
+ *
+ * @param X - Design matrix (rows = observations, cols = predictors)
+ * @param y - Response vector (length = number of observations)
+ * @param alpha - L1 penalty strength (`alpha >= 0`; `alpha = 0` ~ OLS)
+ * @param opts - `intercept` (default true), `maxIter` (default 1000), `tol` (default 1e-7)
+ *
+ * @example
+ * lasso([[1], [2], [3], [4]], [2, 4, 6, 8], 100)
+ * // => coefficients[0] === 0 (penalty overwhelms the signal)
+ */
+export declare function lasso(X: number[][], y: number[], alpha: number, opts?: CoordinateDescentOptions): RegularizedRegressionResult;
+/**
+ * Elastic-net regression combining an L1 penalty (`alpha * l1Ratio`, soft-
+ * thresholded) and an L2 penalty (`alpha * (1 - l1Ratio)`, added to the
+ * coordinate-descent denominator) via the same cyclic coordinate descent as
+ * `lasso`. `l1Ratio = 1` is pure lasso; `l1Ratio = 0` is (coordinate-descent)
+ * ridge. The intercept is never penalized.
+ *
+ * @param X - Design matrix (rows = observations, cols = predictors)
+ * @param y - Response vector (length = number of observations)
+ * @param alpha - Overall penalty strength (`alpha >= 0`)
+ * @param l1Ratio - Mixing parameter in `[0, 1]` between L1 and L2
+ * @param opts - `intercept` (default true), `maxIter` (default 1000), `tol` (default 1e-7)
+ *
+ * @example
+ * elasticNet([[1], [2], [3], [4]], [2, 4, 6, 8], 0.1, 0.5)
+ * // => finite coefficients blending ridge shrinkage and lasso sparsity
+ */
+export declare function elasticNet(X: number[][], y: number[], alpha: number, l1Ratio: number, opts?: CoordinateDescentOptions): RegularizedRegressionResult;
+//# sourceMappingURL=regularized-regression.d.ts.map

package/dist/ml/regularized-regression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regularized-regression.d.ts","sourceRoot":"","sources":["../../src/ml/regularized-regression.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,wBAAyB,SAAQ,YAAY;IAC5D,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,2BAA2B;IAC1C,0EAA0E;IAC1E,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;CACnB;AAqDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CACnB,CAAC,EAAE,MAAM,EAAE,EAAE,EACb,CAAC,EAAE,MAAM,EAAE,EACX,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,YAAY,GAClB,2BAA2B,CAwB7B;AAyDD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CACnB,CAAC,EAAE,MAAM,EAAE,EAAE,EACb,CAAC,EAAE,MAAM,EAAE,EACX,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,wBAAwB,GAC9B,2BAA2B,CAc7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CACxB,CAAC,EAAE,MAAM,EAAE,EAAE,EACb,CAAC,EAAE,MAAM,EAAE,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,wBAAwB,GAC9B,2BAA2B,CAiB7B"}

package/dist/stats/inference-extra.d.ts

@@ -0,0 +1,46 @@
+/** Result of {@link chi2Contingency}. */
+export interface Chi2ContingencyResult {
+    chi2: number;
+    pValue: number;
+    dof: number;
+    expected: number[][];
+    cramersV: number;
+}
+/** Options for {@link chi2Contingency}. */
+export interface Chi2ContingencyOptions {
+    /** Apply the Yates continuity correction on 2x2 tables. Default true (matches scipy). */
+    correction?: boolean;
+}
+/**
+ * Chi-square test of independence on a contingency table.
+ *
+ * Expected counts `E_ij = rowSum_i * colSum_j / total`. `chi2 = sum((O_ij -
+ * E_ij)^2 / E_ij)`, with the Yates continuity correction
+ * `(|O_ij - E_ij| - 0.5)^2 / E_ij` applied on 2x2 tables when
+ * `opts.correction !== false` (default true, matching
+ * `scipy.stats.chi2_contingency`). `dof = (rows - 1) * (cols - 1)`; `pValue =
+ * 1 - chiSquaredCDF(chi2, dof)`. `cramersV = sqrt(chi2 / (total *
+ * min(rows-1, cols-1)))`.
+ *
+ * @example
+ * chi2Contingency([[10, 20], [30, 40]], { correction: false });
+ * // { chi2: 0.7937, pValue: 0.373, dof: 1, expected: [[12, 18], [28, 42]], cramersV }
+ */
+export declare function chi2Contingency(table: readonly (readonly number[])[], opts?: Chi2ContingencyOptions): Chi2ContingencyResult;
+/** Supported multiple-testing correction methods. */
+export type MultipleTestMethod = 'bonferroni' | 'holm' | 'bh';
+/**
+ * Multiple-testing p-value adjustment, returned in the original input order.
+ * Matches `statsmodels.stats.multitest.multipletests`.
+ *
+ * - `bonferroni`: `min(1, p_i * n)`.
+ * - `holm` (step-down): sort ascending; adjusted_(k) = `min(1, max_{j<=k}
+ *   (n - j + 1) * p_(j))`, enforced monotonic non-decreasing.
+ * - `bh` (Benjamini-Hochberg FDR, step-up): sort ascending; adjusted_(k) =
+ *   `min(1, min_{j>=k} (n / j) * p_(j))`, enforced monotonic non-decreasing
+ *   from the largest p-value down.
+ *
+ * @example multipleTest([0.01, 0.04, 0.5], 'bonferroni'); // [0.03, 0.12, 1]
+ */
+export declare function multipleTest(pValues: readonly number[], method: MultipleTestMethod): number[];
+//# sourceMappingURL=inference-extra.d.ts.map

package/dist/stats/inference-extra.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference-extra.d.ts","sourceRoot":"","sources":["../../src/stats/inference-extra.ts"],"names":[],"mappings":"AAaA,yCAAyC;AACzC,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,yFAAyF;IACzF,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACrC,IAAI,GAAE,sBAA2B,GAChC,qBAAqB,CA0CvB;AAED,qDAAqD;AACrD,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,MAAM,GAAG,IAAI,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAiC7F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/mathts-functions",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Mathematical functions for MathTS - arithmetic, algebra, trigonometry, statistics, and more",
   "author": "Daniel Simon Jr.",
   "license": "MIT",