Metadata-Version: 2.4
Name: imputation-methods
Version: 0.2.0
Summary: A unified pandas API for 40+ missing-data imputation methods: statistical, time-series, regression, ensemble and matrix-completion.
License-Expression: MIT
License-File: LICENSE
Keywords: imputation,missing-data,missing-values,data-cleaning,data-preprocessing,pandas,scikit-learn,time-series,statistics,machine-learning
Author: Diogo Ribeiro
Author-email: dfr@esmad.ipp.pt
Maintainer: Diogo Ribeiro
Maintainer-email: dfr@esmad.ipp.pt
Requires-Python: >=3.10
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Provides-Extra: viz
Requires-Dist: matplotlib (>=3.7) ; extra == "viz"
Requires-Dist: numpy (>=1.24)
Requires-Dist: pandas (>=2.0)
Requires-Dist: scikit-learn (>=1.4)
Requires-Dist: scipy (>=1.10)
Requires-Dist: seaborn (>=0.13) ; extra == "viz"
Project-URL: Changelog, https://github.com/DiogoRibeiro7/imputation-methods/blob/main/CHANGELOG.md
Project-URL: Documentation, https://diogoribeiro7.github.io/imputation-methods/
Project-URL: Homepage, https://github.com/DiogoRibeiro7/imputation-methods
Project-URL: Issues, https://github.com/DiogoRibeiro7/imputation-methods/issues
Project-URL: Repository, https://github.com/DiogoRibeiro7/imputation-methods
Description-Content-Type: text/markdown

# imputation-methods

