linreg-core 0.5.0 → 0.6.1

package/linreg_core.d.ts

@@ -95,6 +95,41 @@ export function breusch_pagan_test(y_json: string, x_vars_json: string): string;
  */
 export function cooks_distance_test(y_json: string, x_vars_json: string): string;
 
+/**
+ * Deserialize a serialized model, extracting the inner model data.
+ *
+ * This function takes a serialized model JSON (as created by serialize_model),
+ * validates the format version, and returns the inner model data as JSON.
+ *
+ * # Arguments
+ *
+ * * `json_string` - JSON string of the serialized model (with metadata wrapper)
+ *
+ * # Returns
+ *
+ * JSON string of the inner model data (coefficients, statistics, etc.),
+ * or a JSON error object if the input is invalid, the format version is
+ * incompatible, or the domain check fails.
+ *
+ * # Example
+ *
+ * ```javascript
+ * import { deserialize_model } from './linreg_core.js';
+ *
+ * // Load from file (browser-side)
+ * const response = await fetch('my_model.json');
+ * const serialized = await response.text();
+ *
+ * // Deserialize to get the model data
+ * const modelJson = deserialize_model(serialized);
+ * const model = JSON.parse(modelJson);
+ *
+ * console.log(model.coefficients);
+ * console.log(model.r_squared);
+ * ```
+ */
+export function deserialize_model(json_string: string): string;
+
 /**
  * Performs DFBETAS analysis via WASM.
  *
@@ -188,6 +223,46 @@ export function durbin_watson_test(y_json: string, x_vars_json: string): string;
  */
 export function elastic_net_regression(y_json: string, x_vars_json: string, _variable_names: string, lambda: number, alpha: number, standardize: boolean, max_iter: number, tol: number): string;
 
+/**
+ * Extract metadata from a serialized model without deserializing the full model.
+ *
+ * This function returns only the metadata portion of a serialized model,
+ * which includes information like model type, library version, creation time,
+ * and optional model name.
+ *
+ * # Arguments
+ *
+ * * `json_string` - JSON string of the serialized model
+ *
+ * # Returns
+ *
+ * JSON string containing the metadata object with fields:
+ * - `format_version` - Format version (e.g., "1.0")
+ * - `library_version` - linreg-core version used to create the model
+ * - `model_type` - Type of model ("OLS", "Ridge", etc.)
+ * - `created_at` - ISO 8601 timestamp of creation
+ * - `name` - Optional custom model name
+ *
+ * Returns a JSON error object if the input is invalid or the domain check fails.
+ *
+ * # Example
+ *
+ * ```javascript
+ * import { get_model_metadata } from './linreg_core.js';
+ *
+ * const response = await fetch('my_model.json');
+ * const serialized = await response.text();
+ *
+ * const metadataJson = get_model_metadata(serialized);
+ * const metadata = JSON.parse(metadataJson);
+ *
+ * console.log('Model type:', metadata.model_type);
+ * console.log('Created:', metadata.created_at);
+ * console.log('Name:', metadata.name || '(unnamed)');
+ * ```
+ */
+export function get_model_metadata(json_string: string): string;
+
 /**
  * Computes the inverse of the standard normal CDF (probit function).
  *
@@ -291,6 +366,110 @@ export function harvey_collier_test(y_json: string, x_vars_json: string): string
  */
 export function jarque_bera_test(y_json: string, x_vars_json: string): string;
 
