Batwing ML Library

Modular, functional, and interpretable machine learning pipeline for classification, multiclass, and regression tasks. Designed for data scientists who want rapid experimentation, clean diagnostics, and powerful model comparisons — all with minimal code.

🚀 Features

• Full EDA and column-level diagnosis
• Modular preprocessing (impute, encode, scale)
• Feature engineering with PCA and correlation filtering
• Hyperparameter tuning with Optuna (classification, regression, multiclass)
• Nested Cross-Validation for robust model benchmarking
• Rich model evaluation (metrics + visualizations)
• Supports cost-sensitive classification and diagnostics
• Dashboard/notebook-friendly outputs (HTML/tabulate/rich)

📦 Installation

Coming soon to PyPI

For now, clone the repo and import functions directly:

git clone https://github.com/your-org/batwing-ml.git

from batwing_ml import (
    summary_dataframe,
    preprocess_dataframe,
    run_nested_cv_classification,
    evaluate_classification_model,
    ...
)

🧠 Module Overview

🔧 Usage Examples

📊 1. Data Summary

summary_dataframe(df, verbose=True, detailing=True, correlation_matrix=True)
summary_column(df, "age", plots=["histogram", "missing_trend"])

⚙️ 2. Preprocessing

X_proc, y_proc, steps = preprocess_dataframe(
    df, target_col="target",
    impute=True, encode="onehot", scale="standard",
    return_steps=True
)

🔁 3. Model Tuning (Binary Classification)

from sklearn.ensemble import RandomForestClassifier
from batwing_ml import hyperparameter_tuning_classification

model_class = RandomForestClassifier
param_grid = {
    'n_estimators': lambda trial: trial.suggest_int("n_estimators", 50, 200),
    'max_depth': lambda trial: trial.suggest_int("max_depth", 3, 10)
}

results = hyperparameter_tuning_classification(
    model_class=model_class,
    param_grid=param_grid,
    X=X, y=y,
    scoring='roc_auc'
)

🏁 4. Nested Cross-Validation (Regression)

models = {
    "ridge": Ridge(),
    "rf": RandomForestRegressor()
}
param_grids = {
    "ridge": {"alpha": [0.1, 1.0, 10]},
    "rf": {"n_estimators": [100, 200], "max_depth": [3, 5]}
}

run_nested_cv_regression(
    X=X, y=y,
    model_dict=models,
    param_grids=param_grids,
    scoring_list=["r2", "rmse", "mae"],
    search_method="grid",
    return_results=True
)

📈 Visualizations

• Feature Importance
• Correlation Heatmaps
• PCA Scree and Scatter Plots
• Confusion Matrix, ROC, Threshold Plots
• Learning Curve, Residuals, Prediction vs Actual
• Lift Charts, Cost-Sensitive Curves

📚 License

MIT License

👥 Contributors

Built by [Your Name] and contributors.

💡 Future Additions

• AutoML wrappers
• MLflow integration
• HTML dashboard export
• Time series module