simpute 0.1.0__py3-none-any.whl

simpute/__init__.py

@@ -0,0 +1,5 @@
+from simpute.core import Simpute
+from simpute.utils import ColumnProfile
+
+__version__ = "0.1.0"
+__all__ = ["Simpute", "ColumnProfile", "__version__"]

simpute/core.py

@@ -0,0 +1,291 @@
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from sklearn.base import BaseEstimator, TransformerMixin
+
+from simpute.models import buildmodel, pickmodel
+from simpute.utils import (
+    ColumnProfile,
+    decodecolumn,
+    expandfeatures,
+    featurecolumns,
+    isnumerical,
+    profilecolumn,
+    profiledataframe,
+    selectfeatures,
+)
+
+
+class Simpute(BaseEstimator, TransformerMixin):
+  """Adaptive per-column imputer with automatic model selection."""
+
+  def __init__(
+    self,
+    columns: list[str] | None = None,
+    exclude: list[str] | None = None,
+    maskratio: float = 0.0,
+    randomstate: int = 42,
+  ) -> None:
+    self.columns = columns
+    self.exclude = exclude or []
+    self.maskratio = maskratio
+    self.randomstate = randomstate
+    self.profiles_: dict[str, ColumnProfile] = {}
+    self.models_: dict[str, Any] = {}
+    self.featuremaps_: dict[str, list[str]] = {}
+    self.dummycolumns_: dict[str, dict[str, list[str]]] = {}
+    self.targetencodings_: dict[str, dict[object, int]] = {}
+    self.featurefills_: dict[str, dict[str, float | str | bool]] = {}
+    self.fallbacks_: dict[str, float | object] = {}
+    self.booltargets_: set[str] = set()
+    self.fittedcolumns_: list[str] = []
+
+  def _targets(self, df: pd.DataFrame) -> list[str]:
+    if self.columns is not None :
+      return [column for column in self.columns if column in df.columns]
+    return [column for column in df.columns if column not in self.exclude]
+
+  def _columnorder(self, df: pd.DataFrame, columns: list[str]) -> list[str]:
+    return sorted(
+      columns,
+      key = lambda column : (
+        0 if self.profiles_.get(column) and self.profiles_[column].kind == "numerical" else 1,
+        int(df[column].isna().sum()),
+        column,
+      ),
+    )
+
+  def _preparefeatures(self, df: pd.DataFrame, target: str, features: list[str]) -> pd.DataFrame:
+    dummymap = self.dummycolumns_.get(target)
+    expanded, learned = expandfeatures(df[features], features, dummymap)
+    if target not in self.dummycolumns_ :
+      self.dummycolumns_[target] = learned
+    return expanded.astype(float)
+
+  def _preparetarget(self, series: pd.Series, target: str) -> pd.Series:
+    if isnumerical(series) :
+      return series.astype(float)
+    labels = sorted(series.dropna().unique(), key = lambda value : str(value))
+    mapping = {label : index for index, label in enumerate(labels)}
+    self.targetencodings_[target] = mapping
+    return series.map(mapping).astype(float)
+
+  def _fallbackvalue(self, series: pd.Series) -> float | object:
+    observed = series.dropna()
+    if observed.empty :
+      return np.nan
+    if isnumerical(series) :
+      return float(observed.median())
+    modes = observed.mode()
+    return modes.iloc[0] if not modes.empty else observed.iloc[0]
+
+  def _nativemissing(self, modelname: str) -> bool:
+    return modelname in {"LGBMRegressor", "LGBMClassifier", "CatBoostClassifier"}
+
+  def _featurefills(self, df: pd.DataFrame, features: list[str]) -> dict[str, float | str | bool]:
+    fills: dict[str, float | str | bool] = {}
+    for feature in features :
+      series = df[feature]
+      if isnumerical(series) :
+        fills[feature] = float(series.dropna().median())
+        continue
+      mode = series.dropna().mode()
+      fills[feature] = mode.iloc[0] if not mode.empty else series.dropna().iloc[0]
+    return fills
+
+  def _resetcolumn(self, target: str) -> None:
+    self.models_.pop(target, None)
+    self.featuremaps_.pop(target, None)
+    self.dummycolumns_.pop(target, None)
+    self.targetencodings_.pop(target, None)
+    self.featurefills_.pop(target, None)
+    self.fallbacks_.pop(target, None)
+    self.booltargets_.discard(target)
+
+  def _fitcolumn(self, data: pd.DataFrame, target: str) -> bool:
+    self._resetcolumn(target)
+    profile = self.profiles_.get(target) or profilecolumn(target, data[target])
+    self.profiles_[target] = profile
+    if profile.missingnessflag == "high_missing" and data[target].isna().all() :
+      return False
+    features = selectfeatures(data, target, self.exclude, topk = 6)
+    if not features :
+      return False
+    observed = data[target].notna()
+    if observed.sum() < 2 :
+      return False
+
+    trainframe = data.loc[observed].copy()
+    fills = self._featurefills(trainframe, features)
+    selectionframe = trainframe.copy()
+    for feature, fill in fills.items() :
+      selectionframe[feature] = selectionframe[feature].fillna(fill)
+
+    xselect = self._preparefeatures(selectionframe, target, features).fillna(0.0)
+    ytrain = self._preparetarget(trainframe[target], target)
+    valid = xselect.notna().all(axis = 1) & ytrain.notna()
+    xselect = xselect.loc[valid]
+    ytrain = ytrain.loc[valid]
+    if len(xselect) < 2 :
+      return False
+
+    modelname = pickmodel(profile, xselect.values, ytrain.values, data[target])
+    usenative = self._nativemissing(modelname)
+
+    if usenative :
+      xtrain = self._preparefeatures(trainframe.loc[ytrain.index], target, features)
+    else :
+      filled = trainframe.loc[ytrain.index, features + [target]].copy()
+      for feature, fill in fills.items() :
+        filled[feature] = filled[feature].fillna(fill)
+      xtrain = self._preparefeatures(filled, target, features).fillna(0.0)
+      complete = xtrain.notna().all(axis = 1)
+      xtrain = xtrain.loc[complete]
+      ytrain = ytrain.loc[complete.index[complete]]
+
+    if len(xtrain) > 15000 :
+      keep = np.random.default_rng(self.randomstate).choice(len(xtrain), 15000, replace = False)
+      xtrain = xtrain.iloc[keep]
+      ytrain = ytrain.iloc[keep]
+
+    if len(xtrain) < 2 :
+      return False
+
+    self.profiles_[target] = ColumnProfile(
+      profile.name,
+      profile.kind,
+      profile.missingratio,
+      profile.cardinality,
+      profile.distributionshape,
+      profile.missingnessflag,
+      modelname,
+    )
+    model = buildmodel(modelname, self.profiles_[target], len(xtrain), xtrain.shape[1])
+    model.fit(xtrain.values, ytrain.values)
+    self.models_[target] = model
+    self.featuremaps_[target] = features
+    self.featurefills_[target] = fills
+    self.fallbacks_[target] = self._fallbackvalue(data[target])
+    if not hasattr(self, "usenative_") :
+      self.usenative_ = {}
+    self.usenative_[target] = usenative
+    if pd.api.types.is_bool_dtype(data[target]) :
+      self.booltargets_.add(target)
+    return True
+
+  def _predictvalues(self, model: Any, xpred: pd.DataFrame) -> np.ndarray:
+    preds = np.asarray(model.predict(xpred.values))
+    return preds.ravel()
+
+  def _imputecolumn(self, result: pd.DataFrame, target: str) -> None:
+    if target not in self.models_ :
+      missing = result[target].isna()
+      if missing.any() :
+        result.loc[missing, target] = self._fallbackvalue(result[target])
+      return
+
+    missing = result[target].isna()
+    if not missing.any() :
+      return
+
+    features = self.featuremaps_[target]
+    block = result.loc[missing, features].copy()
+    usenative = getattr(self, "usenative_", {}).get(target, False)
+    if not usenative :
+      for feature, fill in self.featurefills_[target].items() :
+        block[feature] = block[feature].fillna(fill)
+
+    xpred = self._preparefeatures(block, target, features)
+    if not usenative :
+      xpred = xpred.fillna(0.0)
+
+    preds = self._predictvalues(self.models_[target], xpred)
+    profile = self.profiles_[target]
+    if profile.kind == "categorical" :
+      decoded = decodecolumn(pd.Series(preds), self.targetencodings_[target])
+      if target in self.booltargets_ :
+        result.loc[missing, target] = decoded.astype(bool).values
+      else :
+        result.loc[missing, target] = decoded.values
+    else :
+      if profile.cardinality <= 20 :
+        preds = np.round(preds)
+      result.loc[missing, target] = np.asarray(preds, dtype = float)
+
+    stillmissing = result[target].isna()
+    if stillmissing.any() :
+      result.loc[stillmissing, target] = self.fallbacks_[target]
+
+  def fit(self, df: pd.DataFrame, y: Any = None) -> Simpute:
+    del y
+    data = df.copy()
+    targets = self._targets(data)
+    self.profiles_ = profiledataframe(data, targets)
+    self.models_.clear()
+    self.featuremaps_.clear()
+    self.dummycolumns_.clear()
+    self.targetencodings_.clear()
+    self.featurefills_.clear()
+    self.fallbacks_.clear()
+    self.booltargets_.clear()
+
+    order = self._columnorder(data, targets)
+    for target in order :
+      self._fitcolumn(data, target)
+
+    self.fittedcolumns_ = list(self.models_.keys())
+    return self
+
+  def transform(self, df: pd.DataFrame) -> pd.DataFrame:
+    if not self.models_ :
+      raise RuntimeError("Simpute is not fitted. Call fit before transform.")
+    result = df.copy()
+    order = self._columnorder(result, self.fittedcolumns_)
+    for _ in range(3) :
+      before = result.isna().sum().sum()
+      for target in order :
+        self._imputecolumn(result, target)
+      if result.isna().sum().sum() == before :
+        break
+    for column in self._targets(result) :
+      if column not in self.models_ and result[column].isna().any() :
+        result[column] = result[column].fillna(self._fallbackvalue(df[column]))
+    return result
+
+  def fit_transform(self, df: pd.DataFrame, y: Any = None) -> pd.DataFrame:
+    del y
+    data = df.copy()
+    targets = self._targets(data)
+    self.profiles_ = profiledataframe(data, targets)
+    self.models_.clear()
+    self.featuremaps_.clear()
+    self.dummycolumns_.clear()
+    self.targetencodings_.clear()
+    self.featurefills_.clear()
+    self.fallbacks_.clear()
+    self.booltargets_.clear()
+
+    result = data.copy()
+    order = self._columnorder(result, targets)
+    for target in order :
+      if result[target].isna().sum() == 0 :
+        continue
+      self._fitcolumn(result, target)
+      self._imputecolumn(result, target)
+
+    self.fittedcolumns_ = list(self.models_.keys())
+    return result
+
+  def getprofiles(self) -> dict[str, ColumnProfile]:
+    return copy.deepcopy(self.profiles_)
+
+  def getmodelselection(self) -> dict[str, str]:
+    return {
+      target : profile.modelname
+      for target, profile in self.profiles_.items()
+      if profile.modelname is not None
+    }

