API

The Node.js bindings provide a high-performance interface to the core Rust library, mirroring the Rust API structure.

StreamingLowess and OnlineLowess are documented separately: Streaming Adapter, Online Adapter

When to Use Batch Adapter

• Dataset fits in memory
• Need intervals, cross-validation, or diagnostics
• Processing complete files

Classes

Lowess

The Lowess class allows configuring the LOWESS parameters once and fitting multiple datasets using those parameters.

Constructor:

const { Lowess } = require('fastlowess');

const model = new Lowess({ fraction: 0.5, iterations: 3 });
const result = model.fit(
    new Float64Array([0, 1, 2, 3, 4, 5]),
    new Float64Array([0.0, 1.1, 1.9, 3.1, 3.9, 5.0])
);
console.log("y[0]:", result.y[0].toFixed(4));

y[0]: 0.0000

• options: An object containing LowessOptions fields.

fit(x, y, customWeights?)

Fits the model to the provided x and y typed arrays. customWeights is an optional Float64Array of per-observation weights — all values must be ≥ 0 and length must match x. Returns a LowessResult object containing the smoothed values and optional diagnostics.

const { Lowess } = require('fastlowess');

const n = 100;
const x = Float64Array.from({ length: n }, (_, i) => i * 2 * Math.PI / (n - 1));
const y = Float64Array.from(x, xi => Math.sin(xi) + 0.1);

const model = new Lowess({ fraction: 0.5 });
const result = model.fit(x, y);
console.log("Fraction used:", result.fraction_used);

Fraction used: 0.5

Options Structures

LowessOptions

Field	Type	Default	Description
fraction	number	0.67	Smoothing fraction (bandwidth)
iterations	number	3	Number of robustifying iterations
weight_function	string	"tricube"	Weight function name
robustness_method	string	"bisquare"	Robustness method name
delta	number	NaN	Interpolation distance (NaN auto-sets it to 1% of the x-range)
zero_weight_fallback	string	"use_local_mean"	Zero-weight handling
boundary_policy	string	"extend"	Boundary handling policy
scaling_method	string	"mad"	Residual scaling method
auto_converge	number	null	Auto-convergence tolerance
missing	string	"error"	Policy for non-finite (NaN/Inf) values in input data
parallel	boolean	true	Enable parallel execution
backend	string	"cpu"	Execution backend ("cpu" or "gpu"); GPU requires the package to be built with the gpu Cargo feature
outputs	string[]	[]	Select se, diagnostics, residuals, weights, derivative, and/or sorted
intervals	object	null	Grouped interval options: confidence, prediction, and bootstrap
cv	object	null	Grouped CV options: method, k, and fractions
seed	number	null	Shared CV/bootstrap seed; must be an integer from 0 through Number.MAX_SAFE_INTEGER
retain_model	boolean	false	Retain training data, enabling result.predict()
custom_weights	Float64Array	null	Per-observation case weights — passed to fit(), not the options object

Options

fraction

fraction is the most important parameter: it controls the size of the local neighbourhood used at each point.

Range	Effect	Use case
0.1-0.3	Fine detail	Rapidly changing signals
0.3-0.5	Balanced	General purpose
0.5-0.7	Heavy smoothing	Noisy data
0.7-1.0	Very smooth	Trend extraction

iterations

iterations controls robustness to outliers, at the cost of speed.

Value	Effect	Performance
0	No robustness	Fastest
1-3	Moderate	Recommended
4-6	Strong	Contaminated data
7+	Very strong	Heavy outliers

weight_function

See: Weight Functions

• "tricube" (default)
• "epanechnikov"
• "gaussian"
• "uniform" (alias: "boxcar")
• "biweight" (alias: "bisquare")
• "triangle" (alias: "triangular")
• "cosine"

robustness_method

See: Robustness

• "bisquare" (default; alias: "biweight")
• "huber"
• "talwar"

delta

Points within delta of each other on the x-axis share the same local fit instead of each computing its own regression — an interpolation shortcut that trades a small amount of accuracy for a large speedup on dense, evenly-spaced data. NaN (default) auto-sets it to 1% of the x-range. Set it to 0 explicitly to disable interpolation and fit every point exactly.

zero_weight_fallback

Behavior when all neighborhood weights are zero:

Option	Behavior
"use_local_mean" (default; aliases: "local_mean", "mean")	Use the mean of the neighborhood
"return_original" (alias: "original")	Return the original y value
"return_none" (alias: "none")	Return NaN

boundary_policy

See: Boundary Handling

• "extend" (default; alias: "pad")
• "reflect" (alias: "mirror")
• "zero"
• "noboundary" (alias: "none")

scaling_method

See: Scaling Methods

• "mad" (default; alias: "median_absolute_deviation")
• "mar" (alias: "median_absolute_residual")
• "mean" (alias: "mean_absolute_residual")

auto_converge

See: Robustness

Convergence tolerance for early stopping of robustness iterations. null (default) disables early stopping.

missing

