API Reference

FastLOWESS.FastLOWESS — Module
FastLOWESS

High-performance LOWESS (Locally Weighted Scatterplot Smoothing) for Julia.

Provides bindings to the fastlowess Rust library for fast, robust LOWESS smoothing.

Main API

  • Lowess(; kwargs...): Configure batch LOWESS
  • fit(model, x, y): Fit and return results
  • StreamingLowess(; kwargs...) / process_chunk / finalize: Streaming mode
  • OnlineLowess(; kwargs...) / add_point: Online sliding-window mode

Example

using FastLOWESS

x = collect(1.0:0.1:10.0)
y = sin.(x) .+ 0.1 .* randn(length(x))

result = fit(Lowess(fraction=0.3), x, y)
println("Smoothed values: ", result.y)
source
FastLOWESS._APPENDABLE_RESULT_FIELDS — Constant
Base.append!(a::LowessResult, b::LowessResult) -> LowessResult

Append the per-point results from b to a in place. Per-point optional fields must be present in both results or neither.

Results that carry fit-global state (cv_scores, diagnostics, or predict_model) cannot be appended — those fields are not defined for concatenated streaming chunks.

source
FastLOWESS.Diagnostics — Type
Diagnostics

Diagnostic statistics for LOWESS fit quality.

Fields

  • rmse::Float64: Root Mean Squared Error
  • mae::Float64: Mean Absolute Error
  • r_squared::Float64: R-squared (coefficient of determination)
  • aic::Union{Float64, Nothing}: Akaike Information Criterion, or nothing
if not computed
  • aicc::Union{Float64, Nothing}: Corrected AIC, or nothing if not computed
  • effective_df::Union{Float64, Nothing}: Effective degrees of freedom, or
`nothing` if not computed
  • residual_sd::Float64: Batch uses robust residual scale estimate (1.4826 * MAD); Streaming uses cumulative sample SD of emitted residuals
source
FastLOWESS.Lowess — Type
Lowess(; kwargs...)

Stateful batch LOWESS smoother.

Keyword Arguments

  • fraction::Float64 = 0.67: Smoothing fraction (proportion of data used for each fit). See Notes for guidance on choosing a value.
  • iterations::Int = 3: Number of robustness iterations, between 0 and 1000. See Notes for guidance on choosing a value.
  • delta::Float64 = NaN: Interpolation optimization threshold (NaN auto-sets it to 1% of the x-range)
  • weight_function::String = "tricube": Kernel function
  • robustness_method::String = "bisquare": Robustness method
  • scaling_method::String = "mad": Scaling method for robustness
  • boundary_policy::String = "extend": Handling of edge effects
  • intervals = nothing: Grouped interval options, e.g. (confidence=0.95, prediction=0.95, bootstrap=200). Omitted levels disable that bound; bootstrap (at least 2) replaces analytic intervals with residual-bootstrap refits.
  • outputs::Vector{String} = String[]: Optional result components such as
`"diagnostics"`, `"residuals"`, `"weights"`, `"derivative"`, `"se"`, and
`"sorted"`.
  • zero_weight_fallback::String = "use_local_mean": Fallback when all weights are zero. See Notes for a description of each option.
  • auto_converge::Float64 = NaN: Tolerance for auto-convergence, NaN to disable
  • cv = nothing: Grouped cross-validation options, e.g. (method="kfold", k=5, fractions=[0.2, 0.3, 0.5]). method is "kfold" (fast) or "loocv" (slow and exhaustive); k is ignored for LOOCV.
  • seed::Union{Integer,Nothing} = nothing: Shared seed for k-fold CV and residual bootstrap. Does not enable either by itself; 0 is a valid seed.
  • parallel::Bool = true: Enable parallel execution
  • outputs may include "se" and/or "sorted". Results are sorted ascending by x instead of in the original input order. To get both orderings without re-fitting, sort the default (unsorted) result client-side (e.g. sortperm(result.x)) rather than calling fit twice.
  • backend::String = "cpu": Execution backend ("cpu" or "gpu"). GPU requires the library to be built with the gpu Cargo feature and a Vulkan/Metal/DX12- capable GPU driver.
  • missing::String = "error": Policy for non-finite (NaN/Inf) values in input data. See Notes for a description of each option.
  • retain_model::Bool = false: Retain the fitted model's training data, enabling LowessResult.predict_model for out-of-sample prediction.

