Out-of-Sample Prediction

Evaluate a fitted Batch model at query points that were not in the training set.

Overview

Out-of-sample prediction is available in Batch mode only. Streaming and Online modes do not support it.

PredictModel.predict(newX, options) evaluates the fit at arbitrary query points, like R’s predict(model, newdata).

It reuses fit’s own (possibly `delta-interpolated) smoothed curve for its y output — so predicting at a training x always exactly reproduces that point’s fit output, regardless of delta. A fresh local fit is only run when "derivative", "se" (or an interval level), or maxNeighborDistance needs the actual regression slope or standard error.

Result.predictModel() returns an Optional<PredictModel>, populated only when retainModel was true.


Options

Setting Type Default Description

outputs(String…​)

String…​

empty

Select "se" and/or "derivative".

intervals(IntervalsOptions)

IntervalsOptions

disabled

Confidence/prediction levels and optional residual-bootstrap refits.

seed(long)

long

unset

Reproducible prediction-time bootstrap draws; 0 is valid.

extrapolation

String

"clamp"

Behavior for query points outside the training x-range.

maxExtrapolationDistance

double

NaN

Under "linear" extrapolation, the max allowed distance beyond the training boundary before erroring (NaN to disable).

maxNeighborDistance

double

NaN

Max allowed distance to the farthest training point in a query’s local window before erroring (NaN to disable).

outputs

Request "se" for standard errors (from the retained model’s residual scale and per-point leverage) and "derivative" for the local slope at each query point. Analytic intervals compute their required standard errors even without an explicit "se" output.

intervals

Build with IntervalsOptions.builder(). confidence(level) bounds the mean response and prediction(level) bounds a new observation at each query point (e.g. 0.95). Without bootstrap, these use normal-theory standard errors and the retained residual scale.

Set bootstrap(n) to at least 2 to resample the retained Batch residuals, refit the model, and calculate query-point percentile intervals and standard errors.

seed

Seeds prediction-time bootstrap draws, independently of the fit/CV seed on Options. It does not enable bootstrap by itself.

extrapolation

Behavior for query points outside [min(x_train), max(x_train)]:

Policy Behavior

"clamp" (default)

Clamps the query to the nearest boundary window

"linear"

Linearly extrapolates from the nearest boundary point’s local fit and slope

"error"

Fails the whole call with an exception

maxExtrapolationDistance

Under "linear" extrapolation, the maximum allowed distance beyond the training boundary before predict throws, instead of returning an unbounded value. NaN (default, uncapped).

maxNeighborDistance

Maximum allowed distance to the farthest training point in a query’s local window before predict throws. Guards against an "empty range" blind spot: a query point can fall within [min(x_train), max(x_train)] yet still be far from any real training point (e.g. training x in [0,10] and [90,100], query at x=50). NaN (default, uncapped); applies regardless of extrapolation.

Example

Basic Usage

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.7).retainModel(true).build();

try (Lowess model = new Lowess(options)) {
    Result result = model.fit(x, y);
    try (PredictModel predictModel = result.predictModel().orElseThrow()) {
        PredictResult prediction = predictModel.predict(new double[] { 1.5, 4.5 });
        System.out.println(java.util.Arrays.toString(prediction.y()));
    }
}
[3.05, 9.05]

Standard Errors and Derivative

PredictOptions options = PredictOptions.builder()
        .outputs("se", "derivative")
        .build();
PredictResult prediction = predictModel.predict(new double[] { 2.5 }, options);

Bootstrap Intervals

PredictOptions options = PredictOptions.builder()
        .intervals(IntervalsOptions.builder().confidence(0.95).prediction(0.95).bootstrap(200).build())
        .seed(7L)
        .build();
PredictResult prediction = predictModel.predict(new double[] { 2.5, 4.5 }, options);

Linear Extrapolation

PredictOptions options = PredictOptions.builder().extrapolation("linear").build();
PredictResult prediction = predictModel.predict(new double[] { 10.0 }, options);