Duplicate from JashuXo/smart-knn

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,169 @@
+---
+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