API
Batch Lowess reference. Best suited when the dataset fits in memory and you need intervals, cross-validation, or diagnostics.
|
StreamingLowess and OnlineLowess are documented separately: StreamingLowess API, OnlineLowess API |
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:
Options options = Options.builder()
.fraction(0.3)
.outputs("diagnostics")
.build();
try (Lowess model = new Lowess(options)) {
// ...
}
-
new Lowess(Options options)creates a new batch model. ThrowsRuntimeExceptionif any option is out of range (some validation is eager at construction, e.g.iterations; some is deferred tofit, e.g.fraction). -
options: AnOptionsinstance. UseOptions.builder()(pre-populated with recommended defaults) and override only the settings you need.
fit(x, y) / fit(x, y, customWeights)
Lowess.fit(double[] x, double[] y) Result and Lowess.fit(double[] x, double[] y, double[] customWeights) Result smooth y as a function of x. x and y must be non-empty and the same length. An optional customWeights array (same length) applies per-observation case weights; pass null (or use the two-argument overload) for uniform weights. Returns a Result containing the smoothed values and optional diagnostics.
Result result = model.fit(x, y);
-
Lowess.close()releases native resources. Safe to call multiple times. ImplementsAutoCloseable, so prefer try-with-resources over relying on the garbage collector.
Options Structures
Options
| Setting | Type | Default | Description |
|---|---|---|---|
|
|
|
Smoothing fraction, in (0, 1]. |
|
|
|
Robustness iterations, in [0, 1000]. |
|
|
|
Kernel: |
|
|
|
Outlier downweighting: |
|
|
|
Interpolation distance threshold, as a fraction of the x range. |
|
|
|
Fallback when all robustness weights hit zero: |
|
|
|
Boundary handling: |
|
|
|
Residual scale estimator: |
|
|
|
Convergence tolerance for early stopping. |
|
|
|
Policy for non-finite (NaN/Infinity) values in input data: |
|
|
|
Enable parallel processing. |
|
|
|
|
|
|
empty |
Select |
|
|
|
Retain training data, enabling |
|
|
disabled |
Grouped confidence/prediction levels and optional residual-bootstrap refits. |
|
|
|
Grouped cross-validation configuration. |
|
|
unset |
Shared CV/bootstrap seed; |
Use Options.builder() (pre-populated with recommended defaults) and override only the settings you need:
Options options = Options.builder()
.fraction(0.3)
.outputs("diagnostics")
.build();
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 |
weightFunction
See: Weight Functions
-
"tricube"(default) -
"epanechnikov" -
"gaussian" -
"uniform"(alias:"boxcar") -
"biweight"(alias:"bisquare") -
"triangle"(alias:"triangular") -
"cosine"
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.0 explicitly to disable interpolation and fit every point exactly.
zeroWeightFallback
Behavior when all neighborhood weights are zero:
| Option | Behavior |
|---|---|
|
Use the mean of the neighborhood |
|
Return the original y value |
|
Return |
boundaryPolicy
See: Boundary Handling
-
"extend"(default; alias:"pad") -
"reflect"(alias:"mirror") -
"zero" -
"noboundary"(alias:"none")
scalingMethod
See: Scaling Methods
-
"mad"(default; alias:"median_absolute_deviation") -
"mar"(alias:"median_absolute_residual") -
"mean"(alias:"mean_absolute_residual")
autoConverge
See: Robustness
Convergence tolerance for early stopping of robustness iterations. NaN (default) disables early stopping.
missing
Policy for handling non-finite (NaN/Infinity) values in x/y (and customWeights):
| Option | Behavior |
|---|---|
|
Throw if any value is non-finite |
|
Silently remove observations where |
A length mismatch between x and y always throws, 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 agpu-feature build of the native library
outputs: se
See: Intervals
Select "se" to compute hat-matrix statistics (effective degrees of freedom, leverage, delta1/delta2) and standard errors.
outputs: diagnostics
Select "diagnostics" to populate Result.diagnostics() (RMSE, MAE, R², AIC/AICc, effective degrees of freedom). AIC/AICc/effective degrees of freedom additionally require "se" (or confidence/prediction intervals), since they depend on hat-matrix statistics.
outputs: weights
Select "weights" to populate Result.robustnessWeights() (from the last robustness iteration).
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) via Result.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. via a Comparator over the returned x() array) instead of calling fit() twice.
intervals
See: Intervals
Build with IntervalsOptions.builder(). Set confidence(level) and/or prediction(level) independently; for example, use 0.90 for confidence coverage and 0.99 for prediction coverage. Unset levels disable that bound. Set bootstrap(n) to at least 2 to replace analytic intervals with residual-bootstrap standard errors and percentile bounds. seed controls both CV and fit-time bootstrap when enabled, but does not enable either by itself.
CV Options
See: Cross-Validation
-
method:"kfold"(default) — fast, evaluates each candidate fraction overkfolds;"loocv"— slow, exhaustive leave-one-out cross-validation -
k: Number of folds for k-fold CV. Ignored whenmethod("loocv"). -
fractions: Candidate fractions to evaluate. Required. -
seed(onOptions.Builder, notCVOptions): Outer seed shared by k-fold shuffling and bootstrap. Unset uses each feature’s default;0is valid.
Options options = Options.builder()
.cv(CVOptions.builder().method("kfold").k(5)
.seed(42L)
.fractions(0.1, 0.2, 0.3, 0.5).build())
.build();
try (Lowess model = new Lowess(options)) {
Result result = model.fit(x, y);
System.out.println(java.util.Arrays.toString(result.cvScores().orElseThrow()));
System.out.println(result.fractionUsed()); // the CV-selected fraction
}
seed
One seed shared by k-fold CV shuffling and fit-time residual bootstrap. It does not enable either feature by itself. The value is interpreted as an unsigned 64-bit integer, and 0 is a valid seed.
retainModel
See: Predict
Retains the fitted model’s training data, populating Result.predictModel() with an Optional<PredictModel> usable to evaluate the fit at out-of-sample query points not in the training set. Close the Result (or the nested PredictModel) to free the native handle. false (default) — no extra memory/copy cost unless requested.
customWeights
See: Custom Weights
Per-observation weights, passed to fit() rather than the constructor.
double[] weights = new double[x.length];
java.util.Arrays.fill(weights, 1.0);
weights[0] = 5.0; // trust the first observation more
try (Lowess model = new Lowess(Options.builder().build())) {
Result result = model.fit(x, y, weights);
}
Result Structure
Result
| Accessor | Type | Populated when |
|---|---|---|
|
|
Always. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Always. |
|
|
Always (empty if not available). |
|
|
|
|
|
|
Diagnostics
| Accessor | Type | Description |
|---|---|---|
|
|
Root Mean Squared Error |
|
|
Mean Absolute Error |
|
|
R-squared |
|
|
Robust residual scale estimate ( |
|
|
Effective degrees of freedom |
|
|
AIC |
|
|
AICc |
Predict
See: Predict
Example
import fastlowess.Lowess;
import fastlowess.Options;
import fastlowess.Result;
public class Example {
public static void main(String[] args) {
double[] x = {1, 2, 3, 4, 5};
double[] y = {2.1, 4.0, 6.2, 8.0, 10.1};
Options options = Options.builder().fraction(0.5).build();
try (Lowess model = new Lowess(options)) {
Result result = model.fit(x, y);
System.out.println(java.util.Arrays.toString(result.y()));
}
}
}
[2.1, 4.0, 6.2, 8.0, 10.1]