LOESS Streaming Smoothing — StreamingLoess • rfastloess

Create a stateful LOESS model for streaming data. Processes data in fixed-size chunks with configurable overlap: results for each chunk are returned by process_chunk, and finalize flushes any remaining buffered points after the last chunk.

Usage

StreamingLoess(
    fraction = 0.67,
    chunk_size = 5000L,
    ...,
    overlap = NULL,
    iterations = 3L,
    weight_function = "tricube",
    robustness_method = "bisquare",
    scaling_method = "mad",
    boundary_policy = "extend",
    zero_weight_fallback = "use_local_mean",
    auto_converge = NULL,
    intervals = NULL,
    merge_strategy = "weighted_average",
    parallel = TRUE,
    degree = "linear",
    dimensions = 1L,
    distance_metric = "normalized",
    surface_mode = "interpolation",
    weighted_metric_weights = NULL,
    cell = NULL,
    interpolation_vertices = NULL,
    boundary_degree_fallback = NULL,
    missing = "error",
    outputs = NULL
)

Arguments

fraction: Smoothing fraction, greater than 0 and up to 1. Default: 0.67. See Details for guidance on choosing a value.
chunk_size: Number of data points per processing chunk, at least 10. Default: 5000.
...: Not used; forces all subsequent arguments to be named.
overlap: Number of overlapping points between consecutive chunks, less than chunk_size. NULL (default) uses chunk_size / 10 (clamped to [1, chunk_size - 10]).
iterations: Number of robustness iterations, between 0 and 1000 (inclusive). Default: 3.
weight_function: Kernel weight function. One of "tricube" (default), "gaussian", "uniform" (alias: "boxcar"), "cosine", "epanechnikov", "biweight" (alias: "bisquare"), or "triangle" (alias: "triangular").
robustness_method: Outlier downweighting method: "bisquare" (default; alias: "biweight"), "huber", or "talwar".
scaling_method: Residual scale estimation for robustness weights: "mad" (default; alias: "median_absolute_deviation"), "mar" (alias: "median_absolute_residual"), or "mean" (alias: "mean_absolute_residual").
boundary_policy: Boundary handling strategy: "extend" (default; alias: "pad"), "reflect" (alias: "mirror"), "zero", or "noboundary" (alias: "none").
zero_weight_fallback: Fallback policy when all robustness weights drop to zero: "use_local_mean" (default; aliases: "local_mean", "mean"), "return_original" (alias: "original"), or "return_none" (alias: "none").
auto_converge: Convergence tolerance for early stopping of robustness iterations. NULL (default) disables early stopping.
intervals: Grouped coverage levels from intervals_opts.
merge_strategy: Strategy for reconciling overlapping chunk regions: "weighted_average" (default; alias: "weighted"), "average" (alias: "mean"), "take_first" (alias: "first"), or "take_last" (alias: "last").
parallel: Logical; enable parallel processing. Default: TRUE.
degree: Local polynomial degree: "constant", "linear" (default), "quadratic", "cubic", or "quartic".
dimensions: Number of predictor dimensions. Default: 1.
distance_metric: Distance metric for neighbourhood computation: "normalized" (default), "euclidean", "manhattan", "chebyshev", "minkowski", or "weighted". Use "minkowski:p" to set a custom p value.
surface_mode: Surface evaluation mode: "interpolation" (default) or "direct".
weighted_metric_weights: Numeric vector of per-dimension weights. Length must equal dimensions. Only used when distance_metric = "weighted"; setting distance_metric = "weighted" without providing this raises an error. NULL (default) has no effect unless distance_metric = "weighted" is set.
cell: Cell size tuning parameter for the interpolation grid. NULL (default) uses the library default.
interpolation_vertices: Number of vertices in the interpolation grid. NULL (default) uses the library default.
boundary_degree_fallback: Logical; if TRUE, interpolation vertices lying outside the range of the data are fitted with a linear model rather than the requested degree, avoiding unstable extrapolation. It has no effect below quadratic degree, and FALSE reproduces stats::loess(). NULL (default) uses the library default.
missing: Policy for non-finite (NaN/Inf) values in the input data: "error" (default) raises an error, "drop" silently removes observations (rows) where any x dimension or y is non-finite (and the matching custom_weights entry) before fitting. A length mismatch between x and y always raises an error, even under "drop".
outputs: Optional character vector selecting "diagnostics", "residuals", "weights", "gradient" (or "derivative"), and "se". NULL (default) selects no optional components.

Value

A StreamingLoess object.

Details

When outputs includes "diagnostics", residual_sd is the cumulative sample standard deviation of emitted residuals. Batch residual_sd instead uses the robust residual scale estimate 1.4826 * MAD. Best suited for datasets over 100,000 points, memory-constrained environments, or batch processing pipelines. For smaller datasets that fit in memory, see Loess; for point-by-point real-time data, see OnlineLoess.

Overlapping regions between chunks are reconciled via merge_strategy:

Strategy	Behavior
`"average"`	Arithmetic mean of both estimates
`"weighted_average"`	Distance-weighted blend (default)
`"take_first"`	Keep left-chunk estimate
`"take_last"`	Keep right-chunk estimate

Examples

x <- seq(0, 10, length.out = 100)
y <- sin(x) + rnorm(100, 0, 0.1)
model <- StreamingLoess(fraction = 0.2, chunk_size = 50)
res1 <- process_chunk(model, x[1:50], y[1:50])
res2 <- process_chunk(model, x[51:100], y[51:100])
finalize(model)
#> <LoessResult>
#>   Points:            5 
#>   Fraction Used:     0.2