Update README.md

README.md

@@ -1,60 +1,82 @@
+---
 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
+---
 
-en
-library_name: smartknn
-tasks:
 
-tabular-classification
+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.
 
-tabular-regression
-metrics:
 
-r_squared
+# Model Details
 
-mse
 
-accuracy
+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.
 
-mae
-tags:
+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)
 
-knn
+Model Sources
+Repository: https://github.com/thatipamula-jashwanth/smart-knn  
+Paper (DOI): https://doi.org/10.5281/zenodo.17713746  
+Demo: Coming soon
 
-weighted-knn
 
-smartknn
+# Uses
 
-machine-learning
 
-regression
+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
 
-classification
+Downstream Use
+• Research on distance-metric learning  
+• Explainable ML baselines  
+• AutoML components for tabular data
 
-tabular-data
+Out-of-Scope Use
+• NLP, image or audio modelling  
+• Deep learning / GPU models  
+• Raw categorical datasets without encoding
 
-explainable-ai
 
-metric-learning
+# Bias, Risks, and Limitations
 
-distance-based-learning
+• 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
 
-nearest-neighbors
+Recommendations
+Users should numerically encode categorical features before fitting SmartKNN.
 
-python
 
-data-science
+# How to Get Started with the Model
 
-SmartKNN — Weighted & Interpretable K-Nearest Neighbours for Tabular ML
 
 pip install smart-knn
 
-SmartKNN is a smarter, weighted, feature-selective variant of KNN built for modern tabular machine learning.
-It learns per-feature importance automatically, filters weak and noisy dimensions, handles missing values, normalizes numerical data internally, and consistently delivers higher accuracy than classical KNN — while preserving a simple scikit-learn style API.
-It supports both regression and classification, requires no manual preprocessing, and integrates seamlessly with NumPy and Pandas.
-
-Quickstart
-
 import pandas as pd
 from smart_knn import SmartKNN
 
@@ -67,64 +89,81 @@ model.fit(X, y)
 
 sample = X.iloc[0]
 pred = model.predict(sample)
-print("Prediction:", pred)
+print(pred)
 
-SmartKNN automatically:
 
-• Normalizes inputs
-• Cleans NaN / Inf values
-• Learns feature weights
-• Filters weak features
-• Computes weighted distances
-• Selects the most meaningful neighbours
+# Training Details
 
-Features
 
-• Learns feature importance (MSE + MI + Random Forest)
-• Filters weak & noisy features automatically
-• Handles missing values (median imputation + NaN/Inf cleaning)
-• Performs robust outlier clipping
-• Normalizes data internally
-• Uses weighted Euclidean distance
-• Exposes global feature importance
-• Works for both regression & classification
+Training Data
+SmartKNN is not pretrained and does not ship with training data; users train on their own dataset.
 
-Evaluation Results
+Preprocessing
+Performed automatically:
+• Normalization
+• NaN / Inf cleaning
+• Median imputation
+• Outlier clipping
+• Feature filtering via learned weights
 
-Across 35 regression and 20 classification tabular datasets:
+Training Hyperparameters
+• k = number of neighbors  
+• weight_threshold = drop features below learned importance
 
-• Regression: SmartKNN outperformed classical KNN on 90%+ datasets
-• Classification: SmartKNN beat classical KNN on 60% of datasets
 
-SmartKNN delivers higher accuracy, stronger robustness, and better interpretability while preserving the simplicity of classical KNN.
+# Evaluation
+Testing Data
+Evaluated across 35 regression and 20 classification public tabular datasets.
 
-If you want KNN-level simplicity with real-world reliability, SmartKNN is built for you.
+# Metrics
+Regression: R², MSE  
+Classification: Accuracy
 
-Useful Links
+# Results
+• Regression: SmartKNN outperformed classical KNN on 90%+ datasets  
+• Classification: SmartKNN beat classical KNN on 60% of datasets  
 
-PyPI → https://pypi.org/project/smart-knn
+# Summary
+SmartKNN delivers higher accuracy, greater robustness to noise, and better interpretability than classical KNN while preserving its simplicity.
 
-GitHub → https://github.com/thatipamula-jashwanth/smart-knn
 
-Medium Article → https://medium.com/@thatipamulajashwanthgoud/a-new-smarter-take-on-knn-where-feature-weighting-noise-resilience-and-interpretability-meet-5fc284892669
+# Environmental Impact
 
-DOI → https://doi.org/10.5281/zenodo.17713746
 
-Citation
+SmartKNN requires no GPU and has minimal energy usage.
+Hardware Type: CPU  
+Hours used: Minimal  
+Carbon Emitted: Negligible
 
-If you use SmartKNN in academic or scientific work, please cite:
+# Technical Specifications
 
-@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 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}
 }
 
-License
 
-SmartKNN is released under the MIT License.
-See the LICENSE file in this repository for full legal text.
+# Model Card Authors
+
+Jashwanth Thatipamula
+
+Model Card Contact
+Contact via GitHub issues: https://github.com/thatipamula-jashwanth/smart-knn