Metadata-Version: 2.4
Name: fastloess
Version: 3.0.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Operating System :: OS Independent
Requires-Dist: numpy>=1.20.0
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
Summary: High-performance LOESS smoothing for Python.
Keywords: loess,smoothing,statistics,regression,numpy
Author-email: Amir Valizadeh <thisisamirv@gmail.com>
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/thisisamirv/loess-project/CHANGELOG.md
Project-URL: Documentation, https://loess.readthedocs.io/
Project-URL: Repository, https://github.com/thisisamirv/loess-project

<!-- markdownlint-disable MD024 MD033 -->
# LOESS Project

<p align="center">
  <a href="https://pypi.org/project/fastloess/"><img src="https://img.shields.io/badge/PyPI-3775A9?logo=pypi&logoColor=white" alt="PyPI"></a>
  <a href="https://anaconda.org/conda-forge/fastloess"><img src="https://img.shields.io/badge/fastloess_(Python)-44A833?logo=anaconda&logoColor=white" alt="fastloess (Python)"></a>
  <a href="https://github.com/thisisamirv/loess-project/actions/workflows/ci-python.yml"><img src="https://github.com/thisisamirv/loess-project/actions/workflows/ci-python.yml/badge.svg" alt="CI"></a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/thisisamirv/loess-project/main/dev/logo.png" alt="One LOESS to Rule Them All" width="400">
  <br>
  <em>One LOESS to Rule Them All</em>
</p>

The fastest, most robust, and most feature-complete language-agnostic LOESS (Locally Estimated Scatterplot Smoothing) implementation for **Rust**, **Python**, **R**, **Julia**, **Node.js**, **C++**, **Go**, **Java**, and **WebAssembly**.

The `loess-project` also offers bindings for Rust, Python, R, Julia, Node.js, WebAssembly, C++, Go, and Java — see the [full repository](https://github.com/thisisamirv/loess-project).

---

## Installation & Documentation

> Currently available for R, Python, Rust, Julia, Node.js, WebAssembly, and C++. See the [Installation Guide](https://loess.readthedocs.io/en/latest/introduction/installation/) for detailed installation instructions.
>
> ### 📚 [View the full documentation](https://loess.readthedocs.io/)

---

## 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) |

Read more about how LOESS works in the [Concepts](https://loess.readthedocs.io/en/latest/introduction/concepts.html).

> **Note:** For a **LOWESS** implementation, use [`lowess-project`](https://github.com/thisisamirv/lowess-project).

---

## Why this package?

### Speed

`fastLoess` beats the competition by being **47.3× faster than R's `stats::loess` in serial mode** and **236.4× faster in parallel compared to R's `stats::loess`**; speedups vary by workload, and parallel execution is not always faster. For datasets of 1,000 points or fewer, serial execution is advised.

For more details on the performance comparison, see the [Benchmarks](https://loess.readthedocs.io/en/latest/benchmarks/) page.

### Robustness

This implementation is *more robust* than R's `loess` due to two key design choices:

**MAD-Based Scale Estimation:**

For robustness weight calculations, this crate uses *Median Absolute Deviation (MAD)* for scale estimation:

```text
s = median(|r_i - median(r)|)
```

In contrast, R's `loess` uses the median of absolute residuals (MAR):

```text
s = median(|r_i|)
```

- MAD is a *breakdown-point-optimal* estimator—it remains valid even when up to 50% of data are outliers.
- The median-centering step removes asymmetric bias from residual distributions.
- MAD provides consistent outlier detection regardless of whether residuals are centered around zero.

**Boundary Padding:**

This crate applies a range of different *boundary policies* at dataset edges:

- **Extend**: Repeats edge values to maintain local neighborhood size.
- **Reflect**: Mirrors data symmetrically around boundaries.
- **Zero**: Pads with zeros (useful for signal processing).
- **NoBoundary**: Original Cleveland behavior

R's `loess` does not apply boundary padding, which can lead to:

- Biased estimates near boundaries due to asymmetric local neighborhoods.
- Increased variance at the edges of the smoothed curve.

### Features

A variety of features, supporting a range of use cases:

| Feature                       | This package  | R (stats)        |
|-------------------------------|:-------------:|:----------------:|
| Polynomial Degree             | 5 (0–4)       | 2 (1 or 2)       |
| Kernel                        | 7 options     | only Tricube     |
| Robustness Weighting          | 3 options     | only Bisquare    |
| Scale Estimation              | 3 options     | only MAR         |
| Distance Metric               | 6 options     | normalized only  |
| Boundary Padding              | 4 options     | no padding       |
| Zero Weight Fallback          | 3 options     | no               |
| Auto Convergence              | yes           | no               |
| Online Mode                   | yes           | no               |
| Streaming Mode                | yes           | no               |
| Confidence Intervals          | yes           | no               |
| Prediction Intervals          | yes           | no               |
| Diagnostics (RMSE, R2, AIC)   | yes           | no               |
| Cross-Validation              | 2 options     | no               |
| Parallel Execution            | yes           | no               |
| `no-std` Support              | yes           | no               |

## Validation

All implementations are **numerical twins** of R's `loess`:

| 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 |

---

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](https://github.com/thisisamirv/loess-project/blob/main/CONTRIBUTING.md) for more information.

## License

Licensed under [MIT](https://github.com/thisisamirv/loess-project/blob/main/LICENSE-MIT) or [Apache-2.0](https://github.com/thisisamirv/loess-project/blob/main/LICENSE-APACHE).

## Citation

If you use this software in your research, please cite it using the [CITATION.cff](https://github.com/thisisamirv/loess-project/blob/main/CITATION.cff) file or the BibTeX entry below:

```bibtex
@software{loess_project,
  author = {Valizadeh, Amir},
  title = {LOESS Project: High-Performance Locally Estimated Scatterplot Smoothing},
  year = {2026},
  url = {https://github.com/thisisamirv/loess-project},
  license = {MIT OR Apache-2.0}
}
```

