Initial upload (auto-create if missing)

README.md

@@ -0,0 +1,290 @@
+---
+language: "en"
+license: "apache-2.0"
+created: "2025-12-30T05:32:51.193018Z"
+tags:
+  - "bot-detection"
+  - "instagram"
+  - "classification"
+---
+
+# INSTAGRAM Bot Detection Model
+
+## Overview
+
+This directory contains a trained Random Forest classifier for detecting bot accounts on Instagram.
+
+**Model Version:** v2
+**Training Date:** 2025-12-30 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.9788 (97.88%) |
+| **Precision**         | 0.9923 (99.23%) |
+| **Recall**            | 0.9652 (96.52%) |
+| **F1-Score**          | 0.9786 (97.86%) |
+| **ROC-AUC**           | 0.9979 (99.79%) |
+| **Average Precision** | 0.9923 (99.23%) |
+
+### Model Improvement
+
+- **Baseline ROC-AUC:** 0.9982
+- **Tuned ROC-AUC:** 0.9979
+
+---
+
+## 🗂️ 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.3500     | Indicates if account has a profile picture |
+| 2    | `followers`                  | 0.2587     | Number of followers                        |
+| 3    | `username_num_ratio`         | 0.2029     | Ratio of numbers in username               |
+| 4    | `follows`                    | 0.0997     | Ratio of followers to following count      |
+| 5    | `fullname_words`             | 0.0345     | 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.9979
+- **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.9979
+  - Accuracy: 97.88%
+  - 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.

instagram_bot_detection_model.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:29fbc4e428d4c5984d733bc494054af84f45ca600ec801e8eb05089faa3ad34d
+size 1676089

instagram_features.json

@@ -0,0 +1,12 @@
+[
+  "profile_pic",
+  "username_num_ratio",
+  "username_is_numeric",
+  "fullname_words",
+  "fullname_num_ratio",
+  "is_name_number_only",
+  "name_equals_username",
+  "followers",
+  "follows",
+  "followers_to_follows_ratio"
+]

instagram_features.txt

@@ -0,0 +1,10 @@
+profile_pic
+username_num_ratio
+username_is_numeric
+fullname_words
+fullname_num_ratio
+is_name_number_only
+name_equals_username
+followers
+follows
+followers_to_follows_ratio

instagram_metrics.txt

@@ -0,0 +1,23 @@
+Model: Instagram Bot Detection
+Date: 2025-12-29 22:02:58.371023
+
+============================================================
+Performance Metrics
+============================================================
+
+Accuracy: 0.9788
+Precision: 0.9923
+Recall: 0.9652
+F1: 0.9786
+Roc_auc: 0.9979
+Avg_precision: 0.9982
+
+Best Parameters:
+  class_weight: balanced
+  max_depth: 30
+  max_features: sqrt
+  min_samples_leaf: 1
+  min_samples_split: 2
+  n_estimators: 100
+
+Cross-Validation ROC-AUC: 0.9984 (+/- 0.0013)

instagram_model_comparison.csv

@@ -0,0 +1,7 @@
+Metric,Baseline,Tuned,Improvement,Improvement %
+Accuracy,0.986,0.986,0.0,0.0
+Precision,0.9917525773195877,0.9917525773195877,0.0,0.0
+Recall,0.9796334012219959,0.9796334012219959,0.0,0.0
+F1-Score,0.985655737704918,0.985655737704918,0.0,0.0
+ROC-AUC,0.998803612370408,0.9989916733021498,0.00018806093174172922,0.018828619501626963
+Avg Precision,0.9988880328453673,0.9990380665868485,0.00015003374148114812,0.015020075979263841

instagram_scaler.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cde4b5fa22e39296618b8401fd2a3d47f474b2b20051dbdaa2d8c03bf618b197
+size 1591

requirements.txt

@@ -0,0 +1,4 @@
+scikit-learn>=1.3.0
+pandas>=2.0.0
+numpy>=1.24.0
+joblib>=1.3.0