Notes

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

RangeEffectUse case
0.1-0.3Fine detailRapidly changing signals
0.3-0.5BalancedGeneral purpose
0.5-0.7Heavy smoothingNoisy data
0.7-1.0Very smoothTrend extraction

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

ValueEffectPerformance
0No robustnessFastest
1-3ModerateRecommended
4-6StrongContaminated data
7+Very strongHeavy outliers

zero_weight_fallback controls the behavior when all neighborhood weights are zero:

OptionBehavior
"use_local_mean" (default)Use the mean of the neighborhood
"return_original"Return the original y value
"return_none"Return NaN

missing controls the behavior when x/y (or custom_weights) contain non-finite (NaN/Inf) values:

OptionBehavior
"error" (default)Raise an error 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 errors, even under "drop".

Example

l = Lowess(fraction=0.3)
result = fit(l, x, y)
source
FastLOWESS.LowessResult — Type
LowessResult

Result from LOWESS smoothing.

Fields

  • x::Vector{Float64}: x values (same order as input)
  • y::Vector{Float64}: Smoothed y values
  • standard_errors::Union{Vector{Float64}, Nothing}: Standard errors (if computed)
  • confidence_lower::Union{Vector{Float64}, Nothing}: Lower confidence bounds
  • confidence_upper::Union{Vector{Float64}, Nothing}: Upper confidence bounds
  • prediction_lower::Union{Vector{Float64}, Nothing}: Lower prediction bounds
  • prediction_upper::Union{Vector{Float64}, Nothing}: Upper prediction bounds
  • residuals::Union{Vector{Float64}, Nothing}: Residuals
  • robustness_weights::Union{Vector{Float64}, Nothing}: Robustness weights
  • derivative::Union{Vector{Float64}, Nothing}: Per-point local fit derivative
(slope); only populated when `outputs=["derivative"]` was passed to `Lowess`/`StreamingLowess`
  • cv_scores::Union{Vector{Float64}, Nothing}: Cross-validation scores for tested fractions
  • fraction_used::Float64: Fraction used for smoothing
  • iterations_used::Union{Int, Nothing}: Number of iterations performed (nothing if not applicable)
  • diagnostics::Union{Diagnostics, Nothing}: Diagnostic metrics
  • predict_model::Union{PredictModel, Nothing}: Retained fitted-model state, non-nothing only if retain_model=true was passed to Lowess. Enables out-of-sample predict().
source
FastLOWESS.OnlineLowess — Type
OnlineLowess(; kwargs...)

Stateful online LOWESS smoother.

Keyword Arguments

  • fraction::Float64 = 0.67: Smoothing fraction. See Lowess for guidance on choosing a value.
  • window_capacity::Int = 1000: Maximum points to retain in window, at least 3
  • min_points::Int = 2: Minimum points before smoothing starts, between 2 and window_capacity
  • iterations::Int = 0: Number of robustness iterations. Requires update_mode = "full"; the default "incremental" mode performs a non-robust single-point fit.
  • delta::Float64 = NaN: Interpolation threshold (NaN auto-sets it to 0.0)
  • weight_function::String = "tricube": Kernel function
  • robustness_method::String = "bisquare": Robustness method
  • scaling_method::String = "mad": Scaling method
  • boundary_policy::String = "extend": Boundary handling
  • update_mode::String = "incremental": Update strategy ("full" or "incremental")
  • auto_converge::Float64 = NaN: Auto-convergence tolerance
  • outputs::Vector{String} = String[]: Optional outputs including "weights", "derivative", and "se".
  • zero_weight_fallback::String = "use_local_mean": Zero weight handling. See Lowess for a description of each option.
  • missing::String = "error": Policy for non-finite (NaN/Inf) x/y values passed to add_point. "error" (default) raises, "drop" ignores the point and returns :dropped instead of adding it to the window.
  • intervals = nothing: Grouped interval options, e.g. (confidence=0.95, prediction=0.95, bootstrap=200), for the latest point of each window. Requires update_mode = "full".
  • seed::Union{Integer,Nothing} = nothing: Bootstrap seed; each full-update window restarts from it. Does not enable bootstrap by itself; 0 is valid.

