Metadata-Version: 2.4
Name: imputekit
Version: 0.1.0
Summary: Fill missing values using group-wise statistics instead of one flat column average.
Author-email: YOUR NAME HERE <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/YOUR_USERNAME/imputekit
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3
Dynamic: license-file

# GroupImputer

![Tests](https://github.com/karlyn14/imputekit/actions/workflows/tests.yml/badge.svg)

Fill missing values using the average of **similar rows**, instead of one flat
value for the entire column.

Standard `pandas.fillna(mean)` fills every missing value with the same
number — even if a "Sales" salary and a "Tech" salary have nothing in common.
`GroupImputer` fills each missing value using the average for its own group
(e.g. its department), with a safe fallback when a group has no data at all.

## Installation

```
pip install imputekit
```

## Quick Start

```python
import pandas as pd
from imputekit import GroupImputer

df = pd.DataFrame({
    "Department": ["Sales", "Sales", "Sales", "Tech", "Tech", "Tech"],
    "Salary":     [60000,   45000,   None,    50000,  90000,  None],
})

filler = GroupImputer(group_by="Department", target="Salary")
df_filled = filler.fit_transform(df)

print(df_filled)
print(filler.report())
```

Output:

```
Imputation Report
-----------------
Target column          : Salary
Grouped by              : Department
Statistic used          : mean
Missing values filled   : 2
  filled by group avg   : 2
  filled by fallback    : 0
Already present values  : 4
```

## How It Works

1. `fit()` groups the data by the column(s) you specify and computes the
   mean, median, or mode of the target column for each group.
2. `transform()` fills each missing value using its group's statistic.
3. If a group has **no** valid data at all, it falls back to the overall
   column statistic instead of leaving the value empty.
4. `report()` tells you exactly how many values were filled, and by which
   method — so nothing happens silently.

## API

```python
GroupImputer(group_by, target, strategy="mean")
```

- `group_by`: a column name, or list of column names, to group by
- `target`: the column containing missing values to fill
- `strategy`: `"mean"`, `"median"`, or `"mode"`

Methods: `.fit(df)`, `.transform(df)`, `.fit_transform(df)`, `.report()`

## Why not just use `df.groupby(...).transform(...)`?

You can! For a single quick fix, plain pandas is fine. `GroupImputer` is
useful when you want the fallback safety net, multiple group columns,
and a clear report of what was filled and how — without rewriting that
logic every time.

## License

MIT
