This project is a Python application for missing-value imputation and for reproducing the experiments from the publication kNNSampler: Stochastic Imputations for Recovering Missing Value Distributions. It's a joint work by SAP SE and Eurecom with funding support from the ANRT.
knnSampler is a kNN-based method for missing-value imputation with support for multiple imputation and uncertainty quantification. It aims to preserve the underlying data distribution when imputing missing values (see the publication for more details).
If you use knnSampler, please cite the original publication:
@article{pashmchi2025knnsampler,
title={k{NNS}ampler: Stochastic Imputations for Recovering Missing Value Distributions},
author={Parastoo PASHMCHI and J{\'e}r{\^o}me Benoit and Motonobu Kanagawa},
journal={Transactions on Machine Learning Research},
issn={2835-8856},
year={2025},
url={https://openreview.net/forum?id=4CDnIACCQG},
note={}
}This project requires Python 3.12+ and Poetry 2+.
- Clone the repository
git clone <repository_url>- Navigate to the project directory
cd <repository_directory>- Install dependencies
poetry install --no-rootThe project uses a self-documenting configuration file assets/config.conf.
poetry run task mainRuns the main imputation pipeline using assets/config.conf.
For reproducible seeded KnnSampler runs, set the dataset random_state and
[execution] execution_random_state in
assets/config.conf. The dataset seed controls data
preparation and missing-value selection; the execution seed controls sampling
for imputers that honor it. Each do_imputation(..., iterations=N) iteration
receives an independent derived seed, while task main runs one execution per
imputer. Leave the execution seed blank to run unseeded. KNNxKDEImputer uses
global randomness internally and is not fully reproducible.
KnnSampler's K-fold selection uses optimal_k_random_state (default 42,
integer in [0, 4294967295]; None is Python-API-only) in the [KnnSampler]
section of assets/hyperparameters.conf. The
scaler is fitted on each training fold; loo_penalized keeps global scaling
on all complete-case rows. It uses the fast leave-one-out computation of
Kanagawa (2024) (arXiv:2405.04919) with an additional (k+1)^2/k^2 penalty
that penalizes small k. The kNNSampler paper uses plain LOOCV without this
extra penalty. The value is validated for every method, but only
kfold uses it.
For Python use, load settings with assets.config.load_config(). Legacy
module-level overrides remain supported. A complete set of required fields
avoids configuration-file I/O; optional fields use their defaults unless set
explicitly. When both configuration files are absent, partial overrides also
use optional defaults; required fields still raise. A present but incomplete
file set still reports the configuration error.
Note: the benchmarking scripts do not have dedicated configuration files. To change benchmark settings, edit the top of benchmark_all.py and benchmark_knnsampler.py.
For comparing imputation algorithms with each other.
A fixed benchmark seed reproduces the prepared datasets. Stochastic imputations, permutation tests and execution times may still vary.
poetry run task benchmark_allFor detailed knnSampler results with different parameter ranges.
poetry run task benchmark_knnsamplerThis project is open to feature requests and bug reports via GitHub issues. Contributions and feedback are welcome. See CONTRIBUTING.md for details.
poetry install --no-root --with devpoetry run task formatpoetry run task lintpoetry run task testpoetry run task typecheckpoetry run pre-commit installIf you find a bug that may pose a security issue, follow our security policy instructions to report it. Do not open GitHub issues for security reports.
By participating in this project, you agree to follow our Code of Conduct.
Copyright 2025 SAP SE or an SAP affiliate company and knnSampler contributors. See LICENSE for details. Detailed third-party licensing information is available via the REUSE tool.