Policy for handling non-finite (NaN/Inf) values in x/y (and custom_weights):

Option	Behavior
"error" (default)	Throw an error if any value is non-finite
"drop"	Silently remove observations where x or y is non-finite before fitting

Note: A length mismatch between x and y always errors, even under "drop".

parallel

Enable multi-threaded execution via Rayon.

• true (default) — parallelizes the local regression fits across CPU cores
• false — forces single-threaded execution (useful for benchmarking or deterministic profiling)

backend

See: GPU Backend

The batch Lowess class can optionally run on a GPU-accelerated backend powered by wgpu, for high-throughput processing of large datasets (10k+ points).

• "cpu" (default)
• "gpu" — requires the package to be built with the gpu Cargo feature

outputs: se

See: Intervals

Computes hat-matrix statistics (effective degrees of freedom, leverage, delta1/delta2) in addition to standard errors.

outputs: diagnostics

See: Diagnostics

Select "diagnostics" to include a Diagnostics object (RMSE, MAE, R², AIC/AICc, effective degrees of freedom) in the result. AIC/AICc/effective_df additionally require "se" (or confidence/prediction intervals) to be selected, since they depend on hat-matrix statistics.

outputs: residuals

Include per-point residuals (y - fitted) in the result.

outputs: weights

Include the final per-point robustness weights (from the last robustness iteration) in the result.

outputs: derivative

Each point’s local WLS fit already computes a slope internally; this exposes that per-point slope (rate of change of the smoothed curve) in LowessResult.derivative, enabling turning-point/rate-of-change analysis at effectively no extra computation cost.

outputs: sorted

When set to true, it reorders every result field (residuals, intervals, etc.) by x in an ascending manner, instead of in original input order. To get both orderings, sort the default result client-side (e.g. by the returned x array’s sort order) instead of calling fit() twice.

intervals

See: Intervals

An object such as { confidence: 0.90, prediction: 0.99, bootstrap: 200 }. Confidence and prediction coverage levels are independent: confidence bounds the mean response and prediction bounds a new observation; omitted levels disable that bound. bootstrap (at least 2) replaces analytic intervals with residual-bootstrap standard errors and percentile bounds. seed controls fit-time bootstrap draws but does not enable bootstrap by itself.

CV Options

See: Cross-Validation

An object such as { method: "kfold", k: 5, fractions: [0.2, 0.3, 0.5] }:

• method: "kfold" (default) — fast, evaluates each candidate fraction over k folds; "loocv" — slow, exhaustive leave-one-out cross-validation
• k: Number of folds for k-fold CV. Ignored when method: "loocv".
• fractions: Candidate fractions to evaluate. Required.

Seed k-fold shuffling with the outer seed option, not inside cv.

seed

One seed shared by k-fold CV shuffling and fit-time residual bootstrap. It does not enable either feature by itself; null (default) uses each feature’s default. Seeds must be finite, non-negative safe integers no greater than Number.MAX_SAFE_INTEGER; fractional, negative, and unsafe values throw. 0 is valid.

retain_model

See: Predict

Retains the fitted model’s training data, enabling result.predict(newX, options) at out-of-sample query points. false (default) — no extra memory/copy cost unless requested.

custom_weights

See: Custom Weights

Per-observation weights, passed to fit() rather than the options object.

Result Structure

LowessResult

Field	Type	Description
x	Float64Array	x values (same order as input)
y	Float64Array	Smoothed y values
fraction_used	number	Fraction used (set or selected by CV)
iterations_used	number | null	Robustness iterations actually performed
standard_errors	Float64Array | null	Per-point standard errors
confidence_lower	Float64Array | null	Lower confidence bounds
confidence_upper	Float64Array | null	Upper confidence bounds
prediction_lower	Float64Array | null	Lower prediction bounds
prediction_upper	Float64Array | null	Upper prediction bounds
residuals	Float64Array | null	Residuals (if "residuals" was requested)
robustness_weights	Float64Array | null	Robustness weights (if "weights" was requested)
cv_scores	Float64Array | null	CV score per tested fraction
diagnostics	Diagnostics | null	Fit metrics (if "diagnostics" was requested)
derivative	Float64Array | null	Per-point local fit derivative/slope (if "derivative" was requested)

Diagnostics

Field	Type	Description
rmse	number	Root Mean Squared Error
mae	number	Mean Absolute Error
r_squared	number	R-squared
residual_sd	number	Robust residual scale estimate (1.4826 * MAD)
effective_df	number | null	Effective degrees of freedom
aic	number | null	AIC
aicc	number | null	AICc

Example

const { Lowess } = require('fastlowess');

const x = new Float64Array([1, 2, 3, 4, 5]);
const y = new Float64Array([2.1, 4.0, 6.2, 8.0, 10.1]);

// Configure model
const model = new Lowess({ fraction: 0.5 });

// Fit data
const result = model.fit(x, y);

console.log("Smoothed Y:", result.y);

Smoothed Y: Float64Array(5) [ 2.1, 4, 6.2, 8, 10.1 ]