+/**
+ * Performs K-Fold Cross Validation for Elastic Net regression via WASM.
+ *
+ * # Arguments
+ *
+ * * `y_json` - JSON array of response variable values
+ * * `x_vars_json` - JSON array of predictor arrays
+ * * `lambda` - Regularization strength (>= 0)
+ * * `alpha` - Mixing parameter (0 = Ridge, 1 = Lasso)
+ * * `standardize` - Whether to standardize predictors
+ * * `n_folds` - Number of folds (must be >= 2)
+ * * `shuffle_json` - JSON boolean: whether to shuffle data before splitting
+ * * `seed_json` - JSON string with seed number or "null" for no seed
+ *
+ * # Returns
+ *
+ * JSON string containing CV results (same structure as OLS).
+ *
+ * # Errors
+ *
+ * Returns a JSON error object if parsing fails, parameters are invalid,
+ * or domain check fails.
+ */
+export function kfold_cv_elastic_net(y_json: string, x_vars_json: string, lambda: number, alpha: number, standardize: boolean, n_folds: number, shuffle_json: string, seed_json: string): string;
+
+/**
+ * Performs K-Fold Cross Validation for Lasso regression via WASM.
+ *
+ * # Arguments
+ *
+ * * `y_json` - JSON array of response variable values
+ * * `x_vars_json` - JSON array of predictor arrays
+ * * `lambda` - Regularization strength (>= 0)
+ * * `standardize` - Whether to standardize predictors
+ * * `n_folds` - Number of folds (must be >= 2)
+ * * `shuffle_json` - JSON boolean: whether to shuffle data before splitting
+ * * `seed_json` - JSON string with seed number or "null" for no seed
+ *
+ * # Returns
+ *
+ * JSON string containing CV results (same structure as OLS).
+ *
+ * # Errors
+ *
+ * Returns a JSON error object if parsing fails, parameters are invalid,
+ * or domain check fails.
+ */
+export function kfold_cv_lasso(y_json: string, x_vars_json: string, lambda: number, standardize: boolean, n_folds: number, shuffle_json: string, seed_json: string): string;
+
+/**
+ * Performs K-Fold Cross Validation for OLS regression via WASM.
+ *
+ * # Arguments
+ *
+ * * `y_json` - JSON array of response variable values
+ * * `x_vars_json` - JSON array of predictor arrays
+ * * `variable_names_json` - JSON array of variable names
+ * * `n_folds` - Number of folds (must be >= 2)
+ * * `shuffle_json` - JSON boolean: whether to shuffle data before splitting
+ * * `seed_json` - JSON string with seed number or "null" for no seed
+ *
+ * # Returns
+ *
+ * JSON string containing CV results:
+ * - `n_folds` - Number of folds used
+ * - `n_samples` - Total number of observations
+ * - `mean_mse`, `std_mse` - Mean and std of MSE across folds
+ * - `mean_rmse`, `std_rmse` - Mean and std of RMSE across folds
+ * - `mean_mae`, `std_mae` - Mean and std of MAE across folds
+ * - `mean_r_squared`, `std_r_squared` - Mean and std of R² across folds
+ * - `fold_results` - Array of individual fold results
+ * - `fold_coefficients` - Array of coefficient arrays from each fold
+ *
+ * # Errors
+ *
+ * Returns a JSON error object if parsing fails, parameters are invalid,
+ * or domain check fails.
+ */
+export function kfold_cv_ols(y_json: string, x_vars_json: string, variable_names_json: string, n_folds: number, shuffle_json: string, seed_json: string): string;
+
+/**
+ * Performs K-Fold Cross Validation for Ridge regression via WASM.
+ *
+ * # Arguments
+ *
+ * * `y_json` - JSON array of response variable values
+ * * `x_vars_json` - JSON array of predictor arrays
+ * * `lambda` - Regularization strength (>= 0)
+ * * `standardize` - Whether to standardize predictors
+ * * `n_folds` - Number of folds (must be >= 2)
+ * * `shuffle_json` - JSON boolean: whether to shuffle data before splitting
+ * * `seed_json` - JSON string with seed number or "null" for no seed
+ *
+ * # Returns
+ *
+ * JSON string containing CV results (same structure as OLS).
+ *
+ * # Errors
+ *
+ * Returns a JSON error object if parsing fails, parameters are invalid,
+ * or domain check fails.
+ */
+export function kfold_cv_ridge(y_json: string, x_vars_json: string, lambda: number, standardize: boolean, n_folds: number, shuffle_json: string, seed_json: string): string;
+
 /**
  * Performs Lasso regression via WASM.
  *
@@ -592,6 +771,46 @@ export function reset_test(y_json: string, x_vars_json: string, powers_json: str
  */
 export function ridge_regression(y_json: string, x_vars_json: string, _variable_names: string, lambda: number, standardize: boolean): string;
 
+/**
+ * Serialize a model by wrapping its JSON data with metadata.
+ *
+ * This function takes a model's JSON representation (as returned by regression
+ * functions), wraps it with version and type metadata, and returns a serialized
+ * JSON string suitable for storage or download.
+ *
+ * # Arguments
+ *
+ * * `model_json` - JSON string of the model result (e.g., from ols_regression)
+ * * `model_type` - Type of model: "OLS", "Ridge", "Lasso", "ElasticNet", "WLS", or "LOESS"
+ * * `name` - Optional custom name for the model
+ *
+ * # Returns
+ *
+ * JSON string containing the serialized model with metadata, or a JSON error object
+ * if the input is invalid or the domain check fails.
+ *
+ * # Example
+ *
+ * ```javascript
+ * import { serialize_model, ols_regression } from './linreg_core.js';
+ *
+ * // Train a model
+ * const resultJson = ols_regression(yJson, xJson, namesJson);
+ *
+ * // Serialize it
+ * const serialized = serialize_model(resultJson, "OLS", "My Housing Model");
+ *
+ * // Download (browser-side)
+ * const blob = new Blob([serialized], { type: 'application/json' });
+ * const url = URL.createObjectURL(blob);
+ * const a = document.createElement('a');
+ * a.href = url;
+ * a.download = 'my_model.json';
+ * a.click();
+ * ```
+ */
+export function serialize_model(model_json: string, model_type: string, name?: string | null): string;
+
 /**
  * Performs the Shapiro-Wilk test for normality via WASM.
  *
@@ -807,6 +1026,48 @@ export function vif_test(y_json: string, x_vars_json: string): string;
  */
 export function white_test(y_json: string, x_vars_json: string, method: string): string;
 
