# ## Générateur de graphiques des performances pour des perturbations données
# Modèle : E5
# Dataset : Challenge evalLLM
# Exploite une liste de pertubation définies dans un fichier `perturbation.txt` sous trois formes:
# - `mot -> mot` pour un remplacement (éventuelement avec le mot vide pour supprimer)
# - `mot +` pour ajouter la requête puis le mot à gauche du document
# - `+ mot` pour ajouter le mot puis la requête à droite du document
#
# Les graphiques sont enregistrés dans `./res/<descripteur-de-la-perturbation>.png`
#
# # Générateur de graphiques de performance pour l'analyse de perturbations textuelles
# ## Description
# Ce script permet d'évaluer l'impact de perturbations lexicales sur les scores produits par un modèle de retrieval dense. À partir d'un ensemble de couples *(requête, document)* et d'une liste de perturbations définies par l'utilisateur, il génère différentes statistiques et représentations graphiques comparant les performances obtenues sur les documents originaux et leurs versions perturbées.
# Les perturbations sont appliquées uniquement aux documents. Les scores de similarité entre les requêtes et les documents sont ensuite recalculés afin d'étudier la sensibilité du modèle à ces modifications.
# ## Format des perturbations
# Les perturbations doivent être décrites dans un fichier texte contenant une règle par ligne. Trois types de transformations sont supportés :
# * `mot1->mot2` : remplacement de `mot1` par `mot2` ;
# * `mot->` : suppression de `mot` ;
# * `mot+` : ajout de `mot` au début du document ;
# * `+mot` : ajout de `mot` à la fin du document.
# Exemple :
# ```
# drone->aéronef
# militaire->
# important+
# +confidentiel
# ```
# ## Données d'entrée
# Le script nécessite :
# * un modèle de retrieval compatible avec MechIR ;
# * un jeu de données contenant des couples *(requête, document)* ;
# * un fichier décrivant les perturbations à appliquer.
# Les données peuvent provenir soit :
# * d'un fichier CSV ;
# * d'une collection compatible avec `ir_datasets`.
# ### Paramètres concernant les entrées
# * `dot_model_name` : nom du modèle dense utilisé pour le calcul des représentations dans la base HuggingFace;
# * `perturbations_path` : chemin vers le fichier de perturbations ;
# * `data_path` : chemin vers le fichier CSV ou identifiant de la collection dans la librairie `ir_datasets`;
# * `is_irdata` : indique si les données proviennent d'`ir_datasets` ;
# Dans le cas où le dataset provient d'un CSV:
# * `query_field` : nom de la colonne contenant les requêtes ;
# * `text_field` : nom de la colonne contenant les documents ;
# Dans le cas où le dataset est présent dans `ir_datasets`:
# * `query_id_subset` : liste optionnelle des identifiants de requêtes à conserver.
# ## Résultats produits
# Selon les options activées, le script peut générer :
# * les distributions des scores avant et après perturbation ;
# * les matrices d'impact des perturbations pour chaque composant du modèle sous la forme :
# * de moyennes des perturbations des paires ;
# * les écarts-types associés ;
# ### Paramètres concernant les sorties
# * `gen_matrices` : calcule les matrices d'impact des perturbations sur les composants ;
# * `gen_mean` : génère les graphiques des moyennes ;
# * `gen_std` : génère les graphiques des écarts-types;
# * `res_path` : répertoire où enregistrer les graphiques.
# ## Sauvegarde
# Un fichier JSON permettant de sauvegarder les scores calculés pour éviter leur recomputation lors d'exécutions ultérieures.
# Pour conserver les résultats calculés lors d'une execution, définir `save_values = True`.
# Pour pour exploiter des résultats préalablement sauvegardés, définir `load_values = True`.
# Le fichier JSON est enregistré/ lu est défini par `load_path`.
