regressio 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,545 @@
+/**
+* Computation engine abstraction.
+* Default: pure TypeScript. Call useWasmEngine() to switch to WASM backend.
+*
+* The WASM engine accelerates: matrix multiply, QR decomposition, Cholesky, back-substitution.
+* All other operations remain in TypeScript.
+*/
+interface WasmModule {
+	matrix_multiply(a: Float64Array, a_rows: number, a_cols: number, b: Float64Array, b_rows: number, b_cols: number): Float64Array;
+	qr_decompose(data: Float64Array, rows: number, cols: number): Float64Array;
+	cholesky(data: Float64Array, n: number): Float64Array;
+	solve_triangular(r: Float64Array, b: Float64Array, n: number): Float64Array;
+}
+interface ComputeEngine {
+	name: "typescript" | "wasm";
+	wasm?: WasmModule;
+}
+/** Get the current computation engine. */
+declare function getEngine(): ComputeEngine;
+/** Check if the WASM engine is active. */
+declare function isWasmActive(): boolean;
+/**
+* Switch to the WASM computation engine for faster matrix operations.
+* Requires the regressio WASM package to be built:
+*   cd rust && wasm-pack build --target bundler --out-dir ../pkg
+*/
+declare function useWasmEngine(): Promise<void>;
+/**
+* Load WASM engine from a pre-loaded module (useful for custom bundler setups).
+*/
+declare function useWasmModule(wasmModule: WasmModule): void;
+/** Reset to the default TypeScript engine. */
+declare function useTypescriptEngine(): void;
+/**
+* Matrix class backed by a flat Float64Array in row-major order.
+* Provides all linear algebra primitives needed by the regression models.
+* Matrix multiply is dispatched to the WASM engine when available.
+*/
+declare class Matrix {
+	readonly rows: number;
+	readonly cols: number;
+	readonly data: Float64Array;
+	constructor(rows: number, cols: number, data?: Float64Array | number[]);
+	static fromArray(arr: number[][]): Matrix;
+	static zeros(rows: number, cols: number): Matrix;
+	static ones(rows: number, cols: number): Matrix;
+	static identity(n: number): Matrix;
+	static columnVector(arr: number[]): Matrix;
+	static rowVector(arr: number[]): Matrix;
+	static diagonal(values: number[]): Matrix;
+	get(i: number, j: number): number;
+	set(i: number, j: number, value: number): void;
+	getColumn(j: number): Matrix;
+	getRow(i: number): Matrix;
+	setColumn(j: number, col: Matrix): void;
+	transpose(): Matrix;
+	/** Matrix multiplication — dispatched to WASM engine when available. */
+	multiply(other: Matrix): Matrix;
+	add(other: Matrix): Matrix;
+	subtract(other: Matrix): Matrix;
+	scale(scalar: number): Matrix;
+	addInPlace(other: Matrix): void;
+	subtractInPlace(other: Matrix): void;
+	scaleInPlace(scalar: number): void;
+	/** Frobenius norm: sqrt(sum of squares). */
+	norm(): number;
+	/** Trace: sum of diagonal elements (square matrices only). */
+	trace(): number;
+	/** Determinant (square matrices only, via LU-like elimination). */
+	determinant(): number;
+	submatrix(rowStart: number, rowEnd: number, colStart: number, colEnd: number): Matrix;
+	clone(): Matrix;
+	toArray(): number[][];
+	toFlatArray(): number[];
+	/** Dot product for two column vectors. */
+	dot(other: Matrix): number;
+	private assertSameDimensions;
+}
+/** A 1D array of numbers (single feature or response vector). */
+type DataVector = number[];
+/** A 2D array of numbers (multiple features, rows = observations, cols = features). */
+type DataMatrix = number[][];
+/** Input data: 1D (single feature) auto-converts to 2D internally. */
+type DataInput = DataVector | DataMatrix;
+interface BaseModelOptions {
+	/** Whether to fit an intercept term (default: true). */
+	fitIntercept?: boolean;
+}
+interface RegularizedOptions extends BaseModelOptions {
+	/** Regularization strength (default: 1.0). */
+	alpha?: number;
+}
+interface ElasticNetOptions extends RegularizedOptions {
+	/** L1 ratio: 1 = pure Lasso, 0 = pure Ridge (default: 0.5). */
+	l1Ratio?: number;
+	/** Maximum iterations for coordinate descent (default: 1000). */
+	maxIterations?: number;
+	/** Convergence tolerance (default: 1e-4). */
+	tolerance?: number;
+}
+interface LassoOptions extends RegularizedOptions {
+	/** Maximum iterations for coordinate descent (default: 1000). */
+	maxIterations?: number;
+	/** Convergence tolerance (default: 1e-4). */
+	tolerance?: number;
+}
+interface PolynomialOptions extends BaseModelOptions {
+	/** Polynomial degree (default: 2). */
+	degree?: number;
+}
+interface WeightedOptions extends BaseModelOptions {
+	/** Observation weights — higher = more reliable. */
+	weights?: DataVector;
+}
+interface RobustOptions extends BaseModelOptions {
+	/** M-estimator method (default: "huber"). */
+	method?: "huber" | "tukey";
+	/** Tuning constant. Huber default: 1.345, Tukey default: 4.685. */
+	tuningConstant?: number;
+	/** Maximum IRLS iterations (default: 50). */
+	maxIterations?: number;
+	/** Convergence tolerance (default: 1e-4). */
+	tolerance?: number;
+}
+interface LogisticOptions extends BaseModelOptions {
+	/** Maximum iterations for IRLS (default: 100). */
+	maxIterations?: number;
+	/** Convergence tolerance (default: 1e-6). */
+	tolerance?: number;
+}
+interface FitResult {
+	/** Coefficients (excluding intercept). */
+	coefficients: number[];
+	/** Intercept term (0 if fitIntercept is false). */
+	intercept: number;
+}
+interface RegressionStatistics {
+	/** Coefficient of determination. */
+	rSquared: number;
+	/** Adjusted R-squared (penalises extra predictors). */
+	adjustedRSquared: number;
+	/** Standard errors of coefficients. */
+	standardErrors: number[];
+	/** t-statistics for each coefficient. */
+	tStatistics: number[];
+	/** Two-tailed p-values for each coefficient. */
+	pValues: number[];
+	/** 95 % confidence intervals for each coefficient [lower, upper]. */
+	confidenceIntervals: [number, number][];
+	/** F-statistic for overall model significance. */
+	fStatistic: number;
+	/** p-value for the F-statistic. */
+	fPValue: number;
+	/** Residual standard error (σ̂). */
+	residualStandardError: number;
+	/** Akaike Information Criterion. */
+	aic: number;
+	/** Bayesian Information Criterion. */
+	bic: number;
+	/** Residual degrees of freedom (n − p − 1). */
+	degreesOfFreedom: number;
+	/** Number of observations. */
+	nObservations: number;
+}
+interface ConfusionMatrix {
+	truePositives: number;
+	trueNegatives: number;
+	falsePositives: number;
+	falseNegatives: number;
+}
+interface ClassificationStatistics {
+	accuracy: number;
+	precision: number;
+	recall: number;
+	f1Score: number;
+	confusionMatrix: ConfusionMatrix;
+	/** McFadden's pseudo R-squared. */
+	pseudoRSquared: number;
+	/** Log-likelihood of the fitted model. */
+	logLikelihood: number;
+	/** AIC. */
+	aic: number;
+	/** BIC. */
+	bic: number;
+}
+interface ResidualDiagnostics {
+	/** Raw residuals (y − ŷ). */
+	raw: number[];
+	/** Studentized residuals. */
+	studentized: number[];
+	/** Cook's distance for each observation. */
+	cooksDistance: number[];
+	/** Leverage (hat matrix diagonal) for each observation. */
+	leverage: number[];
+}
+interface TestResult {
+	/** Test statistic value. */
+	statistic: number;
+	/** p-value. */
+	pValue: number;
+}
+interface PredictionInterval {
+	/** Point prediction ŷ. */
+	predicted: number;
+	/** Lower bound. */
+	lower: number;
+	/** Upper bound. */
+	upper: number;
+}
+interface BootstrapResult {
+	/** Mean of bootstrapped coefficients. */
+	coefficients: number[];
+	/** Empirical confidence intervals for each coefficient [lower, upper]. */
+	confidenceIntervals: [number, number][];
+	/** Bootstrap standard errors. */
+	standardErrors: number[];
+}
+interface ScalingParams {
+	means: number[];
+	stds: number[];
+}
+interface NormalizationParams {
+	mins: number[];
+	maxs: number[];
+}
+/**
+* Compute Variance Inflation Factor for each feature.
+* VIF_j = 1 / (1 - R²_j) where R²_j is from regressing x_j on all other x's.
+* VIF > 10 signals multicollinearity.
+*/
+declare function vif(X: DataMatrix): number[];
+/**
+* Compute pairwise Pearson correlation matrix.
+* Returns p×p matrix of correlations.
+*/
+declare function correlationMatrix(X: DataMatrix): number[][];
+/**
+* Compute the condition number of X: κ = σ_max / σ_min.
+* κ > 30 signals potential numerical instability from multicollinearity.
+*/
+declare function conditionNumber(X: DataMatrix): number;
+/**
+* Compute residual diagnostics for a fitted linear model.
+* @param X Feature matrix (without intercept column)
+* @param y Response vector
+* @param yHat Predicted values
+* @param fitIntercept Whether the model included an intercept
+*/
+declare function residualDiagnostics(X: DataMatrix, y: DataVector, yHat: DataVector, fitIntercept?: boolean): ResidualDiagnostics;
+/** Compute just the leverage (hat matrix diagonal) values. */
+declare function leverage(X: DataMatrix, fitIntercept?: boolean): number[];
+/** Compute Cook's distance for each observation. */
+declare function cooksDistance2(X: DataMatrix, y: DataVector, yHat: DataVector, fitIntercept?: boolean): number[];
+/** Compute studentized residuals. */
+declare function studentizedResiduals(X: DataMatrix, y: DataVector, yHat: DataVector, fitIntercept?: boolean): number[];
+/**
+* Durbin-Watson test for autocorrelation in residuals.
+* DW ∈ [0,4], ~2 = no autocorrelation, <2 = positive, >2 = negative.
+*/
+declare function durbinWatson(residuals: DataVector): TestResult;
+/**
+* Breusch-Pagan test for heteroscedasticity.
+* Regresses squared residuals on X, uses Chi² test statistic = n * R².
+*/
+declare function breuschPagan(X: DataMatrix, residuals: DataVector): TestResult;
+/**
+* Shapiro-Wilk test for normality (simplified version for n ≤ 5000).
+* Tests H0: data comes from a normal distribution.
+*/
+declare function shapiroWilk(data: DataVector): TestResult;
+declare abstract class BaseRegression {
+	protected _coefficients: number[];
+	protected _intercept: number;
+	protected _fitted: boolean;
+	protected _fitIntercept: boolean;
+	protected _X: DataMatrix;
+	protected _y: DataVector;
+	protected _yHat: DataVector;
+	constructor(options?: BaseModelOptions);
+	get coefficients(): number[];
+	get intercept(): number;
+	abstract predict(X: DataInput): DataVector;
+	residuals(): number[];
+	statistics(): RegressionStatistics;
+	summary(): string;
+	protected normalizeInput(X: DataInput): DataMatrix;
+	protected addInterceptColumn(X: DataMatrix): DataMatrix;
+	protected validateFitInput(X: DataMatrix, y: DataVector): void;
+	protected assertFitted(): void;
+}
+declare class LassoRegression extends BaseRegression {
+	protected _alpha: number;
+	protected _maxIterations: number;
+	protected _tolerance: number;
+	constructor(options?: LassoOptions);
+	fit(X: DataInput, y: DataVector): this;
+	predict(X: DataInput): DataVector;
+	protected coordinateUpdate(rho: number, colNormSq: number, n: number, _j: number): number;
+	protected softThreshold(rho: number, lambda: number): number;
+	protected standardize(X: DataMatrix, y: DataVector): {
+		Xstd: DataMatrix;
+		xMeans: number[];
+		xStds: number[];
+		yMean: number;
+	};
+}
+declare class ElasticNet extends LassoRegression {
+	private _l1Ratio;
+	constructor(options?: ElasticNetOptions);
+	protected coordinateUpdate(rho: number, colNormSq: number, n: number, _j: number): number;
+}
+interface KNNOptions {
+	/** Number of neighbors (default: 5). */
+	k?: number;
+	/** Distance metric (default: "euclidean"). */
+	distance?: "euclidean" | "manhattan";
+	/** Mode: "classification" predicts class labels, "regression" predicts mean of neighbors (default: "classification"). */
+	mode?: "classification" | "regression";
+}
+/**
+* K-Nearest Neighbors for classification and regression.
+* Stores training data and computes distances at prediction time.
+*/
+declare class KNearestNeighbors {
+	private _k;
+	private _distance;
+	private _mode;
+	private _fitted;
+	private _X;
+	private _y;
+	constructor(options?: KNNOptions);
+	fit(X: DataInput, y: DataVector): this;
+	predict(X: DataInput): DataVector;
+	/** Return the k nearest neighbor indices for a single point. */
+	neighbors(point: number[]): number[];
+	private predictOne;
+	private findNeighbors;
+	private computeDistance;
+	private normalizeInput;
+}
+declare class LinearRegression extends BaseRegression {
+	constructor(options?: BaseModelOptions);
+	fit(X: DataInput, y: DataVector): this;
+	predict(X: DataInput): DataVector;
+}
+declare class LogisticRegression {
+	private _coefficients;
+	private _intercept;
+	private _fitted;
+	private _fitIntercept;
+	private _maxIterations;
+	private _tolerance;
+	private _y;
+	private _probabilities;
+	constructor(options?: LogisticOptions);
+	get coefficients(): number[];
+	get intercept(): number;
+	private sigmoid;
+	fit(X: DataInput, y: DataVector): this;
+	predict(X: DataInput): DataVector;
+	predictProbability(X: DataInput): DataVector;
+	statistics(): ClassificationStatistics;
+	private normalizeInput;
+	private addInterceptColumn;
+}
+interface MulticlassLogisticOptions {
+	/** Whether to fit an intercept term (default: true). */
+	fitIntercept?: boolean;
+	/** Maximum iterations for gradient descent (default: 200). */
+	maxIterations?: number;
+	/** Convergence tolerance (default: 1e-6). */
+	tolerance?: number;
+	/** Learning rate (default: 0.1). */
+	learningRate?: number;
+}
+interface MulticlassStatistics {
+	accuracy: number;
+	/** Per-class precision. */
+	precision: number[];
+	/** Per-class recall. */
+	recall: number[];
+	/** Number of classes. */
+	nClasses: number;
+	/** Log-likelihood. */
+	logLikelihood: number;
+}
+/**
+* Multiclass Logistic Regression (multinomial) via softmax + gradient descent.
+* Supports any number of classes (labels must be integers 0, 1, ..., K-1).
+*/
+declare class MulticlassLogisticRegression {
+	private _weights;
+	private _fitted;
+	private _fitIntercept;
+	private _maxIterations;
+	private _tolerance;
+	private _learningRate;
+	private _nClasses;
+	private _classes;
+	private _X;
+	private _y;
+	constructor(options?: MulticlassLogisticOptions);
+	get weights(): Matrix;
+	get classes(): number[];
+	/** Softmax: converts raw scores to probabilities. */
+	private softmax;
+	fit(X: DataInput, y: DataVector): this;
+	/** Predict class labels. */
+	predict(X: DataInput): DataVector;
+	/** Predict class probabilities: returns array of probability vectors. */
+	predictProbability(X: DataInput): number[][];
+	statistics(): MulticlassStatistics;
+	private normalizeInput;
+}
+type ActivationFunction = "relu" | "sigmoid" | "tanh" | "linear" | "softmax";
+interface LayerConfig {
+	/** Number of neurons in this layer. */
+	units: number;
+	/** Activation function (default: "relu"). */
+	activation?: ActivationFunction;
+}
+interface NeuralNetworkOptions {
+	/** Hidden layer configurations. Output layer is added automatically. */
+	layers: LayerConfig[];
+	/** Learning rate (default: 0.01). */
+	learningRate?: number;
+	/** Number of training epochs (default: 100). */
+	epochs?: number;
+	/** Task type (default: "regression"). */
+	task?: "regression" | "classification";
+}
+/**
+* Feedforward Neural Network (Multi-Layer Perceptron) with backpropagation.
+* Supports regression and classification tasks.
+*/
+declare class NeuralNetwork {
+	private _layers;
+	private _learningRate;
+	private _epochs;
+	private _task;
+	private _fitted;
+	private _outputSize;
+	private _classes;
+	constructor(options: NeuralNetworkOptions);
+	private _layerConfigs;
+	private initializeLayers;
+	private createLayer;
+	fit(X: DataInput, y: DataVector): this;
+	predict(X: DataInput): DataVector;
+	/** Return raw output (probabilities for classification, values for regression). */
+	predictRaw(X: DataInput): number[][];
+	private forward;
+	private backward;
+	private activate;
+	private activationDerivative;
+	private sigmoid;
+	private encodeTarget;
+	private normalizeInput;
+}
+declare class PolynomialRegression extends BaseRegression {
+	private _degree;
+	private _inner;
+	constructor(options?: PolynomialOptions);
+	private expandFeatures;
+	fit(X: DataInput, y: DataVector): this;
+	predict(X: DataInput): DataVector;
+}
+declare class RidgeRegression extends BaseRegression {
+	private _alpha;
+	constructor(options?: RegularizedOptions);
+	fit(X: DataInput, y: DataVector): this;
+	predict(X: DataInput): DataVector;
+}
+declare class RobustRegression extends BaseRegression {
+	private _method;
+	private _tuningConstant;
+	private _maxIterations;
+	private _tolerance;
+	constructor(options?: RobustOptions);
+	fit(X: DataInput, y: DataVector): this;
+	predict(X: DataInput): DataVector;
+}
+declare class WeightedRegression extends BaseRegression {
+	private _weights;
+	constructor(options?: WeightedOptions);
+	fit(X: DataInput, y: DataVector, weights?: DataVector): this;
+	predict(X: DataInput): DataVector;
+}
+/**
+* Bootstrap confidence intervals on regression coefficients.
+* Resamples with replacement, refits the model nBootstrap times.
+* Returns mean coefficients, empirical CIs (percentile method), and bootstrap SEs.
+*/
+declare function bootstrapCoefficients(X: DataMatrix, y: DataVector, nBootstrap?: number, alpha?: number, fitIntercept?: boolean): BootstrapResult;
+/**
+* Compute confidence intervals on ŷ (uncertainty on the mean prediction).
+* CI: ŷ ± t_{α/2,df} × s × √(x₀ᵀ (XᵀX)⁻¹ x₀)
+*/
+declare function confidenceInterval(X: DataMatrix, y: DataVector, yHat: DataVector, newX: DataMatrix, newYHat: DataVector, fitIntercept?: boolean, alpha?: number): PredictionInterval[];
+/**
+* Compute prediction intervals on ŷ (uncertainty on a new individual observation).
+* PI: ŷ ± t_{α/2,df} × √(s² + s² × x₀ᵀ (XᵀX)⁻¹ x₀)
+* Always wider than confidence interval.
+*/
+declare function predictionInterval(X: DataMatrix, y: DataVector, yHat: DataVector, newX: DataMatrix, newYHat: DataVector, fitIntercept?: boolean, alpha?: number): PredictionInterval[];
+/**
+* One-hot encode a categorical column.
+* @param column Array of category labels (strings or numbers)
+* @param categories Optional explicit category list. Auto-detected if omitted.
+* @param dropFirst If true, drop the first category to avoid multicollinearity trap (default: false).
+* @returns 2D array where each row is a binary vector.
+*/
+declare function oneHotEncode(column: (string | number)[], categories?: (string | number)[], dropFirst?: boolean): number[][];
+/**
+* Generate polynomial features: for each column x, add x², x³, ..., x^degree.
+* The original columns are preserved.
+*/
+declare function polynomialFeatures(X: DataMatrix, degree: number): DataMatrix;
+/**
+* Generate interaction features: x_i * x_j for all pairs (or specified pairs).
+* Original columns are NOT included in the output — only the interactions.
+*/
+declare function interactionFeatures(X: DataMatrix, pairs?: [number, number][]): DataMatrix;
+/** Remove rows containing NaN/null/undefined. */
+declare function dropMissing(X: DataMatrix, y?: DataVector): {
+	X: DataMatrix;
+	y?: DataVector;
+};
+/** Replace NaN values with column means. */
+declare function imputeMean(X: DataMatrix): DataMatrix;
+/** Replace NaN values with column medians. */
+declare function imputeMedian(X: DataMatrix): DataMatrix;
+/** Standardize (z-score): mean=0, std=1. Returns transformed data + params. */
+declare function standardize(X: DataMatrix): {
+	transformed: DataMatrix;
+} & ScalingParams;
+/** Inverse of standardize: restore original scale. */
+declare function unstandardize(X: DataMatrix, params: ScalingParams): DataMatrix;
+/** Normalize (min-max) to [0,1]. Returns transformed data + params. */
+declare function normalize(X: DataMatrix): {
+	transformed: DataMatrix;
+} & NormalizationParams;
+/** Inverse of normalize: restore original scale. */
+declare function unnormalize(X: DataMatrix, params: NormalizationParams): DataMatrix;
+export { vif, useWasmModule, useWasmEngine, useTypescriptEngine, unstandardize, unnormalize, studentizedResiduals, standardize, shapiroWilk, residualDiagnostics, predictionInterval, polynomialFeatures, oneHotEncode, normalize, leverage, isWasmActive, interactionFeatures, imputeMedian, imputeMean, getEngine, durbinWatson, dropMissing, correlationMatrix, cooksDistance2 as cooksDistance, confidenceInterval, conditionNumber, breuschPagan, bootstrapCoefficients, WeightedRegression, WeightedOptions, WasmModule, TestResult, ScalingParams, RobustRegression, RobustOptions, RidgeRegression, ResidualDiagnostics, RegularizedOptions, RegressionStatistics, PredictionInterval, PolynomialRegression, PolynomialOptions, NormalizationParams, NeuralNetworkOptions, NeuralNetwork, MulticlassStatistics, MulticlassLogisticRegression, MulticlassLogisticOptions, Matrix, LogisticRegression, LogisticOptions, LinearRegression, LayerConfig, LassoRegression, LassoOptions, KNearestNeighbors, KNNOptions, FitResult, ElasticNetOptions, ElasticNet, DataVector, DataMatrix, DataInput, ConfusionMatrix, ComputeEngine, ClassificationStatistics, BootstrapResult, BaseModelOptions, ActivationFunction };