API Reference
FastLOWESS.FastLOWESS — Module
FastLOWESSHigh-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 LOWESSfit(model, x, y): Fit and return resultsStreamingLowess(; kwargs...)/process_chunk/finalize: Streaming modeOnlineLowess(; 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)FastLOWESS._APPENDABLE_RESULT_FIELDS — Constant
Base.append!(a::LowessResult, b::LowessResult) -> LowessResultAppend 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.
FastLOWESS.Diagnostics — Type
DiagnosticsDiagnostic statistics for LOWESS fit quality.
Fields
rmse::Float64: Root Mean Squared Errormae::Float64: Mean Absolute Errorr_squared::Float64: R-squared (coefficient of determination)aic::Union{Float64, Nothing}: Akaike Information Criterion, ornothing
if not computedaicc::Union{Float64, Nothing}: Corrected AIC, ornothingif not computedeffective_df::Union{Float64, Nothing}: Effective degrees of freedom, or
`nothing` if not computedresidual_sd::Float64: Batch uses robust residual scale estimate (1.4826 * MAD); Streaming uses cumulative sample SD of emitted residuals
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 functionrobustness_method::String = "bisquare": Robustness methodscaling_method::String = "mad": Scaling method for robustnessboundary_policy::String = "extend": Handling of edge effectsintervals = 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 disablecv = nothing: Grouped cross-validation options, e.g.(method="kfold", k=5, fractions=[0.2, 0.3, 0.5]).methodis"kfold"(fast) or"loocv"(slow and exhaustive);kis ignored for LOOCV.seed::Union{Integer,Nothing} = nothing: Shared seed for k-fold CV and residual bootstrap. Does not enable either by itself;0is a valid seed.parallel::Bool = true: Enable parallel executionoutputsmay include"se"and/or"sorted". Results are sorted ascending byxinstead 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 callingfittwice.backend::String = "cpu": Execution backend ("cpu"or"gpu"). GPU requires the library to be built with thegpuCargo 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, enablingLowessResult.predict_modelfor out-of-sample prediction.
Notes
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 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 |
zero_weight_fallback controls the behavior when all neighborhood weights are zero:
| Option | Behavior |
|---|---|
"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:
| Option | Behavior |
|---|---|
"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)FastLOWESS.LowessResult — Type
LowessResultResult from LOWESS smoothing.
Fields
x::Vector{Float64}: x values (same order as input)y::Vector{Float64}: Smoothed y valuesstandard_errors::Union{Vector{Float64}, Nothing}: Standard errors (if computed)confidence_lower::Union{Vector{Float64}, Nothing}: Lower confidence boundsconfidence_upper::Union{Vector{Float64}, Nothing}: Upper confidence boundsprediction_lower::Union{Vector{Float64}, Nothing}: Lower prediction boundsprediction_upper::Union{Vector{Float64}, Nothing}: Upper prediction boundsresiduals::Union{Vector{Float64}, Nothing}: Residualsrobustness_weights::Union{Vector{Float64}, Nothing}: Robustness weightsderivative::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 fractionsfraction_used::Float64: Fraction used for smoothingiterations_used::Union{Int, Nothing}: Number of iterations performed (nothingif not applicable)diagnostics::Union{Diagnostics, Nothing}: Diagnostic metricspredict_model::Union{PredictModel, Nothing}: Retained fitted-model state, non-nothingonly ifretain_model=truewas passed toLowess. Enables out-of-samplepredict().
FastLOWESS.OnlineLowess — Type
OnlineLowess(; kwargs...)Stateful online LOWESS smoother.
Keyword Arguments
fraction::Float64 = 0.67: Smoothing fraction. SeeLowessfor guidance on choosing a value.window_capacity::Int = 1000: Maximum points to retain in window, at least 3min_points::Int = 2: Minimum points before smoothing starts, between 2 andwindow_capacityiterations::Int = 0: Number of robustness iterations. Requiresupdate_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 functionrobustness_method::String = "bisquare": Robustness methodscaling_method::String = "mad": Scaling methodboundary_policy::String = "extend": Boundary handlingupdate_mode::String = "incremental": Update strategy ("full" or "incremental")auto_converge::Float64 = NaN: Auto-convergence toleranceoutputs::Vector{String} = String[]: Optional outputs including"weights","derivative", and"se".zero_weight_fallback::String = "use_local_mean": Zero weight handling. SeeLowessfor a description of each option.missing::String = "error": Policy for non-finite (NaN/Inf)x/yvalues passed toadd_point."error"(default) raises,"drop"ignores the point and returns:droppedinstead 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. Requiresupdate_mode = "full".seed::Union{Integer,Nothing} = nothing: Bootstrap seed; each full-update window restarts from it. Does not enable bootstrap by itself;0is 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.
FastLOWESS.OnlineOutput — Type
OnlineOutputResult from a single add_point call.
Fields
y::Float64: Smoothed value for the latest pointstandard_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 iterationsderivative::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)
FastLOWESS.PredictModel — Type
PredictModelRetained fitted-model state enabling out-of-sample predict(), obtained via LowessResult.predict_model when retain_model=true was passed to Lowess.
FastLOWESS.PredictResult — Type
PredictResultResult from predict(model, new_x).
Fields
y::Vector{Float64}: Predicted y values, one per query pointstandard_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)
FastLOWESS.StreamingLowess — Type
StreamingLowess(; kwargs...)Stateful streaming LOWESS smoother.
Keyword Arguments
fraction::Float64 = 0.67: Smoothing fraction. SeeLowessfor guidance on choosing a value.chunk_size::Int = 5000: Size of each processing chunk, at least 10overlap::Int = -1: Overlap between adjacent chunks, less thanchunk_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. SeeLowessfor guidance on choosing a value.delta::Float64 = NaN: Interpolation threshold (NaN auto-sets it to 0.0)weight_function::String = "tricube": Kernel functionrobustness_method::String = "bisquare": Robustness methodscaling_method::String = "mad": Scaling methodboundary_policy::String = "extend": Boundary handlingauto_converge::Float64 = NaN: Auto-convergence toleranceoutputs::Vector{String} = String[]: Optional result components such as
`"diagnostics"`, `"residuals"`, `"weights"`, `"derivative"`, and `"se"`.zero_weight_fallback::String = "use_local_mean": Zero weight handling. SeeLowessfor 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 executionmissing::String = "error": Policy for non-finite (NaN/Inf) values in each chunk. SeeLowessfor 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 likey.seed::Union{Integer,Nothing} = nothing: Bootstrap seed; each combined chunk restarts from it. Does not enable bootstrap by itself;0is valid.
Base.finalize — Method
finalize(s::StreamingLowess) -> LowessResultFinalize streaming and return remaining buffered data.
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
OnlineOutputonce the window has at leastmin_pointsfinite observations nothingwhile the window is still filling:droppedwhenmissing = "drop"andxoryis non-finite
FastLOWESS.fit — Method
fit(l::Lowess, x, y; custom_weights=nothing) -> LowessResultFit the LOWESS model to data.
Arguments
custom_weights::Union{Vector{Float64}, Nothing} = nothing: Per-observation case weights. Must have the same length asxandy. All values must be finite and non-negative. Passnothing(default) to disable.
FastLOWESS.gpu_available — Method
gpu_available()::BoolReturn true if the currently loaded FastLOWESS native library was built with the GPU backend enabled.
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.
FastLOWESS.predict — Method
predict(model::PredictModel, new_x::Vector{Float64}; kwargs...) -> PredictResultEvaluate 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} = nothingmax_neighbor_distance::Union{Float64, Nothing} = nothing
FastLOWESS.process_chunk — Method
process_chunk(s::StreamingLowess, x, y) -> LowessResultProcess a chunk of data.
FastLOWESS.version — Method
version() -> StringReturn the installed FastLOWESS Julia package version from Project.toml. This is the Julia binding version, not the native Rust library version.