FaissImputer
Fast KNN imputation with control over which rows can help.
A nearby row is useful only if it contains the value you need. FaissImputer lets you choose between complete donors and partially observed donors, with a familiar scikit-learn interface.
Examples · API reference · Benchmarks
Why FaissImputer?
- Choose donors to suit your data. Use fully observed training rows, or draw from partially observed rows separately for each missing feature. Complete-donor filtering is an additional policy that KNNImputer does not expose.
- Get more search options. Complete-donor mode supports native inner-product search and trainable or approximate Faiss indexes, alongside the default Flat index.
- Account for numerical edge cases. Distance search and aggregation include targeted precision and overflow safeguards, backed by regression tests. Their scope and limits are documented in the API reference.
See the benchmark conditions, results, and trade-offs.
Installation
Install with Python 3.10 or newer:
python -m pip install faiss-imputer
Quick start
Fit on your training data, then fill the gaps in new rows:
import numpy as np
from faiss_imputer import FaissImputer
train = np.array([[0, 10], [2, 20], [4, 40]], dtype=np.float32)
query = np.array([[1.8, np.nan]], dtype=np.float32)
imputer = FaissImputer(n_neighbors=1)
result = imputer.fit(train).transform(query)
print(result)
# [[ 1.8 20. ]]
Work with NumPy arrays or pandas DataFrames, use scikit-learn pipelines, and retain feature names and optional missing-value indicators. See more examples.
Choose which rows can help
A nearby row can fill a missing value only if it contains that value. FaissImputer gives you two ways to choose those donors:
| Policy | Which rows contribute? |
|---|---|
complete — default |
Training rows observed in every non-empty feature. At least n_neighbors eligible complete rows are required when non-empty features exist. |
available |
Partially observed rows can contribute to the features they contain. With built-in L2 metrics, they must also share an observed feature with the query. |
For incomplete training data, start with available donors:
imputer = FaissImputer(n_neighbors=5, donor_policy="available")
Available mode requires index_factory="Flat", permits fewer than
n_neighbors usable donors, and falls back to a fitted column statistic
when no donor is usable. Changing the policy changes the donor pool and
can change reconstruction quality.
You can also choose mean or median aggregation, configure weights, or provide a custom distance function. The API reference explains the supported combinations, precision safeguards, and edge cases.
Performance
Published 0.3.21: a separate-query comparison
2.76–2.77× the first-transform speed of KNNImputer on one available-donor workload. These measurements are from the published FaissImputer 0.3.21 package.
The workload used 20,000 training rows, 300 held-out queries, 20 features, five neighbors, and uniform-weight mean aggregation. Training data had 10% MCAR missingness; each query had four missing features. Measurements used one native thread on an AMD EPYC 7763 runner.
First-transform times in milliseconds, excluding fit:
| Input | KNNImputer 1.9.1 | FaissImputer 0.3.21 | Paired speedup |
|---|---|---|---|
| float32 | 274.60 [272.58–282.91] | 100.39 [97.96–104.07] | 2.77× |
| float64 | 332.68 [320.05–341.91] | 119.33 [117.30–126.13] | 2.76× |
Times are median [min–max] across three seeds and three fresh workers per seed, with a small untimed warmup. Speedups are medians of the nine matched KNNImputer/FaissImputer timing ratios, not ratios of the displayed medians.
Fitting took longer than KNNImputer. Fit plus first transform was 2.49× as fast for both dtypes, while whole-worker peak RSS was slightly higher. Performance depends on the workload: available mode was slower than KNNImputer on Wine Quality for both tested dtypes and on Abalone for float64 in the real-data study linked below.
Full comparison and methodology · Raw measurements · Unrounded summary
Explore other workloads
Each report identifies the version or source commit actually measured and links to its raw evidence and reproduction instructions.
| Study | What it covers |
|---|---|
Scaling and missingness · 9683d03 |
A 12-run same-data sweep across rows, features, missingness, and neighbors. APIs and dtypes are reported separately. |
Wine Quality and Abalone · ef04b1b |
Held-out real-data comparisons covering speed, memory, reconstruction error, and donor counts. |
Float64 refinement · c02b71d |
A source-build optimization comparison with matched timings and a separate same-code control. |
Similar RMSE or MAE values describe similar aggregate reconstruction error on the tested data. They do not establish identical predictions or algorithmic equivalence.
Is it a fit for your project?
Use FaissImputer when nearest-neighbor imputation suits your numerical data and you want control over donor eligibility, aggregation, or Faiss search options. Scale features appropriately before using distances.
FaissImputer is not a drop-in replacement for KNNImputer. Defaults,
search precision, ties, and some edge cases differ. For KNNImputer
comparisons, use donor_policy="available" and match the neighbor count,
weights, and missing markers.
KNNImputer remains a good choice when its behavior meets your needs and
FaissImputer offers no measured advantage for your workload.
Learn more
- Usage examples — partial donors, indicators, custom metrics, and pandas pipelines.
- API reference — parameters, numerical behavior, and memory considerations.
- Benchmark reports — measurements, limitations, and reproducible evidence.
- Migration notes — compatibility changes and historical correctness notes.
- Roadmap · Release history.
Contributing
Bug reports and focused pull requests are welcome. A small, reproducible example helps us understand unexpected behavior. Open an issue.
Created by ScionKim.
License
FaissImputer is released under the MIT License. Faiss is developed by Meta and distributed under the MIT License. FaissImputer is not affiliated with or endorsed by Meta or the Faiss maintainers.
Metadata
Release files for faiss-imputer 0.3.22
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| faiss_imputer-0.3.22.tar.gz | 73.6 kB | With provenance | Details for faiss_imputer-0.3.22.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| faiss_imputer-0.3.22-py3-none-any.whl | Python 3 | none | any | Details for faiss_imputer-0.3.22-py3-none-any.whl |
Total release size: 93.3 kB
Release files / faiss_imputer-0.3.22.tar.gz
| Download URL | faiss_imputer-0.3.22.tar.gz |
|---|---|
| Size | 73.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
923e101e2a9f923fb8bb67ec3cbef2a6e59eb1bdfa6aa6ababeac0da9c71f890
|
|
BLAKE2b-256 checksum How to use checksums |
bf27f0e2f5cb90121d8a2bb067fc606ceec87f1f32404b9a0a6a02e03f7744ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logRelease files / faiss_imputer-0.3.22-py3-none-any.whl
| Download URL | faiss_imputer-0.3.22-py3-none-any.whl |
|---|---|
| Size | 19.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3343bd281e08a27869dc917f5e1479767ce5574be91a8d0f61247bdc728f62c3
|
|
BLAKE2b-256 checksum How to use checksums |
5a3f1ad8e81bf3f3c71db3a313c04e9a0165729000a669dd874e1af0aeddd760
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logSecurity for faiss-imputer 0.3.22
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for faiss_imputer-0.3.22.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 1, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.