[![PyPI](https://img.shields.io/pypi/v/imputation-methods)](https://pypi.org/project/imputation-methods/)
[![Python versions](https://img.shields.io/pypi/pyversions/imputation-methods)](https://pypi.org/project/imputation-methods/)
[![CI](https://github.com/DiogoRibeiro7/imputation-methods/actions/workflows/ci.yml/badge.svg)](https://github.com/DiogoRibeiro7/imputation-methods/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/DiogoRibeiro7/imputation-methods/blob/main/LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

**42 missing-data imputation methods behind one pandas API.** Swap mean imputation
for KNN, MICE, a Kalman filter or low-rank matrix completion by changing one line,
and compare them with the same evaluation code.

```python
from imputation_methods import KNNImputer

completed = KNNImputer(n_neighbors=5).impute(df)
```

- **One interface.** Every imputer takes a numeric `DataFrame` and returns a new one
  with the same index and columns. The input is never modified.
- **Broad coverage.** Statistical, donor-based, time-series, nearest-neighbor,
  regression, iterative, matrix-completion, neural and ensemble methods.
- **Light dependencies.** NumPy, pandas, SciPy and scikit-learn only.
- **Typed and tested.** Inline type hints checked by mypy in strict mode, and tests
  on Python 3.10–3.14, on the newest and the oldest supported dependency versions.

## Installation

```bash
pip install imputation-methods
```

The optional `viz` extra installs matplotlib and seaborn, used by the example
notebooks and scripts:

```bash
pip install "imputation-methods[viz]"
```

Requires Python 3.10 or newer.

## Quick start

```python
import numpy as np
import pandas as pd

from imputation_methods import KNNImputer, MeanImputer, knn_impute

df = pd.DataFrame(
    {
        "height": [170.0, 165.0, np.nan, 180.0, 175.0],
        "weight": [65.0, np.nan, 70.0, 85.0, 78.0],
        "age": [30.0, 25.0, 35.0, np.nan, 40.0],
    }
)

mean_filled = MeanImputer().impute(df)
knn_filled = KNNImputer(n_neighbors=2).impute(df)

# Every imputer also has a functional shortcut.
same_as_knn = knn_impute(df, n_neighbors=2)
```

Imputers are configured in the constructor. Those with a random component accept
`random_state` for reproducible results.

## Available methods

| Family | Imputers |
| --- | --- |
| Statistical | `MeanImputer`, `MedianImputer`, `ModeImputer`, `ConstantImputer`, `QuantileImputer`, `TrimmedMeanImputer`, `EndOfDistributionImputer`, `GroupMeanImputer`, `IndicatorImputer` |
| Donor sampling | `RandomSamplingImputer`, `HotDeckImputer`, `ColdDeckImputer` |
| Time series | `LOCFImputer`, `NOCBImputer`, `ForwardFillFallbackImputer`, `InterpolationImputer`, `MovingAverageImputer`, `WeightedMovingAverageImputer`, `LinearTrendImputer`, `PolynomialTrendImputer`, `SeasonalImputer`, `KalmanFilterImputer` |
| Nearest neighbors | `KNNImputer`, `RadiusNeighborsImputer`, `LocalMeanImputer` |
| Regression | `RegressionImputer`, `StochasticRegressionImputer`, `PMMImputer` (predictive mean matching), `BayesianRidgeImputer`, `HuberImputer`, `RANSACImputer`, `GaussianProcessImputer` |
| Iterative | `MICEImputer`, `MissForestImputer`, `EMImputer` |
| Matrix completion | `SoftImputeImputer`, `PPCAImputer` (probabilistic PCA) |
| Neural networks | `AutoencoderImputer`, `GAINImputer` (generative adversarial imputation) |
| Ensembles | `HybridImputer` (fallback chain), `StackingImputer`, `BaggingImputer` (bootstrap aggregating) |

`EMImputer` runs iterative chained-equation imputation rather than closed-form EM
for a multivariate normal distribution.

The [API reference](https://diogoribeiro7.github.io/imputation-methods/api/) documents
every class and its parameters.

## Evaluating an imputation

When you have complete data, hide some values, impute them, and score only the
cells you hid:

```python
import numpy as np
import pandas as pd
from sklearn.datasets import load_diabetes

from imputation_methods import KNNImputer, MeanImputer, MICEImputer, mae, rmse

complete = load_diabetes(as_frame=True).data
rng = np.random.default_rng(0)
mask = rng.random(complete.shape) < 0.2
incomplete = complete.mask(mask)

imputers = {
    "mean": MeanImputer(),
    "knn": KNNImputer(n_neighbors=5),
    "mice": MICEImputer(random_state=0),
}
for name, imputer in imputers.items():
    completed = imputer.impute(incomplete)
    true = pd.Series(complete.to_numpy()[mask])
    pred = pd.Series(completed.to_numpy()[mask])
    print(f"{name:>5}: RMSE={rmse(true, pred):.4f}  MAE={mae(true, pred):.4f}")
```

## Input requirements

- A `pandas.DataFrame` with numeric columns, including pandas nullable dtypes such
  as `Int64`; missing values as `NaN` or `pd.NA`. Encode categorical columns before imputing. `GroupMeanImputer`
  is the exception: its grouping column may be non-numeric.
- Time-series imputers use row order, so sort the data first.
- Columns without missing values are returned unchanged. Imputed columns are
  floating point: `float32`/`float64` keep their precision and nullable columns
  become `Float64`.
- Columns with no observed values are left as `NaN`, except by imputers that fill
  in a constant you choose, such as `ConstantImputer`.

## Documentation

Full documentation, including guides on choosing a method and evaluating results:
<https://diogoribeiro7.github.io/imputation-methods/>

The [roadmap](https://github.com/DiogoRibeiro7/imputation-methods/blob/main/ROADMAP.md)
describes what is planned before 1.0.

The repository also has [example scripts](https://github.com/DiogoRibeiro7/imputation-methods/tree/main/examples)
and [Jupyter notebooks](https://github.com/DiogoRibeiro7/imputation-methods/tree/main/notebooks).

## Contributing

Contributions are welcome. See the
[contributing guide](https://github.com/DiogoRibeiro7/imputation-methods/blob/main/CONTRIBUTING.md)
for the development setup, and the
[code of conduct](https://github.com/DiogoRibeiro7/imputation-methods/blob/main/CODE_OF_CONDUCT.md).
Report security issues as described in the
[security policy](https://github.com/DiogoRibeiro7/imputation-methods/blob/main/SECURITY.md).

## Citation

If you use this library in research, please cite it. Citation metadata is in
[`CITATION.cff`](https://github.com/DiogoRibeiro7/imputation-methods/blob/main/CITATION.cff);
GitHub's "Cite this repository" button exports it as BibTeX or APA.

## License

MIT. See [LICENSE](https://github.com/DiogoRibeiro7/imputation-methods/blob/main/LICENSE).

