README.md

---
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