Cross-validation, the "sorted", "diagnostics", and "residuals" outputs, and parallel are Batch-only (or Batch/Streaming-only) and have no equivalent here. Online always runs sequentially.

source
FastLOWESS.OnlineOutput — Type
OnlineOutput

Result from a single add_point call.

Fields

  • y::Float64: Smoothed value for the latest point
  • standard_error::Union{Float64, Nothing}: Standard error (if computed)
  • residual::Union{Float64, Nothing}: Residual (raw input y minus this output's y) (if computed)
  • robustness_weight::Union{Float64, Nothing}: Robustness weight (if computed)
  • iterations_used::Union{Int, Nothing}: Number of robustness iterations
  • derivative::Union{Float64, Nothing}: Latest point's local fit derivative
(slope); only populated when `outputs=["derivative"]` was passed to `OnlineLowess`
  • confidence_lower::Union{Float64, Nothing}: Lower confidence interval bound (if requested)
  • confidence_upper::Union{Float64, Nothing}: Upper confidence interval bound (if requested)
  • prediction_lower::Union{Float64, Nothing}: Lower prediction interval bound (if requested)
  • prediction_upper::Union{Float64, Nothing}: Upper prediction interval bound (if requested)
source
FastLOWESS.PredictModel — Type
PredictModel

Retained fitted-model state enabling out-of-sample predict(), obtained via LowessResult.predict_model when retain_model=true was passed to Lowess.

source
FastLOWESS.PredictResult — Type
PredictResult

Result from predict(model, new_x).

Fields

  • y::Vector{Float64}: Predicted y values, one per query point
  • standard_errors::Union{Vector{Float64}, Nothing}: Standard errors (if requested)
  • confidence_lower::Union{Vector{Float64}, Nothing}: Lower confidence bounds (if requested)
  • confidence_upper::Union{Vector{Float64}, Nothing}: Upper confidence bounds (if requested)
  • prediction_lower::Union{Vector{Float64}, Nothing}: Lower prediction bounds (if requested)
  • prediction_upper::Union{Vector{Float64}, Nothing}: Upper prediction bounds (if requested)
  • derivative::Union{Vector{Float64}, Nothing}: Local fit's derivative (slope) at each query point (if requested)
source
FastLOWESS.StreamingLowess — Type
StreamingLowess(; kwargs...)

Stateful streaming LOWESS smoother.

Keyword Arguments

  • fraction::Float64 = 0.67: Smoothing fraction. See Lowess for guidance on choosing a value.
  • chunk_size::Int = 5000: Size of each processing chunk, at least 10
  • overlap::Int = -1: Overlap between adjacent chunks, less than chunk_size. Negative (the default) means "use the library default" (chunk_size / 10, clamped to [1, chunk_size - 10]).
  • iterations::Int = 3: Number of robustness iterations. See Lowess for guidance on choosing a value.
  • delta::Float64 = NaN: Interpolation threshold (NaN auto-sets it to 0.0)
  • weight_function::String = "tricube": Kernel function
  • robustness_method::String = "bisquare": Robustness method
  • scaling_method::String = "mad": Scaling method
  • boundary_policy::String = "extend": Boundary handling
  • auto_converge::Float64 = NaN: Auto-convergence tolerance
  • outputs::Vector{String} = String[]: Optional result components such as
`"diagnostics"`, `"residuals"`, `"weights"`, `"derivative"`, and `"se"`.
  • zero_weight_fallback::String = "use_local_mean": Zero weight handling. See Lowess for a description of each option.
  • merge_strategy::String = "weighted_average": Strategy for merging overlapping chunk regions: "average", "weightedaverage", "takefirst", "take_last"
  • parallel::Bool = true: Enable parallel execution
  • missing::String = "error": Policy for non-finite (NaN/Inf) values in each chunk. See Lowess for a description of each option.
  • intervals = nothing: Grouped interval options, e.g. (confidence=0.95, prediction=0.95, bootstrap=200), computed per combined chunk and blended across overlaps like y.
  • seed::Union{Integer,Nothing} = nothing: Bootstrap seed; each combined chunk restarts from it. Does not enable bootstrap by itself; 0 is valid.
source
Base.finalize — Method
finalize(s::StreamingLowess) -> LowessResult

Finalize streaming and return remaining buffered data.

source
FastLOWESS.add_point — Method
add_point(o::OnlineLowess, x, y) -> Union{OnlineOutput, Nothing, Symbol}

Add a single point to the online processor and return its smoothed value.

Returns:

  • an OnlineOutput once the window has at least min_points finite observations
  • nothing while the window is still filling
  • :dropped when missing = "drop" and x or y is non-finite
source
FastLOWESS.fit — Method
fit(l::Lowess, x, y; custom_weights=nothing) -> LowessResult

Fit the LOWESS model to data.

Arguments

  • custom_weights::Union{Vector{Float64}, Nothing} = nothing: Per-observation case weights. Must have the same length as x and y. All values must be finite and non-negative. Pass nothing (default) to disable.
source
FastLOWESS.gpu_available — Method
gpu_available()::Bool

Return true if the currently loaded FastLOWESS native library was built with the GPU backend enabled.

source
FastLOWESS.install_gpu — Method
install_gpu(; yes::Bool = false, local_path::Union{String,Nothing} = nothing)

Download and install the GPU-enabled FastLOWESS native library for this platform. The GPU backend is not included in the default JLL binary; this fetches a prebuilt library from the matching GitHub Release (github.com/thisisamirv/lowess-project).

Restart your Julia session afterwards to use it — ccall's dynamic library resolution caches a resolved function pointer per call site the first time it runs, so already-compiled calls in the current session keep using the old library even after libfastlowess is updated.

Set yes=true to skip the interactive y/N confirmation prompt (required when stdin is not an interactive terminal).

Pass local_path to install a GPU-enabled library already built locally (e.g. via cargo build --release --features gpu) instead of downloading one — useful for testing the installer itself, or installing an unreleased build. Skips the GitHub Release lookup/download and the on-disk cache.

Once downloaded, the library is cached under ~/.fastlowess/gpu/ and reused on subsequent calls without re-downloading or re-prompting. Set ENV["FASTLOWESS_LIB"] to the printed path in your Julia startup config to use it automatically in future sessions.

source
FastLOWESS.predict — Method
predict(model::PredictModel, new_x::Vector{Float64}; kwargs...) -> PredictResult

Evaluate the fitted model at out-of-sample query points not in the training set.

Keyword Arguments

  • outputs::Vector{String} = String[]: optional output components, including
`"se"` and/or `"derivative"`.
  • intervals = nothing: grouped interval options, e.g.
`(confidence=0.95, prediction=0.95, bootstrap=200)`. `bootstrap` (at least 2)
resamples the retained training residuals instead of using analytic intervals.
  • seed::Union{Integer, Nothing} = nothing: prediction-time bootstrap seed,
independent of the fit seed. Does not enable bootstrap by itself; `0` is valid.
  • extrapolation::String = "clamp": one of "clamp", "linear", "error".
  • max_extrapolation_distance::Union{Float64, Nothing} = nothing
  • max_neighbor_distance::Union{Float64, Nothing} = nothing
source
FastLOWESS.version — Method
version() -> String

Return the installed FastLOWESS Julia package version from Project.toml. This is the Julia binding version, not the native Rust library version.

source