+/**
+ * Performs Weighted Least Squares (WLS) regression via WASM.
+ *
+ * WLS regression allows each observation to have a different weight, which is
+ * useful for handling heteroscedasticity or when observations have different
+ * precision/variances.
+ *
+ * # Arguments
+ *
+ * * `y_json` - JSON array of response variable values
+ * * `x_vars_json` - JSON array of predictor arrays
+ * * `weights_json` - JSON array of observation weights (must be non-negative)
+ *
+ * # Returns
+ *
+ * JSON string containing:
+ * - `coefficients` - Coefficient values (including intercept as first element)
+ * - `standard_errors` - Standard errors of the coefficients
+ * - `t_statistics` - t-statistics for coefficient significance tests
+ * - `p_values` - Two-tailed p-values for coefficients
+ * - `r_squared` - R-squared (coefficient of determination)
+ * - `adj_r_squared` - Adjusted R-squared
+ * - `f_statistic` - F-statistic for overall model significance
+ * - `f_p_value` - p-value for F-statistic
+ * - `residual_std_error` - Residual standard error (sigma-hat estimate)
+ * - `df_residuals` - Degrees of freedom for residuals
+ * - `df_model` - Degrees of freedom for the model
+ * - `fitted_values` - Fitted values (predicted values)
+ * - `residuals` - Residuals (y - ŷ)
+ * - `mse` - Mean squared error
+ * - `rmse` - Root mean squared error
+ * - `mae` - Mean absolute error
+ * - `n` - Number of observations
+ * - `k` - Number of predictors (excluding intercept)
+ *
+ * # Errors
+ *
+ * Returns a JSON error object if parsing fails, parameters are invalid,
+ * or domain check fails.
+ */
+export function wls_regression(y_json: string, x_vars_json: string, weights_json: string): string;
+
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
@@ -815,13 +1076,19 @@ export interface InitOutput {
     readonly breusch_godfrey_test: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
     readonly breusch_pagan_test: (a: number, b: number, c: number, d: number) => [number, number];
     readonly cooks_distance_test: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly deserialize_model: (a: number, b: number) => [number, number];
     readonly dfbetas_test: (a: number, b: number, c: number, d: number) => [number, number];
     readonly dffits_test: (a: number, b: number, c: number, d: number) => [number, number];
     readonly durbin_watson_test: (a: number, b: number, c: number, d: number) => [number, number];
     readonly elastic_net_regression: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => [number, number];
+    readonly get_model_metadata: (a: number, b: number) => [number, number];
     readonly get_version: () => [number, number];
     readonly harvey_collier_test: (a: number, b: number, c: number, d: number) => [number, number];
     readonly jarque_bera_test: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly kfold_cv_elastic_net: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number) => [number, number];
+    readonly kfold_cv_lasso: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => [number, number];
+    readonly kfold_cv_ols: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => [number, number];
+    readonly kfold_cv_ridge: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => [number, number];
     readonly lasso_regression: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => [number, number];
     readonly loess_fit: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number];
     readonly loess_predict: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => [number, number];
@@ -833,6 +1100,7 @@ export interface InitOutput {
     readonly rainbow_test: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
     readonly reset_test: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number];
     readonly ridge_regression: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number];
+    readonly serialize_model: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
     readonly shapiro_wilk_test: (a: number, b: number, c: number, d: number) => [number, number];
     readonly stats_correlation: (a: number, b: number, c: number, d: number) => [number, number];
     readonly stats_mean: (a: number, b: number) => [number, number];
@@ -847,6 +1115,7 @@ export interface InitOutput {
     readonly test_t_critical: (a: number, b: number) => [number, number];
     readonly vif_test: (a: number, b: number, c: number, d: number) => [number, number];
     readonly white_test: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+    readonly wls_regression: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
     readonly get_t_cdf: (a: number, b: number) => number;
     readonly get_t_critical: (a: number, b: number) => number;
     readonly get_normal_inverse: (a: number) => number;