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. Throws RuntimeException if any option is out of range (some validation is eager at construction, e.g. iterations; some is deferred to fit, e.g. fraction).

  • options: An Options instance. Use Options.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. Implements AutoCloseable, so prefer try-with-resources over relying on the garbage collector.

Options Structures

Options

Setting Type Default Description

fraction

double

0.67

Smoothing fraction, in (0, 1].

iterations

int

3

Robustness iterations, in [0, 1000].

weightFunction

String

"tricube"

Kernel: tricube, gaussian, uniform, cosine, epanechnikov, biweight, triangle.

robustnessMethod

String

"bisquare"

Outlier downweighting: bisquare, huber, talwar.

delta

double

NaN (auto)

Interpolation distance threshold, as a fraction of the x range.

zeroWeightFallback

String

"use_local_mean"

Fallback when all robustness weights hit zero: use_local_mean, return_original, return_none.

boundaryPolicy

String

"extend"

Boundary handling: extend, reflect, zero, noboundary.

scalingMethod

String

"mad"

Residual scale estimator: mad, mar, mean.

autoConverge

double

NaN (disabled)

Convergence tolerance for early stopping.

missing

String

"error"

Policy for non-finite (NaN/Infinity) values in input data: error, drop.

parallel

boolean

true

Enable parallel processing.

backend

String

"cpu"

cpu or gpu (requires a gpu-feature build of the native library).

outputs(String…​)

String…​

empty

Select se, diagnostics, residuals, weights, derivative, and/or sorted.

retainModel

boolean

false

Retain training data, enabling Result.predictModel().

intervals(IntervalsOptions)

IntervalsOptions

disabled

Grouped confidence/prediction levels and optional residual-bootstrap refits.

cv(CVOptions)

CVOptions

null (disabled)

Grouped cross-validation configuration.

seed(long)

long

unset

Shared CV/bootstrap seed; 0 is a valid deterministic 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

  • "tricube" (default)

  • "epanechnikov"

  • "gaussian"

  • "uniform" (alias: "boxcar")

  • "biweight" (alias: "bisquare")

  • "triangle" (alias: "triangular")

  • "cosine"

robustnessMethod

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.0 explicitly to disable interpolation and fit every point exactly.

zeroWeightFallback

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

boundaryPolicy

  • "extend" (default; alias: "pad")

  • "reflect" (alias: "mirror")

  • "zero"

  • "noboundary" (alias: "none")

scalingMethod

  • "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

"error" (default)

Throw if any value is non-finite

"drop"

Silently remove observations where x or y is non-finite before fitting

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

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 a gpu-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: residuals

Select "residuals" to populate Result.residuals() (y - fitted).

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

  • 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 (on Options.Builder, not CVOptions): Outer seed shared by k-fold shuffling and bootstrap. Unset uses each feature’s default; 0 is 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

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

x(), y()

double[]

Always.

standardErrors()

Optional<double[]>

"se" output or any interval

confidenceLower(), confidenceUpper()

Optional<double[]>

intervals confidence set

predictionLower(), predictionUpper()

Optional<double[]>

intervals prediction set

residuals()

Optional<double[]>

"residuals" output

robustnessWeights()

Optional<double[]>

"weights" output

cvScores()

Optional<double[]>

cv set

fractionUsed()

double

Always.

iterationsUsed()

OptionalInt

Always (empty if not available).

diagnostics()

Optional<Diagnostics>

"diagnostics" output

derivative()

Optional<double[]>

"derivative" output

Diagnostics

Accessor Type Description

rmse()

double

Root Mean Squared Error

mae()

double

Mean Absolute Error

rSquared()

double

R-squared

residualSd()

double

Robust residual scale estimate (1.4826 * MAD)

effectiveDf()

Optional<Double>

Effective degrees of freedom

aic()

Optional<Double>

AIC

aicc()

Optional<Double>

AICc

Predict

See: Predict

PredictModel.predict(double[] newX, PredictOptions options) PredictResult

Obtained via Result.predictModel(), only populated when retainModel was true. Evaluates the fitted model at out-of-sample query points.

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]