non-param-score-est 1.0.0
Non parametric score function estimation library
License: MIT

# Non-parametric score estimation

Welcome to the `non_param_score_est` Python package ([GitHub repository](https://github.com/krunolp/non_param_score_est), [PyPi library](https://pypi.org/project/non-param-score-est/)).

## Usage

### Initial setup

To install the package, you are required to have a Python 3.10 or newer environment. Then, simply run:

 ```
pip install non_param_score_est
 ```

### Choosing the estimator

The following estimators are available (and the corresponding import names):


| Estimator                         | Import Name                   |
|-----------------------------------|:------------------------------|
| Tikhonov regularization           | Tikhonov                      |
| NKEF (with rate 0.75)             | Tikhonov(subsample_rate=0.75) |
| Kernel density estimator          | KDE                           |
| Landweber iteration               | Landweber                     |
| Nu-method                         | NuMethod                      |
| Spectral Stein gradient estimator | SSGE                          |
| Stein estimator                   | Stein                         |

### Utilising the estimators

To use the estimators in your code, simply import the estimator and call the `estimate_gradients_x_s` or `estimate_gradients_s` function. For example, to utilise the Tikhonov estimator, you would write:
 ```python
import numpy as np
from non_param_score_est.estimators import Tikhonov

samples = np.random.normal(1000)
est = Tikhonov(bandwidth=1., lam=1e-4)

#estimate the gradients of the generated samples
score_estimate = est.estimate_gradients_s(samples=samples)

#estimate the gradients of new query while fitting the score estimator to previously generated samples
new_query = np.random.normal(100)
new_estimate = est.estimate_gradients_s_x(queries=new_query, samples=samples)

 ```

### Working with the estimators
A great way to further investigate how the estimators work is to check the [plots.py](non_param_score_est/tests/plots.py) file. It contains a script that generates plots of the estimators on a simple 1D and 2D examples. The plots are generated by running the following command:
```python
from non_param_score_est.estimators import Tikhonov
from non_param_score_est.tests.plots import plotOneDim, plotTwoDim

# selecting Tikhonov regularization
est = Tikhonov(bandwidth=10., lam=1e-5)

# One-dimensional Gaussian distribution experiment
plotOneDim(estimator=est)

# Two-dimensional Gaussian distribution experiment
plotTwoDim(estimator=est)
```
These generate the following outputs:



| One-dimensional experiment                                                      | Two-dimensional experiment                                                      |
|---------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| ![One-dimensional experiment](non_param_score_est/tests/plot_outputs/plot1.png) | ![Two-dimensional experiment](non_param_score_est/tests/plot_outputs/plot2.png) |
## Contributing

We welcome contributions! Please follow these guidelines if you'd like to contribute to the project:

1. Fork our GitHub repository and clone it to your local machine.
2. Create a new branch for your feature or bug fix.
3. Make your changes and ensure that tests pass.
4. Submit a pull request with a clear title and description.

## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments
The code in [JAX](https://github.com/google/jax) was inspired by the [repository](https://github.com/miskcoo/kscore.git) of the [Nonparametric Score Estimators](https://arxiv.org/abs/2005.10099) paper, by Yuhao Zhou, Jiaxin Shi, Jun Zhu. 

## Contact
Krunoslav Lehman Pavasovic
Email: krunolp@gmail.com
GitHub: krunolp