simpute/models.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from catboost import CatBoostClassifier
+from lightgbm import LGBMClassifier as LGBMC, LGBMRegressor as LGBMR
+from sklearn.ensemble import ExtraTreesRegressor
+from sklearn.linear_model import BayesianRidge, LogisticRegression
+from sklearn.neighbors import KNeighborsRegressor
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+from sklearn.svm import LinearSVC
+
+from simpute.utils import ColumnProfile, isdiscrete, ishighcardinality
+
+
+def _lgbmparams(nrows: int) -> dict[str, Any]:
+  leaves = min(63, max(15, int(np.sqrt(nrows))))
+  estimators = min(150, max(50, nrows // 150))
+  return {
+    "n_estimators" : estimators,
+    "num_leaves" : leaves,
+    "learning_rate" : 0.05,
+    "random_state" : 42,
+    "verbosity" : -1,
+    "n_jobs" : -1,
+  }
+
+
+def candidates(profile: ColumnProfile, nrows: int, series: Any = None) -> list[str]:
+  if profile.kind == "categorical" :
+    if ishighcardinality(profile.cardinality) :
+      return ["CatBoostClassifier", "LGBMClassifier"]
+    if profile.cardinality <= 2 :
+      return ["LogisticRegression"]
+    return ["LogisticRegression", "LinearSVC"]
+  discrete = series is not None and isdiscrete(series, profile.cardinality)
+  if nrows >= 1000 :
+    return ["LGBMRegressor", "ExtraTreesRegressor"]
+  if discrete or profile.distributionshape == "skewed" :
+    return ["LGBMRegressor", "ExtraTreesRegressor"]
+  return ["KNNRegressor", "BayesianRidge"]
+
+
+def selectmodel(profile: ColumnProfile, nrows: int, series: Any = None) -> str:
+  return candidates(profile, nrows, series)[0]
+
+
+def buildmodel(modelname: str, profile: ColumnProfile, nrows: int, nfeatures: int) -> Any:
+  if modelname == "LGBMClassifier" :
+    return LGBMC(**_lgbmparams(nrows))
+  if modelname == "CatBoostClassifier" :
+    return CatBoostClassifier(
+      iterations = min(300, max(100, nrows // 50)),
+      depth = min(8, max(4, int(np.log2(nrows + 1)))),
+      learning_rate = 0.05,
+      random_seed = 42,
+      verbose = False,
+      thread_count = -1,
+    )
+  if modelname == "LogisticRegression" :
+    return Pipeline([
+      ("scaler", StandardScaler()),
+      ("model", LogisticRegression(
+        max_iter = 2000,
+        C = 1.0,
+        class_weight = "balanced",
+        random_state = 42,
+      )),
+    ])
+  if modelname == "LinearSVC" :
+    return Pipeline([
+      ("scaler", StandardScaler()),
+      ("model", LinearSVC(max_iter = 3000, class_weight = "balanced", random_state = 42)),
+    ])
+  if modelname == "LGBMRegressor" :
+    return LGBMR(**_lgbmparams(nrows))
+  if modelname == "ExtraTreesRegressor" :
+    return ExtraTreesRegressor(
+      n_estimators = min(300, max(100, nrows // 50)),
+      max_features = "sqrt",
+      random_state = 42,
+      n_jobs = -1,
+    )
+  if modelname == "KNNRegressor" :
+    neighbors = min(50, max(5, int(np.sqrt(nrows))))
+    return Pipeline([
+      ("scaler", StandardScaler()),
+      ("model", KNeighborsRegressor(n_neighbors = neighbors, weights = "distance", n_jobs = -1)),
+    ])
+  if modelname == "BayesianRidge" :
+    return Pipeline([
+      ("scaler", StandardScaler()),
+      ("model", BayesianRidge()),
+    ])
+  raise ValueError(f"Unsupported model: {modelname}")
+
+
+def pickmodel(
+  profile: ColumnProfile,
+  xtrain: np.ndarray,
+  ytrain: np.ndarray,
+  series: Any = None,
+) -> str:
+  options = candidates(profile, len(ytrain), series)
+  if len(options) == 1 :
+    return options[0]
+  if profile.kind == "numerical" and len(ytrain) >= 1000 :
+    return "LGBMRegressor" if "LGBMRegressor" in options else options[0]
+  if profile.kind == "categorical" and len(ytrain) >= 1000 and "CatBoostClassifier" in options :
+    return "CatBoostClassifier"
+  if profile.kind == "categorical" and len(ytrain) >= 1000 :
+    return options[0]
+  return options[0]

simpute/utils.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+
+ColumnKind = Literal["numerical", "categorical"]
+DistributionShape = Literal["skewed", "normal_uniform"]
+MissingnessFlag = Literal["ok", "high_missing"]
+
+HIGH_MISSING_THRESHOLD = 0.70
+HIGH_CARDINALITY_THRESHOLD = 10
+SKEW_THRESHOLD = 1.0
+
+
+@dataclass(frozen = True)
+class ColumnProfile:
+    name: str
+    kind: ColumnKind
+    missingratio: float
+    cardinality: int
+    distributionshape: DistributionShape | None
+    missingnessflag: MissingnessFlag
+    modelname: str | None = None
+
+
+def isnumerical(series: pd.Series) -> bool:
+  dtype = series.dtype
+  return pd.api.types.is_numeric_dtype(dtype) and not pd.api.types.is_bool_dtype(dtype)
+
+
+def iscategorical(series: pd.Series) -> bool:
+  return pd.api.types.is_bool_dtype(series) or pd.api.types.is_object_dtype(series) or pd.api.types.is_categorical_dtype(series)
+
+
+def missingratio(series: pd.Series) -> float:
+  return float(series.isna().mean())
+
+
+def cardinality(series: pd.Series) -> int:
+  return int(series.dropna().nunique())
+
+
+def distributionshape(series: pd.Series) -> DistributionShape:
+  values = series.dropna().astype(float)
+  if len(values) < 8 :
+    return "normal_uniform"
+  skew = float(stats.skew(values))
+  if abs(skew) >= SKEW_THRESHOLD :
+    return "skewed"
+  return "normal_uniform"
+
+
+def ishighcardinality(card: int) -> bool:
+  return card > HIGH_CARDINALITY_THRESHOLD
+
+
+def isdiscrete(series: pd.Series, card: int) -> bool:
+  if not isnumerical(series) :
+    return False
+  if card > 20 :
+    return False
+  if pd.api.types.is_integer_dtype(series) :
+    return True
+  values = series.dropna().astype(float)
+  return bool(np.allclose(values, np.round(values)))
+
+
+def profilecolumn(name: str, series: pd.Series) -> ColumnProfile:
+  ratio = missingratio(series)
+  flag: MissingnessFlag = "high_missing" if ratio > HIGH_MISSING_THRESHOLD else "ok"
+  if flag == "high_missing" :
+    warnings.warn(
+      f"Column '{name}' has {ratio:.1%} missing values (> {HIGH_MISSING_THRESHOLD:.0%}). "
+      "Imputation reliability may be limited.",
+      stacklevel = 2,
+    )
+  if isnumerical(series) :
+    card = cardinality(series)
+    shape = distributionshape(series)
+    return ColumnProfile(name, "numerical", ratio, card, shape, flag)
+  return ColumnProfile(
+    name,
+    "categorical",
+    ratio,
+    cardinality(series),
+    None,
+    flag,
+  )
+
+
+def profiledataframe(df: pd.DataFrame, columns: list[str] | None = None) -> dict[str, ColumnProfile]:
+  targets = columns if columns is not None else list(df.columns)
+  return {column : profilecolumn(column, df[column]) for column in targets if column in df.columns}
+
+
+def featurecolumns(df: pd.DataFrame, target: str, exclude: list[str] | None = None) -> list[str]:
+  blocked = {target, *(exclude or [])}
+  return [column for column in df.columns if column not in blocked]
+
+
+def selectfeatures(
+  df: pd.DataFrame,
+  target: str,
+  exclude: list[str] | None = None,
+  topk: int = 6,
+) -> list[str]:
+  from sklearn.feature_selection import mutual_info_classif, mutual_info_regression
+
+  features = featurecolumns(df, target, exclude)
+  if len(features) <= topk :
+    return features
+  observed = df[target].notna() & df[features].notna().all(axis = 1)
+  if observed.sum() < 20 :
+    return features
+  xframe = df.loc[observed, features].copy()
+  yseries = df.loc[observed, target]
+  if len(xframe) > 8000 :
+    xframe = xframe.sample(8000, random_state = 42)
+    yseries = yseries.loc[xframe.index]
+  xnum = pd.DataFrame({
+    column : (
+      xframe[column].astype(float)
+      if isnumerical(xframe[column])
+      else pd.Categorical(xframe[column]).codes
+    )
+    for column in features
+  })
+  if isnumerical(yseries) :
+    scores = mutual_info_regression(xnum, yseries.astype(float), random_state = 42)
+  else :
+    scores = mutual_info_classif(xnum, yseries.astype(str), random_state = 42)
+  ranked = sorted(zip(features, scores), key = lambda item : item[1], reverse = True)
+  return [column for column, score in ranked[:topk] if score > 0] or [column for column, _ in ranked[:topk]]
+
+
+def expandfeatures(
+  df: pd.DataFrame,
+  columns: list[str],
+  dummycolumns: dict[str, list[str]] | None = None,
+) -> tuple[pd.DataFrame, dict[str, list[str]]]:
+  parts: list[pd.DataFrame] = []
+  dummymap: dict[str, list[str]] = {}
+  for column in columns :
+    if column not in df.columns :
+      continue
+    if isnumerical(df[column]) :
+      parts.append(df[[column]].astype(float).rename(columns = {column : column}))
+      continue
+    dummies = pd.get_dummies(df[column].astype(str), prefix = column, dtype = float)
+    if dummycolumns and column in dummycolumns :
+      for name in dummycolumns[column] :
+        if name not in dummies.columns :
+          dummies[name] = 0.0
+      dummies = dummies[dummycolumns[column]]
+    else :
+      dummymap[column] = list(dummies.columns)
+    parts.append(dummies)
+  if not parts :
+    return pd.DataFrame(index = df.index), dummymap
+  return pd.concat(parts, axis = 1), dummymap
+
+
+def encodeframe(df: pd.DataFrame, columns: list[str]) -> tuple[pd.DataFrame, dict[str, dict[object, int]]]:
+  encoded = df.copy()
+  maps: dict[str, dict[object, int]] = {}
+  for column in columns :
+    if column not in encoded.columns :
+      continue
+    series = encoded[column]
+    if isnumerical(series) :
+      encoded[column] = series.astype(float)
+      continue
+    labels = sorted(series.dropna().unique(), key = lambda value : str(value))
+    mapping = {label : index for index, label in enumerate(labels)}
+    maps[column] = mapping
+    encoded[column] = series.map(mapping)
+  return encoded, maps
+
+
+def decodecolumn(series: pd.Series, mapping: dict[object, int]) -> pd.Series:
+  inverse = {code : label for label, code in mapping.items()}
+  return series.map(inverse)

simpute-0.1.0.dist-info/METADATA

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: simpute
+Version: 0.1.0
+Summary: Smart Impute: adaptive per-column missing value imputation
+Author: Hvllvix
+Maintainer: Hvllvix
+License: MIT
+Project-URL: Homepage, https://github.com/Hvllvix/Simpute
+Project-URL: Repository, https://github.com/Hvllvix/Simpute
+Project-URL: Documentation, https://github.com/Hvllvix/Simpute#readme
+Project-URL: Bug Tracker, https://github.com/Hvllvix/Simpute/issues
+Keywords: imputation,missing-data,machine-learning,sklearn,simpute
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: scipy>=1.10
+Requires-Dist: lightgbm>=4.0
+Requires-Dist: catboost>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: matplotlib>=3.7; extra == "dev"
+Requires-Dist: seaborn>=0.13; extra == "dev"
+Dynamic: license-file
+
+# Simple Imputation
+
+**Simpute** (**sim**ple + im**pute**) is an adaptive missing-value imputation library for tabular data. Instead of applying one global strategy to every column, it profiles each feature, selects a tailored model, and imputes columns sequentially so earlier fills inform later ones.
+
+Install from PyPI as `simpute`. Source and releases live at [github.com/Hvllvix/Simpute](https://github.com/Hvllvix/Simpute).
+
+---
+
+## Why Simpute
+
+Most imputers pick a single method (mean, median, MICE, KNN) for the whole table. Real datasets mix binary flags, low-cardinality categories, high-cardinality text-like fields, skewed counts, and smooth continuous variables. Simpute treats each column on its own terms.
+
+| Approach | Simpute |
+|----------|---------|
+| Strategy | Per-column profiling and model routing |
+| API | Scikit-learn `fit` / `transform` / `fit_transform` |
+| Models | LightGBM, CatBoost, logistic/SVM, KNN, Bayesian Ridge, Extra Trees |
+| Safety | Guard test suite with ground-truth verification |
+| Warnings | Flags columns above 70% missingness |
+
+---
+
+## Installation
+
+```bash
+pip install simpute
+```
+
+Development install with tests and plotting extras:
+
+```bash
+git clone https://github.com/Hvllvix/Simpute.git
+cd Simpute
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+```python
+import pandas as pd
+from simpute import Simpute
+
+df = pd.read_csv("data.csv")
+
+imputer = Simpute(exclude=["Student_ID"])
+filled = imputer.fit_transform(df)
+
+print(imputer.getmodelselection())
+print(imputer.getprofiles())
+```
+
+`exclude` keeps identifier columns out of the imputation loop. Use `columns=[...]` instead when you only want to impute a subset.
+
+---
+
+## How It Works
+
+1. **Profile** each target column (type, missingness, cardinality, distribution shape).
+2. **Select features** with mutual information (top 6 predictors by default).
+3. **Route** to a candidate model based on the column profile.
+4. **Fit** on observed rows, then **impute** missing cells column by column.
+5. **Warn** when missingness exceeds 70% on a column.
+
+Sequential imputation means numerical columns are generally filled before categorical ones, and values imputed in earlier columns become features for later columns.
+
+---
+
+## Model Selection
+
+| Column profile | Candidate models |
+|----------------|------------------|
+| High-cardinality categorical | CatBoost Classifier, LightGBM Classifier |
+| Low-cardinality / binary categorical | Logistic Regression, Linear SVC |
+| Large numerical tables (1000+ rows) | LightGBM Regressor, Extra Trees Regressor |
+| Skewed or discrete numerical | LightGBM Regressor, Extra Trees Regressor |
+| Normal / uniform continuous | KNN Regressor, Bayesian Ridge |
+
+Inspect the chosen backend per column after fitting:
+
+```python
+imputer.getmodelselection()
+# {'Pre_Semester_GPA': 'LGBMRegressor', 'Major_Category': 'CatBoostClassifier', ...}
+```
+
+---
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `fit(df)` | Profile columns, train per-column models |
+| `transform(df)` | Impute using fitted models |
+| `fit_transform(df)` | Fit and impute in one pass (recommended) |
+| `getprofiles()` | Column profiles used during routing |
+| `getmodelselection()` | Model name chosen for each imputed column |
+
+Constructor options: `columns`, `exclude`, `maskratio`, `randomstate`.
+
+---
+
+## Guard Tests
+
+The guard suite (`tests/guard.py`) masks values in [`tests/data/test.csv`](tests/data/test.csv), imputes them, and checks:
+
+- No NaN values remain after imputation
+- Categorical predictions stay within the original domain
+- Numerical predictions stay within bounded ranges
+- Imputation beats adaptive random baselines on held-out masked cells
+- Model selection is deterministic and profile-consistent
+- High-missingness columns emit warnings
+- `transform` before `fit` raises `RuntimeError`
+
+See [`tests/data/README.md`](tests/data/README.md) for column descriptions and how to swap in your own CSV.
+
+```bash
+pytest tests/guard.py -v
+```
+
+Metric summary table (MAE for continuous columns, accuracy for nominal):
+
+```bash
+python tests/guard.py
+```
+
+---
+
+## Validation Plots
+
+Generated on the bundled test dataset (`MASKRATIO=0.15`, `SEED=42`):
+
+| Plot | Description |
+|------|-------------|
+| [Imputation density](Assets/Plots/imputation_density.png) | KDE of observed vs post-imputation continuous distributions |
+| [Missingness heatmap](Assets/Plots/missingness_heatmap.png) | Feature completeness before and after imputation |
+| [Model allocation](Assets/Plots/model_allocation_grid.png) | Which backend was assigned per column |
+
+<p align="center">
+  <img src="Assets/Plots/imputation_density.png" alt="Imputation density comparison" width="800"/>
+</p>
+
+<p align="center">
+  <img src="Assets/Plots/missingness_heatmap.png" alt="Missingness heatmap before and after imputation" width="800"/>
+</p>
+
+<p align="center">
+  <img src="Assets/Plots/model_allocation_grid.png" alt="Per-column model allocation" width="800"/>
+</p>
+
+Regenerate locally:
+
+```bash
+python scripts/generate_plots.py
+```
+
+---
+
+## Requirements
+
+- Python 3.10+
+- NumPy, Pandas, SciPy, scikit-learn, LightGBM, CatBoost
+
+---
+
+## Contributing
+
+1. Fork [Hvllvix/Simpute](https://github.com/Hvllvix/Simpute)
+2. Create a branch, make changes, run `pytest tests/guard.py -v`
+3. Open a pull request
+
+---
+
+## License
+
+MIT

simpute-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+simpute/__init__.py,sha256=jMhOCHHC-RivknFBBhkIvvgjYudlFldEjRkx4y0DC4A,150
+simpute/core.py,sha256=1M6qIC0Deiuy_ebJiCaIuv0O74QqjEr6Nf-GIrF18T8,10197
+simpute/models.py,sha256=pisRcmsgGFkYhsWLex7y02CPQYMlhLcQUB19mfVSRUQ,3837
+simpute/utils.py,sha256=3aXb64FxVtQEEyN7aps_YHvVA6Vk66qg2XhMJHCE7Dk,5905
+simpute-0.1.0.dist-info/licenses/LICENSE,sha256=OF0agoaZ50g--hQij9dCPB4Tk5SEJmhxW5KxxmrbPVI,1077
+simpute-0.1.0.dist-info/METADATA,sha256=r3Yfxxf8R0XSVez-XP5rB4_IYtcVdT0irCCl3Ly0RvY,6820
+simpute-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+simpute-0.1.0.dist-info/top_level.txt,sha256=mpxS5gq56wil9Hki9UAPOjascgCeAJ9Jb9uAoxCBilg,8
+simpute-0.1.0.dist-info/RECORD,,

simpute-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

simpute-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simpute Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simpute-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+simpute