Metadata-Version: 2.4
Name: faiss-imputer
Version: 0.2.0
Summary: K-nearest-neighbor imputation backed by Faiss
Author: Hakkil Kim
License-Expression: MIT
Project-URL: Repository, https://github.com/ScionKim/FaissImputer
Project-URL: Issues, https://github.com/ScionKim/FaissImputer/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: faiss-cpu>=1.7.4
Requires-Dist: scikit-learn>=1.6
Provides-Extra: test
Requires-Dist: build>=1.2; extra == "test"
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: examples
Requires-Dist: jupyterlab>=4; extra == "examples"
Requires-Dist: pandas>=2; extra == "examples"
Dynamic: license-file

# FaissImputer
[!WARNING]
Maintenance notice: FaissImputer 0.1.x has a known neighbor-mapping bug that can produce incorrect imputations, and it is incompatible with scikit-learn 1.8+. Please do not use it in production. A corrected v0.2.0 is in progress.

[![PyPI Version](https://img.shields.io/pypi/v/faiss-imputer.svg)](https://pypi.org/project/faiss-imputer/)
[![License](https://img.shields.io/pypi/l/faiss-imputer.svg)](https://github.com/ScionKim/FaissImputer/blob/main/LICENSE)

Impute missing values using Meta's [faiss](https://github.com/facebookresearch/faiss) - A Python library for missing data imputation with k nearest neighbors.

## Installation

You can install `faiss-imputer` using `pip`:

```bash
pip install faiss-imputer
```

## Usage

```python
import numpy as np

from faiss_imputer import FaissImputer

# Complete rows used as reference donors
X_train = np.array(
    [
        [1.0, 10.0, 100.0],
        [2.0, 20.0, 200.0],
        [3.0, 30.0, 300.0],
    ],
    dtype=np.float32,
)

# New rows containing missing values
X_missing = np.array(
    [
        [1.5, np.nan, 150.0],
        [2.5, 25.0, np.nan],
    ],
    dtype=np.float32,
)

imputer = FaissImputer(n_neighbors=2)
imputer.fit(X_train)

X_imputed = imputer.transform(X_missing)
print(X_imputed)
```

`transform()` returns a NumPy `float32` array. The input array is not modified.

## Parameters

- `n_neighbors`: Number of reference rows used to calculate each missing value.
- `metric`: Neighbor-search metric. Supported values are `"l2"` and `"ip"`. Raw inner product is not cosine similarity.
- `strategy`: Aggregation method for neighbor values. Supported values are `"mean"` and `"median"`.
- `index_factory`: Faiss index description. The default `"Flat"` performs exact search.

## Important behavior

- `fit()` currently uses only rows without any missing values as reference donors.
- Neighbor search compares only the columns observed in each query row.
- `n_neighbors` cannot exceed the number of complete reference rows.
- An entirely missing row is filled using statistics learned during `fit()`.
- Input data must be a two-dimensional numeric array with the same number of columns used during `fit()`.

## Example notebook

See [Imputing Missing Values with Faiss Imputer](notebooks/Impute_Missing_Values_with_Faiss_Imputer.ipynb) for a notebook example.

## Contributing

Contributions are welcome! If you find a bug or have an enhancement suggestion, please open an issue or create a pull request.

## Author

![Profile Photo](https://avatars.githubusercontent.com/u/93073728?v=4&size=100)

- **Name:** Hakkil Kim
- **GitHub Profile:** [GitHub Profile Link](https://github.com/ScionKim/)

## License

This project is licensed under the [MIT License](LICENSE).

### Third-Party Licenses

FaissImputer depends on Meta's [Faiss](https://github.com/facebookresearch/faiss), which is distributed under the [MIT License](https://github.com/facebookresearch/faiss/blob/main/LICENSE).

FaissImputer is not affiliated with or endorsed by Meta or the Faiss maintainers.

For detailed licensing information of the Faiss library, please refer to the [Faiss repository](https://github.com/facebookresearch/faiss).
