nahiar/instagram-bot-detection

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

Model Improvement

• —Baseline ROC-AUC: 0.9988
• —Tuned ROC-AUC: 0.9990
• —Improvement: 0.0002 (0.02%)

🗂️ Files

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

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:

All Features

1. 1.profile_pic - Profile picture presence
2. 2.username_num_ratio - Numeric character ratio in username
3. 3.username_is_numeric - Username is entirely numeric
4. 4.fullname_words - Number of words in full name
5. 5.fullname_num_ratio - Numeric character ratio in full name
6. 6.is_name_number_only - Full name contains only numbers
7. 7.name_equals_username - Full name matches username
8. 8.followers - Follower count
9. 9.follows - Following count
10. 10.followers_to_follows_ratio - Follower/following ratio

🚀 Usage

Prerequisites

pip install scikit-learn joblib numpy

Loading the Model

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

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. 1.confusion_matrix.png - Classification confusion matrix
2. 2.roc_curve.png - ROC curve with AUC score
3. 3.precision_recall_curve.png - Precision-recall trade-off
4. 4.feature_importance.png - Feature importance ranking
5. 5.learning_curve.png - Model learning curve
6. 6.class_distribution.png - Training data class distribution
7. 7.prediction_distribution.png - Prediction score distribution
8. 8.calibration_curve.png - Probability calibration
9. 9.cv_scores.png - Cross-validation scores
10. 10.top_features.png - Top 10 features
11. 11.correlation_matrix.png - Feature correlation heatmap
12. 12.threshold_analysis.png - Classification threshold analysis
13. 13.model_comparison.png - Baseline vs tuned model comparison

🎓 Model Training

Training Process

1. 1.Data Preprocessing: Feature engineering and normalization
2. 2.Train-Test Split: 80/20 split with stratification
3. 3.Hyperparameter Tuning: GridSearchCV with 5-fold cross-validation
4. 4.Model Selection: Best parameters based on ROC-AUC score
5. 5.Evaluation: Comprehensive metrics on held-out test set

Cross-Validation

• —Mean ROC-AUC: 0.9988
• —Folds: 5
• —Strategy: Stratified K-Fold

⚠️ Limitations

1. 1.Data Dependency: Model performance depends on feature quality and data accuracy
2. 2.Feature Availability: All 10 features must be available for prediction
3. 3.Temporal Drift: Instagram's platform and bot behavior may change over time
4. 4.Privacy: Ensure compliance with Instagram's terms of service when collecting data
5. 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:

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