| --- |
| license: mit |
| language: |
| - en |
| metrics: |
| - r_squared |
| - accuracy |
| - mae |
| - mse |
| - f1 |
| - recall |
| tags: |
| - machine-learning |
| - algorithms |
| - tabular-data |
| - knn |
| - python |
| - weighted-knn |
| - data-science |
| - preprocessing |
| --- |
| |
|
|
| SmartKNN is a weighted and interpretable extension of classical K-Nearest Neighbours (KNN), designed for real-world tabular machine learning. It automatically learns feature importance, filters weak features, handles missing values, normalizes inputs internally, and consistently achieves higher accuracy and robustness than classical KNN — while maintaining a simple scikit-learn-style API. |
|
|
|
|
| # Model Details |
|
|
|
|
| Model Description |
| SmartKNN improves classical KNN by learning feature weights and applying a weighted Euclidean distance for neighbour selection. It performs normalization, NaN/Inf cleaning, median imputation, outlier clipping, and feature filtering internally. It exposes feature importance for transparency and explainability. |
|
|
| Developed by: Jashwanth Thatipamula |
| Model type: Weighted KNN for tabular ML |
| License: MIT |
| Language(s): Not language-dependent (numerical tabular ML) |
| Finetuned from model: Not applicable (original algorithm) |
|
|
| Model Sources |
| Repository: https://github.com/thatipamula-jashwanth/smart-knn |
| Paper (DOI): https://doi.org/10.5281/zenodo.17713746 |
| Demo: Coming soon |
|
|
|
|
| # Uses |
|
|
|
|
| Direct Use |
| • Regression on tabular datasets |
| • Classification on tabular datasets |
| • Interpretable ML where feature importance matters |
| • Real-world ML pipelines with missing values and noisy features |
|
|
| Downstream Use |
| • Research on distance-metric learning |
| • Explainable ML baselines |
| • AutoML components for tabular data |
|
|
| Out-of-Scope Use |
| • NLP, image or audio modelling |
| • Deep learning / GPU models |
| • Raw categorical datasets without encoding |
|
|
|
|
| # Bias, Risks, and Limitations |
|
|
| • Instance-based prediction can be slower than tree-based models on large datasets |
| • Low performance on categorical-only datasets without encoding |
| • Requires storing full training set for inference |
|
|
| Recommendations |
| Users should numerically encode categorical features before fitting SmartKNN. |
|
|
|
|
| # How to Get Started with the Model |
|
|
|
|
| pip install smart-knn |
|
|
| import pandas as pd |
| from smart_knn import SmartKNN |
| |
| df = pd.read_csv("data.csv") |
| X = df.drop("target", axis=1) |
| y = df["target"] |
|
|
| model = SmartKNN(k=5) |
| model.fit(X, y) |
|
|
| sample = X.iloc[0] |
| pred = model.predict(sample) |
| print(pred) |
|
|
|
|
| # Training Details |
|
|
|
|
| Training Data |
| SmartKNN is not pretrained and does not ship with training data; users train on their own dataset. |
|
|
| Preprocessing |
| Performed automatically: |
| • Normalization |
| • NaN / Inf cleaning |
| • Median imputation |
| • Outlier clipping |
| • Feature filtering via learned weights |
|
|
| Training Hyperparameters |
| • k = number of neighbors |
| • weight_threshold = drop features below learned importance |
| |
| |
| # Evaluation |
| Testing Data |
| Evaluated across 35 regression and 20 classification public tabular datasets. |
| |
| # Metrics |
| Regression: R², MSE |
| Classification: Accuracy |
| |
| # Results |
| • Regression: SmartKNN outperformed classical KNN on 90%+ datasets |
| • Classification: SmartKNN beat classical KNN on 60% of datasets |
| |
| # Summary |
| SmartKNN delivers higher accuracy, greater robustness to noise, and better interpretability than classical KNN while preserving its simplicity. |
| |
| |
| # Environmental Impact |
| |
| |
| SmartKNN requires no GPU and has minimal energy usage. |
| Hardware Type: CPU |
| Hours used: Minimal |
| Carbon Emitted: Negligible |
| |
| # Technical Specifications |
| |
| |
| Model Architecture and Objective |
| • Instance-based learner |
| • Weighted Euclidean distance metric |
| • Learned feature weights (MSE + MI + Random Forest) |
| |
| Compute Infrastructure |
| • Runs efficiently on CPU systems |
| • Implemented using NumPy |
| |
| |
| # Citation |
| |
| |
| @software{smartknn2025, |
| author = {Jashwanth Thatipamula}, |
| title = {SmartKNN: An Interpretable Weighted Distance Framework for K-Nearest Neighbours}, |
| year = {2025}, |
| publisher = {Zenodo}, |
| doi = {10.5281/zenodo.17713746}, |
| url = {https://doi.org/10.5281/zenodo.17713746} |
| } |
| |
| |
| # Model Card Authors |
| |
| Jashwanth Thatipamula |
| |
| Model Card Contact |
| Contact via GitHub issues: https://github.com/thatipamula-jashwanth/smart-knn |
