Metadata-Version: 2.4
Name: kernelmoments
Version: 0.1.0
Summary: Data visualisation and estimation tools based on kernel regression
Author-email: tlaiho <tslaiho@gmail.com>
License: MIT
Project-URL: Repository, https://github.com/tlaiho/kernelmoments
Project-URL: Issues, https://github.com/tlaiho/kernelmoments/issues
Keywords: kernel-regression,conditional-moments,nonparametric,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: kernelboost>=0.3.1
Requires-Dist: numpy
Requires-Dist: matplotlib
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x; extra == "gpu"
Dynamic: license-file

[![PyPI version](https://img.shields.io/pypi/v/kernelmoments)](https://pypi.org/project/kernelmoments/)
[![Python](https://img.shields.io/pypi/pyversions/kernelmoments)](https://pypi.org/project/kernelmoments/)
[![License: MIT](https://img.shields.io/pypi/l/kernelmoments)](https://opensource.org/licenses/MIT)
[![NumPy](https://img.shields.io/badge/NumPy-%23013243?logo=numpy&logoColor=white)](https://numpy.org/)
[![CuPy](https://img.shields.io/badge/CuPy-%23013243?logo=nvidia&logoColor=white)](https://cupy.dev/)

# kernelmoments

Estimate and visualize conditional moments — means, variances, covariances, and correlations — using adaptive kernel regression. Built on [kernelboost](https://pypi.org/project/kernelboost/)'s `KernelTree`, which partitions data and fits local Nadaraya-Watson estimators with automatic bandwidth selection.

Designed for interactive data exploration. Typically fits in under a second on moderately sized datasets (a few thousand rows on CPU, more with GPU acceleration).

For a full tutorial and examples, see the [GitHub repository](https://github.com/tlaiho/kernelmoments).

## Installation

```bash
pip install kernelmoments
```

For GPU acceleration (CUDA 12):

```bash
pip install kernelmoments[gpu]
```

## Quick start

### Plot from NumPy arrays with `plot_relationship`

```python
from kernelmoments import plot_relationship

# Conditional mean with +-1.96*sqrt(Var) prediction bands
result = plot_relationship(x, y, moment="mean", bands=True)

# Conditional variance
result = plot_relationship(x, y, moment="variance")

# Conditional correlation between y and z given x
result = plot_relationship(x, y, z=z, moment="correlation")
```

### Plot from DataFrames with `Plotter`

```python
from kernelmoments import Plotter

p = Plotter(df, n_sample=5000)  # optional subsampling for faster fitting
p.fit(x="age", y="income", z="spending")  # pre-fit all moments

p.plot(x="age", y="income")                              # conditional mean
p.plot(x="age", y="income", moment="variance")            # conditional variance
p.plot(x="age", y="income", z="spending", moment="correlation")  # conditional correlation
```

### Estimators directly

```python
from kernelmoments import MeanEstimator, VarianceEstimator, CovarianceEstimator

mean_est = MeanEstimator().fit(X, y)
y_hat = mean_est.predict(X_new)

var_est = VarianceEstimator().fit(X, y)
var_hat = var_est.predict(X_new)

cov_est = CovarianceEstimator().fit(X, y, z)
cov_hat = cov_est.predict(X_new)
cov_est.fit_correlation()
corr_hat = cov_est.predict_correlation(X_new)
```

All estimators follow the scikit-learn `fit` / `predict` pattern. Constructor parameters (bandwidth bounds, kernel type, tree depth, etc.) are forwarded to `KernelTree`.

## License

MIT
