Upload folder using huggingface_hub

README.md

@@ -8,8 +8,284 @@ tags:
   - "classification"
 ---
 
-# nahiar/instagram-bot-detection
+# INSTAGRAM Bot Detection Model
 
-A short description of this model.
+## Overview
 
--- Add details for: how to use, training data, limitations, citation, and license.
+This directory contains a trained Random Forest classifier for detecting bot accounts on Instagram.
+
+**Model Version:** v2
+**Training Date:** 2025-11-27 11:38:28
+**Framework:** scikit-learn 1.5.2
+**Algorithm:** Random Forest Classifier with GridSearchCV Hyperparameter Tuning
+
+---
+
+## 📊 Model Performance
+
+### Final Metrics (Test Set)
+
+| Metric                | Score           |
+| --------------------- | --------------- |
+| **Accuracy**          | 0.9860 (98.60%) |
+| **Precision**         | 0.9918 (99.18%) |
+| **Recall**            | 0.9796 (97.96%) |
+| **F1-Score**          | 0.9857 (98.57%) |
+| **ROC-AUC**           | 0.9990 (99.90%) |
+| **Average Precision** | 0.9990 (99.90%) |
+
+### Model Improvement
+
+- **Baseline ROC-AUC:** 0.9988
+- **Tuned ROC-AUC:** 0.9990
+- **Improvement:** 0.0002 (0.02%)
+
+---
+
+## 🗂️ Files
+
+| File                             | Description                            |
+| -------------------------------- | -------------------------------------- |
+| `instagram_bot_detection_v2.pkl` | Trained Random Forest model            |
+| `instagram_scaler_v2.pkl`        | MinMaxScaler for feature normalization |
+| `instagram_features_v2.json`     | List of features used by the model     |
+| `instagram_metrics_v2.txt`       | Detailed performance metrics report    |
+| `images/`                        | All visualization plots (13 images)    |
+| `README.md`                      | This file                              |
+
+---
+
+## 🎯 Dataset Information
+
+### Training Configuration
+
+- **Training Samples:** 4,000
+- **Test Samples:** 1,000
+- **Total Samples:** 5,000
+- **Features:** 10
+- **Cross-Validation Folds:** 5
+- **Random State:** 42
+
+### Class Distribution
+
+The model was trained with balanced class weights to handle any class imbalance in the dataset.
+
+---
+
+## 🔧 Model Architecture
+
+### Algorithm
+
+**Random Forest Classifier** - An ensemble learning method that operates by constructing multiple decision trees during training and outputting the class that is the mode of the classes (classification) of the individual trees.
+
+### Hyperparameters (Tuned via GridSearchCV)
+
+| Parameter           | Value    |
+| ------------------- | -------- |
+| `n_estimators`      | 100      |
+| `max_depth`         | 15       |
+| `min_samples_split` | 2        |
+| `min_samples_leaf`  | 1        |
+| `max_features`      | sqrt     |
+| `class_weight`      | balanced |
+
+### Feature Preprocessing
+
+- **Scaler:** MinMaxScaler (normalizes features to [0, 1] range)
+- **Missing Values:** Handled during data preprocessing
+- **Feature Engineering:** Custom features derived from account metadata
+
+---
+
+## 📈 Feature Importance
+
+The model uses 10 features to detect bot accounts. Top 5 most important features:
+
+| Rank | Feature                      | Importance | Description                                |
+| ---- | ---------------------------- | ---------- | ------------------------------------------ |
+| 1    | `profile_pic`                | 0.3314     | Indicates if account has a profile picture |
+| 2    | `followers`                  | 0.2313     | Number of followers                        |
+| 3    | `username_num_ratio`         | 0.1665     | Ratio of numbers in username               |
+| 4    | `followers_to_follows_ratio` | 0.1308     | Ratio of followers to following count      |
+| 5    | `follows`                    | 0.0923     | Number of accounts followed                |
+
+### All Features
+
+1. `profile_pic` - Profile picture presence
+2. `username_num_ratio` - Numeric character ratio in username
+3. `username_is_numeric` - Username is entirely numeric
+4. `fullname_words` - Number of words in full name
+5. `fullname_num_ratio` - Numeric character ratio in full name
+6. `is_name_number_only` - Full name contains only numbers
+7. `name_equals_username` - Full name matches username
+8. `followers` - Follower count
+9. `follows` - Following count
+10. `followers_to_follows_ratio` - Follower/following ratio
+
+---
+
+## 🚀 Usage
+
+### Prerequisites
+
+```bash
+pip install scikit-learn joblib numpy
+```
+
+### Loading the Model
+
+```python
+import joblib
+import numpy as np
+
+# Load model and scaler
+model = joblib.load('instagram_bot_detection_v2.pkl')
+scaler = joblib.load('instagram_scaler_v2.pkl')
+
+# Example prediction
+features = np.array([[
+    1,      # profile_pic
+    0.15,   # username_num_ratio
+    0,      # username_is_numeric
+    2,      # fullname_words
+    0.0,    # fullname_num_ratio
+    0,      # is_name_number_only
+    0,      # name_equals_username
+    1200,   # followers
+    300,    # follows
+    4.0     # followers_to_follows_ratio
+]])
+
+# Scale features
+features_scaled = scaler.transform(features)
+
+# Make prediction
+prediction = model.predict(features_scaled)
+probability = model.predict_proba(features_scaled)
+
+print(f"Bot: {prediction[0] == 1}")
+print(f"Probability: {probability[0][1]:.4f}")
+```
+
+### API Integration
+
+```python
+def predict_instagram_bot(account_data: dict) -> dict:
+    """
+    Predict if an Instagram account is a bot.
+
+    Args:
+        account_data: Dictionary with account features
+
+    Returns:
+        Dictionary with prediction and probability
+    """
+    features = np.array([[
+        account_data['profile_pic'],
+        account_data['username_num_ratio'],
+        account_data['username_is_numeric'],
+        account_data['fullname_words'],
+        account_data['fullname_num_ratio'],
+        account_data['is_name_number_only'],
+        account_data['name_equals_username'],
+        account_data['followers'],
+        account_data['follows'],
+        account_data['followers_to_follows_ratio']
+    ]])
+
+    features_scaled = scaler.transform(features)
+    prediction = model.predict(features_scaled)[0]
+    probability = model.predict_proba(features_scaled)[0]
+
+    return {
+        'is_bot': bool(prediction),
+        'bot_probability': float(probability[1]),
+        'confidence': float(max(probability))
+    }
+```
+
+---
+
+## 📊 Visualization
+
+The `images/` directory contains 13 visualization plots:
+
+1. **confusion_matrix.png** - Classification confusion matrix
+2. **roc_curve.png** - ROC curve with AUC score
+3. **precision_recall_curve.png** - Precision-recall trade-off
+4. **feature_importance.png** - Feature importance ranking
+5. **learning_curve.png** - Model learning curve
+6. **class_distribution.png** - Training data class distribution
+7. **prediction_distribution.png** - Prediction score distribution
+8. **calibration_curve.png** - Probability calibration
+9. **cv_scores.png** - Cross-validation scores
+10. **top_features.png** - Top 10 features
+11. **correlation_matrix.png** - Feature correlation heatmap
+12. **threshold_analysis.png** - Classification threshold analysis
+13. **model_comparison.png** - Baseline vs tuned model comparison
+
+---
+
+## 🎓 Model Training
+
+### Training Process
+
+1. **Data Preprocessing**: Feature engineering and normalization
+2. **Train-Test Split**: 80/20 split with stratification
+3. **Hyperparameter Tuning**: GridSearchCV with 5-fold cross-validation
+4. **Model Selection**: Best parameters based on ROC-AUC score
+5. **Evaluation**: Comprehensive metrics on held-out test set
+
+### Cross-Validation
+
+- **Mean ROC-AUC:** 0.9988
+- **Folds:** 5
+- **Strategy:** Stratified K-Fold
+
+---
+
+## ⚠️ Limitations
+
+1. **Data Dependency**: Model performance depends on feature quality and data accuracy
+2. **Feature Availability**: All 10 features must be available for prediction
+3. **Temporal Drift**: Instagram's platform and bot behavior may change over time
+4. **Privacy**: Ensure compliance with Instagram's terms of service when collecting data
+5. **Threshold Sensitivity**: Default threshold is 0.5; may need adjustment based on use case
+
+---
+
+## 📝 License
+
+This model is released under the **Apache License 2.0**.
+
+---
+
+## 🔄 Version History
+
+- **v2** (2025-11-27): Current version with hyperparameter tuning
+  - ROC-AUC: 0.9990
+  - Accuracy: 98.60%
+  - 10 features
+
+---
+
+## 📧 Contact & Citation
+
+If you use this model in your research or application, please cite:
+
+```bibtex
+@misc{instagram-bot-detection-v2,
+  title={Instagram Bot Detection Model v2},
+  author={Nahiar},
+  year={2025},
+  month={November},
+  publisher={Hugging Face},
+  howpublished={\url{https://huggingface.co/nahiar/instagram-bot-detection}}
+}
+```
+
+---
+
+## 🤝 Contributing
+
+For issues, improvements, or questions, please contact the model maintainer.