fastlowess-wasm 1.3.0 → 3.0.0

package/README.md

@@ -16,6 +16,7 @@
   <a href="https://anaconda.org/conda-forge/r-rfastlowess"><img src="https://img.shields.io/badge/rfastlowess_(R)-44A833?logo=anaconda&logoColor=white" alt="rfastlowess (R)"></a>
   <br>
   <a href="https://github.com/thisisamirv/lowess-project/actions/workflows/ci.yml"><img src="https://github.com/thisisamirv/lowess-project/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/ropensci/software-review/issues/769"><img src="https://badges.ropensci.org/769_status.svg" alt="Status at rOpenSci Software Peer Review"></a>
 </p>
 
 <p align="center">
@@ -45,7 +46,11 @@ The fastest, most robust, and most feature-complete language-agnostic LOWESS (Lo
 
 > [!NOTE]
 >
-> Currently available for R, Python, Rust, Julia, Node.js, WebAssembly, and C++. See [INSTALLATION.md](https://github.com/thisisamirv/lowess-project/blob/main/INSTALLATION.md) for detailed installation instructions.
+> Currently available for R, Python, Rust, Julia, Node.js, WebAssembly, and C++. See the [Installation Guide](https://lowess.readthedocs.io/getting-started/installation/) for detailed installation instructions.
+
+### GPU Backend
+
+In addition to `parallel = true` (multi-core CPU), the batch `Lowess` class in every binding — except WebAssembly — as well as the `fastLowess` Rust crate itself, can run on the GPU via `wgpu` (Vulkan/Metal/DX12). It's opt-in and worth enabling for high-throughput processing of large datasets (roughly 10k+ points); for smaller inputs the CPU backend is typically faster. `StreamingLowess`/`OnlineLowess` remain CPU-only. See the [GPU Backend guide](https://lowess.readthedocs.io/en/latest/user-guide/gpu-backend/) for installation instructions and usage.
 
 ## Documentation
 
@@ -57,12 +62,12 @@ The fastest, most robust, and most feature-complete language-agnostic LOWESS (Lo
 
 ## LOESS vs. LOWESS
 
-| Feature               | LOESS (This Crate)                | LOWESS                         |
-|-----------------------|-----------------------------------|--------------------------------|
-| **Polynomial Degree** | Linear, Quadratic, Cubic, Quartic | Linear (Degree 1)              |
-| **Dimensions**        | Multivariate (n-D support)        | Univariate (1-D only)          |
-| **Flexibility**       | High (Distance metrics)           | Standard                       |
-| **Complexity**        | Higher (Matrix inversion)         | Lower (Weighted average/slope) |
+| Feature | LOESS | LOWESS (This Crate) |
+| --- | --- | --- |
+| **Polynomial Degree** | Linear, Quadratic, Cubic, Quartic | Linear (Degree 1) |
+| **Dimensions** | Multivariate (n-D support) | Univariate (1-D only) |
+| **Flexibility** | High (Distance metrics) | Standard |
+| **Complexity** | Higher (Matrix inversion) | Lower (Weighted average/slope) |
 
 > [!TIP]
 > **Note:** For a **LOESS** implementation, use [`loess-project`](https://github.com/thisisamirv/loess-project).
@@ -75,7 +80,7 @@ The fastest, most robust, and most feature-complete language-agnostic LOWESS (Lo
 
 The `lowess` project beats the competition in terms of speed, whether in single-threaded or multi-threaded parallel execution. It is on average **200-327x faster** than Python's `statsmodels.lowess` and **2-3x faster** than R's `lowess`.
 
-For more details on the performance comparison, see the [BENCHMARKS](https://github.com/thisisamirv/lowess-project/blob/main/BENCHMARKS.md) file.
+For more details on the performance comparison, see the [Benchmarks](https://lowess.readthedocs.io/benchmarks/) page.
 
 ### Robustness
 
@@ -117,46 +122,47 @@ This crate applies a range of different *boundary policies* at dataset edges:
 
 A variety of features, supporting a range of use cases:
 
-| Feature              | This package  | statsmodels  | R (stats)    |
-|----------------------|:-------------:|:------------:|:------------:|
-| Kernel               | 7 options     | only Tricube | only Tricube |
-| Robustness Weighting | 3 options     | only Huber   | only Huber   |
-| Scale Estimation     | 2 options     | only MAR     | only MAR     |
-| Boundary Padding     | 4 options     | no padding   | no padding   |
-| Zero Weight Fallback | 3 options     | no           | no           |
-| Auto Convergence     | yes           | no           | no           |
-| Online Mode          | yes           | no           | no           |
-| Streaming Mode       | yes           | no           | no           |
-| Confidence Intervals | yes           | no           | no           |
-| Prediction Intervals | yes           | no           | no           |
-| Cross-Validation     | 2 options     | no           | no           |
-| Parallel Execution   | yes           | no           | no           |
-| GPU Acceleration     | yes*          | no           | no           |
-| `no-std` Support     | yes           | no           | no           |
-
-\* GPU acceleration is currently in beta and may not be available on all platforms.
+| Feature | This package | statsmodels | R (stats) |
+| --- | :---: | :---: | :---: |
+| Kernel | 7 options | only Tricube | only Tricube |
+| Robustness Weighting | 3 options | only Huber | only Huber |
+| Scale Estimation | 2 options | only MAR | only MAR |
+| Boundary Padding | 4 options | no padding | no padding |
+| Zero Weight Fallback | 3 options | no | no |
+| Auto Convergence | yes | no | no |
+| Online Mode | yes | no | no |
+| Streaming Mode | yes | no | no |
+| Confidence Intervals | yes | no | no |
+| Prediction Intervals | yes | no | no |
+| Cross-Validation | 2 options | no | no |
+| Parallel Execution | yes | no | no |
+| GPU Acceleration | yes | no | no |
+| `no-std` Support | yes | no | no |
 
 ## Validation
 
 All implementations are **numerical twins** of R's `lowess`:
 
-| Aspect          | Status         | Details                                       |
-|-----------------|----------------|-----------------------------------------------|
-| **Accuracy**    | ✅ EXACT MATCH | Max diff < 1e-12 across all scenarios         |
-| **Consistency** | ✅ PERFECT     | Multiple scenarios pass with strict tolerance |
-| **Robustness**  | ✅ VERIFIED    | Robust smoothing matches R exactly            |
+| Aspect | Status | Details |
+| --- | --- | --- |
+| **Accuracy** | ✅ EXACT MATCH | Max diff < 1e-12 across all scenarios |
+| **Consistency** | ✅ PERFECT | Multiple scenarios pass with strict tolerance |
+| **Robustness** | ✅ VERIFIED | Robust smoothing matches R exactly |
 
 ## API Reference
 
 **R:**
 
 ```r
-Lowess(
+library(rfastlowess)
+
+model <- Lowess(
     fraction = 0.5,
     iterations = 3L,
     delta = 0.01,
     weight_function = "tricube",
     robustness_method = "bisquare",
+    scaling_method = "mad",
     zero_weight_fallback = "use_local_mean",
     boundary_policy = "extend",
     confidence_intervals = 0.95,
@@ -164,12 +170,16 @@ Lowess(
     return_diagnostics = TRUE,
     return_residuals = TRUE,
     return_robustness_weights = TRUE,
+    return_se = TRUE,
     cv_fractions = c(0.3, 0.5, 0.7),
     cv_method = "kfold",
     cv_k = 5L,
+    cv_seed = 123L,
     auto_converge = 1e-4,
     parallel = TRUE
-)$fit(x, y)
+)
+custom_weights <- rep(1, length(x))
+result <- fit(model, x, y, custom_weights = custom_weights)
 
 # Result structure:
 result$x,
@@ -198,6 +208,7 @@ model = Lowess(
     delta=0.01,
     weight_function="tricube",
     robustness_method="bisquare",
+    scaling_method="mad",
     zero_weight_fallback="use_local_mean",
     boundary_policy="extend",
     confidence_intervals=0.95,
@@ -205,13 +216,16 @@ model = Lowess(
     return_diagnostics=True,
     return_residuals=True,
     return_robustness_weights=True,
+    return_se=True,
     cv_fractions=[0.3, 0.5, 0.7],
     cv_method="kfold",
     cv_k=5,
+    cv_seed=123,
     auto_converge=1e-4,
     parallel=True
 )
-result = model.fit(x, y)
+custom_weights = [1.0] * len(x)
+result = model.fit(x, y, custom_weights=custom_weights)
 
 # Result structure:
 result.x,
@@ -232,27 +246,32 @@ result.cv_scores
 **Rust:**
 
 ```rust
-Lowess::new()
+use lowess::prelude::*;
+
+let model = Lowess::new()
     .fraction(0.5)
     .iterations(3)
     .delta(0.01)
-    .weight_function(Tricube)
-    .robustness_method(Bisquare)
-    .zero_weight_fallback(UseLocalMean)
-    .boundary_policy(Extend)
+    .weight_function("tricube")
+    .robustness_method("bisquare")
+    .scaling_method("mad")
+    .zero_weight_fallback("use_local_mean")
+    .boundary_policy("extend")
+    .return_se()
     .confidence_intervals(0.95)
     .prediction_intervals(0.95)
     .return_diagnostics()
     .return_residuals()
     .return_robustness_weights()
-    .cross_validate(KFold(5, &[0.3, 0.5, 0.7]).seed(123))
+    .cv_method("kfold")
+    .cv_k(5)
+    .cv_fractions(vec![0.3, 0.5, 0.7])
+    .cv_seed(123)
     .auto_converge(1e-4)
-    .adapter(Batch)
-    .parallel(true)             // fastLowess only
-    .backend(CPU)               // fastLowess only: CPU or GPU
+    .custom_weights(vec![1.0; x.len()])
     .build()?;
 
-let result = model.fit(x, y);
+let result = model.fit(&x, &y)?;
 
 // Result structure:
 pub struct LowessResult<T> {
@@ -275,12 +294,15 @@ pub struct LowessResult<T> {
 **Julia:**
 
 ```julia
-Lowess(;
+using FastLOWESS
+
+model = Lowess(;
     fraction=0.5,
     iterations=3,
     delta=NaN,  # NaN for auto
     weight_function="tricube",
     robustness_method="bisquare",
+    scaling_method="mad",
     zero_weight_fallback="use_local_mean",
     boundary_policy="extend",
     confidence_intervals=NaN,
@@ -288,12 +310,16 @@ Lowess(;
     return_diagnostics=true,
     return_residuals=true,
     return_robustness_weights=true,
+    return_se=true,
     cv_fractions=Float64[], # e.g. [0.3, 0.5]
     cv_method="kfold",
     cv_k=5,
+    cv_seed=123,
     auto_converge=NaN,
     parallel=true
 )
+custom_weights = ones(length(x))
+result = fit(model, x, y; custom_weights=custom_weights)
 
 # Result structure:
 result.x,
@@ -314,90 +340,107 @@ result.cv_scores
 **Node.js:**
 
 ```javascript
-new Lowess({
+import { Lowess } from "fastlowess"
+
+const model = new Lowess({
     fraction: 0.5,
     iterations: 3,
     delta: 0.01,
-    weightFunction: "tricube",
-    robustnessMethod: "bisquare",
-    zeroWeightFallback: "use_local_mean",
-    boundaryPolicy: "extend",
-    confidenceIntervals: 0.95,
-    predictionIntervals: 0.95,
-    returnDiagnostics: true,
-    returnResiduals: true,
-    returnRobustnessWeights: true,
-    cvFractions: [0.3, 0.5, 0.7],
-    cvMethod: "kfold",
-    cvK: 5,
-    autoConverge: 1e-4,
+    weight_function: "tricube",
+    robustness_method: "bisquare",
+    scaling_method: "mad",
+    zero_weight_fallback: "use_local_mean",
+    boundary_policy: "extend",
+    return_se: true,
+    confidence_intervals: 0.95,
+    prediction_intervals: 0.95,
+    return_diagnostics: true,
+    return_residuals: true,
+    return_robustness_weights: true,
+    cv_fractions: [0.3, 0.5, 0.7],
+    cv_method: "kfold",
+    cv_k: 5,
+    cv_seed: 123,
+    auto_converge: 1e-4,
     parallel: true
-}).fit(x, y)
+})
+const custom_weights = Array(x.length).fill(1.0)
+const result = model.fit(x, y, custom_weights)
 
 // Result structure:
 result.x,
 result.y,
-result.standardErrors,
-result.confidenceLower,
-result.confidenceUpper,
-result.predictionLower,
-result.predictionUpper,
+result.standard_errors,
+result.confidence_lower,
+result.confidence_upper,
+result.prediction_lower,
+result.prediction_upper,
 result.residuals,
-result.robustnessWeights,
+result.robustness_weights,
 result.diagnostics,
-result.iterationsUsed,
-result.fractionUsed,
-result.cvScores
+result.iterations_used,
+result.fraction_used,
+result.cv_scores
 ```
 
 **WebAssembly:**
 
 ```javascript
-smooth(x, y, {
+import { Lowess } from "fastlowess-wasm"
+
+const model = new Lowess({
     fraction: 0.5,
     iterations: 3,
     delta: 0.01,
-    weightFunction: "tricube",
-    robustnessMethod: "bisquare",
-    zeroWeightFallback: "use_local_mean",
-    boundaryPolicy: "extend",
-    confidenceIntervals: 0.95,
-    predictionIntervals: 0.95,
-    returnDiagnostics: true,
-    returnResiduals: true,
-    returnRobustnessWeights: true,
-    cvFractions: [0.3, 0.5, 0.7],
-    cvMethod: "kfold",
-    cvK: 5,
-    autoConverge: 1e-4,
+    weight_function: "tricube",
+    robustness_method: "bisquare",
+    scaling_method: "mad",
+    zero_weight_fallback: "use_local_mean",
+    boundary_policy: "extend",
+    return_se: true,
+    confidence_intervals: 0.95,
+    prediction_intervals: 0.95,
+    return_diagnostics: true,
+    return_residuals: true,
+    return_robustness_weights: true,
+    cv_fractions: [0.3, 0.5, 0.7],
+    cv_method: "kfold",
+    cv_k: 5,
+    cv_seed: 123,
+    auto_converge: 1e-4,
     parallel: true
 })
+const custom_weights = new Float64Array(x.length).fill(1)
+const result = model.fit(x, y, custom_weights)
 
 // Result structure:
 result.x,
 result.y,
-result.standardErrors,
-result.confidenceLower,
-result.confidenceUpper,
-result.predictionLower,
-result.predictionUpper,
+result.standard_errors,
+result.confidence_lower,
+result.confidence_upper,
+result.prediction_lower,
+result.prediction_upper,
 result.residuals,
-result.robustnessWeights,
+result.robustness_weights,
 result.diagnostics,
-result.iterationsUsed,
-result.fractionUsed,
-result.cvScores
+result.iterations_used,
+result.fraction_used,
+result.cv_scores
 ```
 
 **C++:**
 
 ```cpp
+#include "fastlowess.hpp"
+
 fastlowess::LowessOptions options;
 options.fraction = 0.5;
 options.iterations = 3;
 options.delta = 0.01;
 options.weight_function = "tricube";
 options.robustness_method = "bisquare";
+options.scaling_method = "mad";
 options.zero_weight_fallback = "use_local_mean";
 options.boundary_policy = "extend";
 options.confidence_intervals = 0.95;
@@ -405,28 +448,31 @@ options.prediction_intervals = 0.95;
 options.return_diagnostics = true;
 options.return_residuals = true;
 options.return_robustness_weights = true;
+options.return_se = true;
 options.cv_fractions = {0.3, 0.5, 0.7};
 options.cv_method = "kfold";
 options.cv_k = 5;
+options.cv_seed = 123;
 options.auto_converge = 1e-4;
 options.parallel = true;
 
 fastlowess::Lowess model(options);
-auto result = model.fit(x, y);
+std::vector<double> custom_weights(x.size(), 1.0);
+const auto result = model.fit(x, y, custom_weights).value();
 
 // Result structure:
-result.xVector(),
-result.yVector(),
-result.standardErrors(),
-result.confidenceLower(),
-result.confidenceUpper(),
-result.predictionLower(),
-result.predictionUpper(),
+result.x_vector(),
+result.y_vector(),
+result.standard_errors(),
+result.confidence_lower(),
+result.confidence_upper(),
+result.prediction_lower(),
+result.prediction_upper(),
 result.residuals(),
-result.robustnessWeights(),
+result.robustness_weights(),
 result.diagnostics(),
-result.iterationsUsed(),
-result.fractionUsed(),
+result.iterations_used(),
+result.fraction_used(),
 result.cv_scores()
 ```
 
@@ -434,7 +480,11 @@ result.cv_scores()
 
 ## Contributing
 
-Contributions are welcome! Please see the [CONTRIBUTING.md](https://github.com/thisisamirv/lowess-project/blob/main/CONTRIBUTING.md) file for more information.
+Contributions are welcome! Please see the [Contributing Guide](https://lowess.readthedocs.io/en/latest/contributing/) for more information.
+
+## Changelog
+
+See the [Changelog](https://lwoess.readthedocs.io/en/latest/changelog/) for a history of changes.
 
 ## License