Skip to main content

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.

PyPI Python Tests

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.

Published FaissImputer 0.3.21 available-donor first-transform benchmark: float32 100.39 ms versus KNNImputer 274.60 ms, float64 119.33 ms versus 332.68 ms; median paired speedups 2.77x and 2.76x, excluding fit.

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

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)

Source distribution for faiss-imputer 0.3.22
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)

Table of built distributions (wheels) for faiss-imputer 0.3.22
File Interpreter ABI Platform Actions
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 log

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

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

Select from 2 files

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 log

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

Release history Release notifications | RSS feed

This release

0.3.22 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page