fastlowess-wasm 0.99.8 → 1.0.0

package/README.md

@@ -1,12 +1,20 @@
 <!-- markdownlint-disable MD024 MD033 -->
 # LOWESS Project
 
-[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE-MIT)
-[![Docs](https://img.shields.io/badge/docs-readthedocs-blue.svg)](https://lowess.readthedocs.io/)
-[![Crates.io](https://img.shields.io/crates/v/lowess.svg)](https://crates.io/crates/lowess)
-[![PyPI](https://img.shields.io/pypi/v/fastlowess.svg)](https://pypi.org/project/fastlowess/)
-[![Conda](https://anaconda.org/conda-forge/fastlowess/badges/version.svg)](https://anaconda.org/conda-forge/fastlowess)
-[![R-universe](https://thisisamirv.r-universe.dev/badges/rfastlowess)](https://thisisamirv.r-universe.dev/rfastlowess)
+<p align="center">
+  <a href="https://crates.io/crates/lowess"><img src="https://img.shields.io/badge/lowess-000000?logo=rust&logoColor=white" alt="lowess"></a>
+  <a href="https://crates.io/crates/fastLowess"><img src="https://img.shields.io/badge/fastLowess-000000?logo=rust&logoColor=white" alt="fastLowess"></a>
+  <a href="https://pypi.org/project/fastlowess/"><img src="https://img.shields.io/badge/PyPI-3775A9?logo=pypi&logoColor=white" alt="PyPI"></a>
+  <a href="https://thisisamirv.r-universe.dev/rfastlowess"><img src="https://img.shields.io/badge/R--universe-276DC3?logo=r&logoColor=white" alt="R-universe"></a>
+  <a href="https://www.npmjs.com/package/fastlowess"><img src="https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white" alt="npm"></a>
+  <a href="https://juliahub.com/ui/Packages/General/fastlowess_jll"><img src="https://img.shields.io/badge/Julia-9558B2?logo=julia&logoColor=white" alt="Julia"></a>
+  <a href="https://www.npmjs.com/package/fastlowess-wasm"><img src="https://img.shields.io/badge/WASM-654FF0?logo=webassembly&logoColor=white" alt="WASM"></a>
+  <a href="https://github.com/thisisamirv/lowess-project/releases/latest"><img src="https://img.shields.io/badge/C++-00599C?logo=cplusplus&logoColor=white" alt="C++"></a>
+  <br>
+  <a href="https://anaconda.org/conda-forge/fastlowess"><img src="https://img.shields.io/badge/fastlowess_(Python)-44A833?logo=anaconda&logoColor=white" alt="fastlowess (Python)"></a>
+  <a href="https://anaconda.org/conda-forge/libfastlowess"><img src="https://img.shields.io/badge/libfastlowess_(C++)-44A833?logo=anaconda&logoColor=white" alt="libfastlowess (C++)"></a>
+  <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>
+</p>
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/thisisamirv/lowess-project/main/dev/logo.png" alt="One LOWESS to Rule Them All" width="400">
@@ -20,14 +28,30 @@ The fastest, most robust, and most feature-complete language-agnostic LOWESS (Lo
 >
 > The `lowess-project` contains a complete ecosystem for LOWESS smoothing:
 >
-> - **[`lowess`](https://github.com/thisisamirv/lowess-project/tree/main/crates/lowess)** - Core single-threaded Rust implementation with `no_std` support
-> - **[`fastLowess`](https://github.com/thisisamirv/lowess-project/tree/main/crates/fastLowess)** - Parallel CPU and GPU-accelerated Rust wrapper with ndarray integration  
-> - **[`R bindings`](https://github.com/thisisamirv/lowess-project/tree/main/bindings/r)** - extendr-based R package
-> - **[`Python bindings`](https://github.com/thisisamirv/lowess-project/tree/main/bindings/python)** - PyO3-based Python package
-> - **[`Julia bindings`](https://github.com/thisisamirv/lowess-project/tree/main/bindings/julia)** - Native Julia package with C FFI
-> - **[`JavaScript bindings`](https://github.com/thisisamirv/lowess-project/tree/main/bindings/nodejs)** - Node.js package
-> - **[`WebAssembly bindings`](https://github.com/thisisamirv/lowess-project/tree/main/bindings/wasm)** - WASM package
-> - **[`C++ bindings`](https://github.com/thisisamirv/lowess-project/tree/main/bindings/cpp)** - Native C++ package with CMake integration
+> - **[`lowess`](https://crates.io/crates/lowess)** - Core single-threaded Rust implementation with `no_std` support
+> - **[`fastLowess`](https://crates.io/crates/fastLowess)** - Parallel CPU and GPU-accelerated Rust wrapper with ndarray integration  
+> - **[`R bindings`](https://thisisamirv.r-universe.dev/rfastlowess)** - extendr-based R binding
+> - **[`Python bindings`](https://pypi.org/project/fastlowess/)** - PyO3-based Python binding
+> - **[`Julia bindings`](https://juliahub.com/ui/Packages/General/fastlowess_jll)** - Native Julia binding with C FFI
+> - **[`JavaScript bindings`](https://www.npmjs.com/package/fastlowess)** - Node.js binding
+> - **[`WebAssembly bindings`](https://www.npmjs.com/package/fastlowess-wasm)** - WASM binding
+> - **[`C++ bindings`](https://github.com/thisisamirv/lowess-project/releases/latest)** - Native C++ binding with CMake integration
+
+---
+
+## Installation
+
+> [!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.
+
+## Documentation
+
+> [!NOTE]
+>
+> ### 📚 [View the full documentation](https://lowess.readthedocs.io/)
+
+---
 
 ## LOESS vs. LOWESS
 
@@ -43,38 +67,13 @@ The fastest, most robust, and most feature-complete language-agnostic LOWESS (Lo
 
 ---
 
-## Documentation
-
-> [!NOTE]
->
-> ### 📚 [View the full documentation](https://lowess.readthedocs.io/)
-
 ## Why this package?
 
 ### Speed
 
-The `lowess` project crushes the competition in terms of speed, wether in single-threaded or multi-threaded parallel execution.
-
-Speedup relative to Python's `statsmodels.lowess` (higher is better):
-
-| Category                        | statsmodels | R (stats) | Serial | Parallel | GPU     |
-|---------------------------------|-------------|-----------|--------|----------|---------|
-| **Clustered**                   | 163ms       | 83×       | 203×   | **433×** | 32×     |
-| **Constant Y**                  | 134ms       | 92×       | 212×   | **410×** | 18×     |
-| **Delta** (large–none)          | 105ms       | 2×        | 4×     | 6×       | **16×** |
-| **Extreme Outliers**            | 489ms       | 106×      | 201×   | **388×** | 29×     |
-| **Financial** (500–10K)         | 106ms       | 105×      | 252×   | **293×** | 12×     |
-| **Fraction** (0.05–0.67)        | 221ms       | 104×      | 228×   | **391×** | 22×     |
-| **Genomic** (1K–50K)            | 1833ms      | 7×        | 9×     | 20×      | **95×** |
-| **High Noise**                  | 435ms       | 133×      | 134×   | **375×** | 32×     |
-| **Iterations** (0–10)           | 204ms       | 115×      | 224×   | **386×** | 18×     |
-| **Scale** (1K–50K)              | 1841ms      | 264×      | 487×   | **581×** | 98×     |
-| **Scientific** (500–10K)        | 167ms       | 109×      | 205×   | **314×** | 15×     |
-| **Scale Large**\* (100K–2M)     | —           | —         | 1×     | **1.4×** | 0.3×    |
-
-\*Scale Large benchmarks are relative to Serial (statsmodels cannot handle these sizes)
+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`.
 
-*The numbers are the average across a range of scenarios for each category (e.g., Delta from none, to small, medium, and large).*
+For more details on the performance comparison, see the [BENCHMARKS](https://github.com/thisisamirv/lowess-project/blob/main/BENCHMARKS.md) file.
 
 ### Robustness
 
@@ -145,185 +144,12 @@ All implementations are **numerical twins** of R's `lowess`:
 | **Consistency** | ✅ PERFECT     | Multiple scenarios pass with strict tolerance |
 | **Robustness**  | ✅ VERIFIED    | Robust smoothing matches R exactly            |
 
-## Installation
-
-Currently available for R, Python, Julia, and Rust:
-
-**R** (from R-universe, recommended):
-
-```r
-install.packages("rfastlowess", repos = "https://thisisamirv.r-universe.dev")
-```
-
-**Python** (from PyPI):
-
-```bash
-pip install fastlowess
-```
-
-Or from conda-forge:
-
-```bash
-conda install -c conda-forge fastlowess
-```
-
-**Rust** (lowess, no_std compatible):
-
-```toml
-[dependencies]
-lowess = "0.99"
-```
-
-**Rust** (fastLowess, parallel + GPU):
-
-```toml
-[dependencies]
-fastLowess = { version = "0.99", features = ["cpu"] }
-```
-
-**Julia** (from Julia General Registry):
-
-```julia
-using Pkg
-Pkg.add("fastLowess")
-```
-
-**Node.js** (from npm):
-
-```bash
-npm install fastlowess
-```
-
-**WebAssembly** (from npm):
-
-```bash
-npm install fastlowess-wasm
-```
-
-Or via CDN:
-
-```html
-<script type="module">
-  import init, { smooth } from 'https://unpkg.com/fastlowess-wasm@latest';
-  await init();
-</script>
-```
-
-**C++** (build from source):
-
-```bash
-make cpp
-# Links against libfastlowess_cpp.so
-```
-
-## Quick Example
-
-**R:**
-
-```r
-library(rfastlowess)
-
-x <- c(1, 2, 3, 4, 5)
-y <- c(2.0, 4.1, 5.9, 8.2, 9.8)
-
-result <- fastlowess(x, y, fraction = 0.5, iterations = 3)
-print(result$y)
-```
-
-**Python:**
-
-```python
-import fastlowess as fl
-import numpy as np
-
-x = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
-y = np.array([2.0, 4.1, 5.9, 8.2, 9.8])
-
-result = fl.smooth(x, y, fraction=0.5, iterations=3)
-print(result["y"])
-```
-
-**Rust:**
-
-```rust
-use lowess::prelude::*;
-
-let x = vec![1.0, 2.0, 3.0, 4.0, 5.0];
-let y = vec![2.0, 4.1, 5.9, 8.2, 9.8];
-
-let model = Lowess::new()
-    .fraction(0.5)
-    .iterations(3)
-    .adapter(Batch)
-    .build()?;
-
-let result = model.fit(&x, &y)?;
-println!("{}", result);
-```
-
-**Julia:**
-
-```julia
-using fastlowess
-
-x = [1.0, 2.0, 3.0, 4.0, 5.0]
-y = [2.0, 4.1, 5.9, 8.2, 9.8]
-
-result = smooth(x, y, fraction=0.5, iterations=3)
-println(result.y)
-```
-
-**Node.js:**
-
-```javascript
-const { smooth } = require('fastlowess');
-
-const x = [1.0, 2.0, 3.0, 4.0, 5.0];
-const y = [2.0, 4.1, 5.9, 8.2, 9.8];
-
-const result = smooth(x, y, { fraction: 0.5, iterations: 3 });
-console.log(result.y);
-```
-
-**WebAssembly:**
-
-```javascript
-import init, { smooth } from 'fastlowess-wasm';
-
-await init();
-
-const x = new Float64Array([1.0, 2.0, 3.0, 4.0, 5.0]);
-const y = new Float64Array([2.0, 4.1, 5.9, 8.2, 9.8]);
-
-const result = smooth(x, y, { fraction: 0.5, iterations: 3 });
-console.log(result.y);
-```
-
-**C++:**
-
-```cpp
-#include <fastlowess.hpp>
-
-std::vector<double> x = {1.0, 2.0, 3.0, 4.0, 5.0};
-std::vector<double> y = {2.0, 4.1, 5.9, 8.2, 9.8};
-
-fastlowess::LowessOptions options;
-options.fraction = 0.5;
-options.iterations = 3;
-
-auto result = fastlowess::smooth(x, y, options);
-for (double val : result.y_vector()) std::cout << val << " ";
-```
-
----
-
 ## API Reference
 
 **R:**
 
 ```r
-fastlowess(
-    x, y,
+Lowess(
     fraction = 0.5,
     iterations = 3L,
     delta = 0.01,
@@ -341,14 +167,30 @@ fastlowess(
     cv_k = 5L,
     auto_converge = 1e-4,
     parallel = TRUE
-)
+)$fit(x, y)
+
+# Result structure:
+result$x,
+result$y,
+result$standard_errors,
+result$confidence_lower,
+result$confidence_upper,
+result$prediction_lower,
+result$prediction_upper,
+result$residuals,
+result$robustness_weights,
+result$diagnostics,
+result$iterations_used,
+result$fraction_used,
+result$cv_scores
 ```
 
 **Python:**
 
 ```python
-fastlowess.smooth(
-    x, y,
+from fastlowess import Lowess
+
+model = Lowess(
     fraction=0.5,
     iterations=3,
     delta=0.01,
@@ -367,16 +209,32 @@ fastlowess.smooth(
     auto_converge=1e-4,
     parallel=True
 )
+result = model.fit(x, y)
+
+# Result structure:
+result.x,
+result.y,
+result.standard_errors,
+result.confidence_lower,
+result.confidence_upper,
+result.prediction_lower,
+result.prediction_upper,
+result.residuals,
+result.robustness_weights,
+result.diagnostics,
+result.iterations_used,
+result.fraction_used,
+result.cv_scores
 ```
 
 **Rust:**
 
 ```rust
 Lowess::new()
-    .fraction(0.5)              // Smoothing span (0, 1]
-    .iterations(3)              // Robustness iterations
-    .delta(0.01)                // Interpolation threshold
-    .weight_function(Tricube)   // Kernel selection
+    .fraction(0.5)
+    .iterations(3)
+    .delta(0.01)
+    .weight_function(Tricube)
     .robustness_method(Bisquare)
     .zero_weight_fallback(UseLocalMean)
     .boundary_policy(Extend)
@@ -387,17 +245,35 @@ Lowess::new()
     .return_robustness_weights()
     .cross_validate(KFold(5, &[0.3, 0.5, 0.7]).seed(123))
     .auto_converge(1e-4)
-    .adapter(Batch)             // or Streaming, Online
+    .adapter(Batch)
     .parallel(true)             // fastLowess only
     .backend(CPU)               // fastLowess only: CPU or GPU
     .build()?;
+
+let result = model.fit(x, y);
+
+// Result structure:
+pub struct LowessResult<T> {
+    pub x: Vec<T>,                           // Sorted x values
+    pub y: Vec<T>,                           // Smoothed y values
+    pub standard_errors: Option<Vec<T>>,
+    pub confidence_lower: Option<Vec<T>>,
+    pub confidence_upper: Option<Vec<T>>,
+    pub prediction_lower: Option<Vec<T>>,
+    pub prediction_upper: Option<Vec<T>>,
+    pub residuals: Option<Vec<T>>,
+    pub robustness_weights: Option<Vec<T>>,
+    pub diagnostics: Option<Diagnostics<T>>,
+    pub iterations_used: Option<usize>,
+    pub fraction_used: T,
+    pub cv_scores: Option<Vec<T>>,
+}
 ```
 
 **Julia:**
 
 ```julia
-smooth(
-    x, y,
+Lowess(;
     fraction=0.5,
     iterations=3,
     delta=NaN,  # NaN for auto
@@ -405,23 +281,38 @@ smooth(
     robustness_method="bisquare",
     zero_weight_fallback="use_local_mean",
     boundary_policy="extend",
-    confidence_intervals=0.95,
-    prediction_intervals=0.95,
+    confidence_intervals=NaN,
+    prediction_intervals=NaN,
     return_diagnostics=true,
     return_residuals=true,
     return_robustness_weights=true,
-    cv_fractions=[0.3, 0.5, 0.7],
+    cv_fractions=Float64[], # e.g. [0.3, 0.5]
     cv_method="kfold",
     cv_k=5,
-    auto_converge=1e-4,
+    auto_converge=NaN,
     parallel=true
 )
+
+# Result structure:
+result.x,
+result.y,
+result.standard_errors,
+result.confidence_lower,
+result.confidence_upper,
+result.prediction_lower,
+result.prediction_upper,
+result.residuals,
+result.robustness_weights,
+result.diagnostics,
+result.iterations_used,
+result.fraction_used,
+result.cv_scores
 ```
 
 **Node.js:**
 
 ```javascript
-smooth(x, y, {
+new Lowess({
     fraction: 0.5,
     iterations: 3,
     delta: 0.01,
@@ -439,7 +330,22 @@ smooth(x, y, {
     cvK: 5,
     autoConverge: 1e-4,
     parallel: true
-})
+}).fit(x, y)
+
+// Result structure:
+result.x,
+result.y,
+result.standardErrors,
+result.confidenceLower,
+result.confidenceUpper,
+result.predictionLower,
+result.predictionUpper,
+result.residuals,
+result.robustnessWeights,
+result.diagnostics,
+result.iterationsUsed,
+result.fractionUsed,
+result.cvScores
 ```
 
 **WebAssembly:**
@@ -461,8 +367,24 @@ smooth(x, y, {
     cvFractions: [0.3, 0.5, 0.7],
     cvMethod: "kfold",
     cvK: 5,
-    autoConverge: 1e-4
+    autoConverge: 1e-4,
+    parallel: true
 })
+
+// Result structure:
+result.x,
+result.y,
+result.standardErrors,
+result.confidenceLower,
+result.confidenceUpper,
+result.predictionLower,
+result.predictionUpper,
+result.residuals,
+result.robustnessWeights,
+result.diagnostics,
+result.iterationsUsed,
+result.fractionUsed,
+result.cvScores
 ```
 
 **C++:**
@@ -487,99 +409,23 @@ options.cv_k = 5;
 options.auto_converge = 1e-4;
 options.parallel = true;
 
-auto result = fastlowess::smooth(x, y, options);
-```
-
-## Result Structure
-
-**R:**
-
-```r
-result$x, result$y, result$standard_errors
-result$confidence_lower, result$confidence_upper
-result$prediction_lower, result$prediction_upper
-result$residuals, result$robustness_weights
-result$diagnostics, result$iterations_used
-result$fraction_used, result$cv_scores
-```
-
-**Python:**
-
-```python
-result.x, result.y, result.standard_errors
-result.confidence_lower, result.confidence_upper
-result.prediction_lower, result.prediction_upper
-result.residuals, result.robustness_weights
-result.diagnostics, result.iterations_used
-result.fraction_used, result.cv_scores
-```
-
-**Rust:**
-
-```rust
-pub struct LowessResult<T> {
-    pub x: Vec<T>,                           // Sorted x values
-    pub y: Vec<T>,                           // Smoothed y values
-    pub standard_errors: Option<Vec<T>>,
-    pub confidence_lower: Option<Vec<T>>,
-    pub confidence_upper: Option<Vec<T>>,
-    pub prediction_lower: Option<Vec<T>>,
-    pub prediction_upper: Option<Vec<T>>,
-    pub residuals: Option<Vec<T>>,
-    pub robustness_weights: Option<Vec<T>>,
-    pub diagnostics: Option<Diagnostics<T>>,
-    pub iterations_used: Option<usize>,
-    pub fraction_used: T,
-    pub cv_scores: Option<Vec<T>>,
-}
-```
-
-**Julia:**
-
-```julia
-result.x, result.y, result.standard_errors
-result.confidence_lower, result.confidence_upper
-result.prediction_lower, result.prediction_upper
-result.residuals, result.robustness_weights
-result.diagnostics, result.iterations_used
-result.fraction_used
-```
-
-**Node.js:**
-
-```javascript
-result.x, result.y, result.standardErrors
-result.confidenceLower, result.confidenceUpper
-result.predictionLower, result.predictionUpper
-result.residuals, result.robustnessWeights
-result.diagnostics, result.iterationsUsed
-result.fractionUsed, result.cvScores
-```
-
-**WebAssembly:**
-
-```javascript
-result.x, result.y, result.standardErrors
-result.confidenceLower, result.confidenceUpper
-result.predictionLower, result.predictionUpper
-result.residuals, result.robustnessWeights
-result.diagnostics, result.iterationsUsed
-result.fractionUsed, result.cvScores
-```
-
-**C++:**
-
-```cpp
-result.y_vector()              // std::vector<double>
-result.confidence_lower()      // std::vector<double>
-result.confidence_upper()      // std::vector<double>
-result.prediction_lower()      // std::vector<double>
-result.prediction_upper()      // std::vector<double>
-result.residuals()             // std::vector<double>
-result.robustness_weights()    // std::vector<double>
-result.diagnostics()           // Diagnostics struct
-result.iterations_used()       // size_t
-result.fraction_used()         // double
+fastlowess::Lowess model(options);
+auto result = model.fit(x, y);
+
+// Result structure:
+result.x_vector(),
+result.y_vector(),
+result.standard_errors(),
+result.confidence_lower(),
+result.confidence_upper(),
+result.prediction_lower(),
+result.prediction_upper(),
+result.residuals(),
+result.robustness_weights(),
+result.diagnostics(),
+result.iterations_used(),
+result.fraction_used(),
+result.cv_scores()
 ```
 
 ---
@@ -590,17 +436,7 @@ Contributions are welcome! Please see the [CONTRIBUTING.md](https://github.com/t
 
 ## License
 
-Licensed under either of:
-
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
-
-at your option.
-
-## References
-
-- Cleveland, W.S. (1979). "Robust Locally Weighted Regression and Smoothing Scatterplots". *JASA*.
-- Cleveland, W.S. (1981). "LOWESS: A Program for Smoothing Scatterplots". *The American Statistician*.
+Licensed under [MIT](https://github.com/thisisamirv/lowess-project/blob/main/LICENSE-MIT) or [Apache-2.0](https://github.com/thisisamirv/lowess-project/blob/main/LICENSE-APACHE).
 
 ## Citation