EnsembleML

EnsembleML est un petit framework pour comparer et évaluer plusieurs modèles de Machine Learning (SVM, KNN, Régression Logistique, Random Forest, Bagging, XGBoost, Gradient Boosting RFF, etc.) sur un ensemble de jeux de données tabulaires. Il fournit :

• Un runner de validation croisée (KFoldRunner) pour chercher les meilleurs hyperparamètres.
• Un outil de mesure de temps (TimeMeasure) pour évaluer le temps d'entraînement en fonction de la taille d'apprentissage.
• Des utilitaires de chargement de données (dans data/) et une sortie des résultats dans results/.

1) Installation des dépendances

Deux options sont proposées : via uv (recommandé pour la reproductibilité et la vitesse) ou via pip.

Option A — uv

Prérequis :

• Python 3.12+ (3.13 supporté)
• uv installé (voir https://docs.astral.sh/uv/)

Depuis la racine du projet :

# Créer un environnement virtuel et installer les deps depuis pyproject/uv.lock
uv sync

# Activer l'environnement (si nécessaire)
# Sur Linux/macOS:
source .venv/bin/activate
# Sur Windows PowerShell:
# .venv\\Scripts\\Activate.ps1

Option B — pip

Prérequis :

• Python 3.12+ (3.13 supporté)
• pip récent

Depuis la racine du projet :

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\Activate.ps1
pip install -r requirements.txt

2) Lancer les expériences (CLI)

Le point d'entrée est main.py. Par défaut, si aucun modèle n'est précisé, tous les modèles sont exécutés.

Exemples :

# Lancer tous les modèles
python main.py

# Lancer uniquement SVM et KNN
python main.py --svm --knn

# Lancer Random Forest uniquement
python main.py --rf

# Lancer avec mesure de temps (voir section TimeMeasure)
python main.py --time

Arguments disponibles (extraits de main.py) :

• --svm : exécuter SVM uniquement
• --knn : exécuter KNN uniquement
• --logreg : exécuter Régression Logistique
• --rf : exécuter Random Forest
• --bagging : exécuter Bagging (base arbre)
• --boosting : exécuter XGBoost
• --gbrff : exécuter Gradient Boosting avec Random Fourier Features
• --time : lancer un benchmark temps d'entraînement (voir ci-dessous)
• --overwrite : réécrire le fichier de résultats results/result.csv
• --help : afficher l'aide personnalisée

Les datasets utilisés sont chargés depuis data/datasets/ via data.data_recovery.

3) Sorties des résultats

• Résumé principal : results/result.csv avec les colonnes
  • dataset, group (balanced/imbalanced), model, best_params, best_score, fold_variance
• Historique de la recherche d'hyperparamètres : results/history/*_history.csv
• Informations descriptives sur les datasets : results/datasets_info.csv

4) Mesure de temps (TimeMeasure)

TimeMeasure permet de mesurer le temps d'entraînement fit() en fonction de la taille de l'échantillon d'apprentissage. Il prend une liste de modèles (ModelSpec) et un intervalle de tailles à tester.

Exemple minimal :

from sklearn.datasets import make_moons
from sklearn.model_selection import train_test_split
from core import TimeMeasure, ModelSpec
from models import SVMModel, GradientBoostingRFFModel

X, y = make_moons(n_samples=20000, noise=0.2, random_state=0)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.3, random_state=0)

specs = [
    ModelSpec("SVM (linear)", SVMModel, {"C": 1.0}),
    ModelSpec("GBRFF", GradientBoostingRFFModel, {"n_estimators": 25, "gamma": 0.1, "lambda_param": 0.1}),
]

tm = TimeMeasure(
    model_specs=specs,
    min_size=2000,
    max_size=20000,
    step=2000,
    repeats=10,
    scale=True,
    random_state=0,
)

df = tm.measure(X_train, y_train)
print(df.head())
tm.save_csv("results/timings_example.csv")
# Optionnel, nécessite matplotlib+seaborn
# tm.save_plot("results/timings_example.png")

Un exemple exécutable est fourni dans examples/time_measure_example.py.

Champs produits par TimeMeasure :

• model (nom lisible), class (nom de classe), params (JSON), size, repeats, total_fit_time_s, mean_fit_time_s, scaled, stratified.

5) Bonnes pratiques et pièges fréquents

• Mise à l'échelle (scaling) : la CV (KFoldRunner) normalise à l'intérieur de chaque fold. Pour évaluer sur le test final, appliquez le même StandardScaler (fit sur train, transform sur test), sinon l'accuracy peut chuter fortement.
• Encodage des labels : certains modèles internes peuvent utiliser {-1, +1}. Harmonisez la sortie lors de l'évaluation (par ex. remapper -1 -> 0 si nécessaire) — le code le gère déjà dans KFoldRunner.
• Métriques différentes : F1 vs Accuracy selon l'équilibre des classes. Vérifiez que la métrique utilisée correspond à votre objectif.
• Aléatoire : fixez random_state pour des résultats reproductibles.

6) Structure du projet

• core/ : KFoldRunner, TimeMeasure
• models/ : implémentations des modèles héritant de BaseModel
• data/ : chargement des datasets et utilitaires
• examples/ : scripts d'exemples (temps d'entraînement)
• results/ : CSV et figures de sortie

7) Dépannage

• Erreurs de dépendances : assurez-vous que les versions de numpy, pandas, scikit-learn, scipy, xgboost correspondent au requirements.txt.
• Problèmes d'import : exécutez depuis la racine du projet, avec l'environnement activé.
• Pylance « tabs vs spaces » : le repo utilise des tabulations dans certaines classes. Gardez un style cohérent (ou configurez votre éditeur pour convertir en tabs).
• OSError: libgomp.so.1: cannot open shared object file: No such file or directory : sudo apt-get update && sudo apt-get install -y libgomp1

---