Glossaire Développeur - Guide de Navigation Pipeline¶

Introduction¶

Ce glossaire est conçu pour vous aider à trouver rapidement où modifier le code selon le type de changement demandé. Chaque section liste les modifications courantes avec les fichiers et fonctions concernés.

📊 Données et colonnes¶

"Ajouter/modifier une colonne dans les données"¶

Mapping colonnes : /app/MariaDB/Tool_architecture/{country}/{table}_mapping_{country}.txt
Types colonnes : /app/MariaDB/Tool_architecture/{country}/Types/{table}_mapping_types_{country}.txt
Schéma DB : /app/MariaDB/Tool_architecture/MariaDB Model Schema/{table}_model_schema.txt
Code : Step_02_Data_Integration.py → process_files()

"Changer le format d'une date"¶

Parsing général : Step_02_Data_Integration.py → process_files() (paramètre dayfirst)
Parmalat spécifique : Step_02_Data_Integration.py → convert_parmalat_dates()
Config : /app/inputs/{business_unit}/promo_config.json → "Dayfirst_datetime"

"Modifier le nom d'une colonne source"¶

Fichier : /app/MariaDB/Tool_architecture/{country}/{table}_mapping_{country}.txt
Format : {'Ancien_nom': 'Nouveau_nom'}

💰 Calculs financiers et marges¶

"Modifier le calcul des marges"¶

Galbani : Step_06_Valuation_of_volume_effects.py → compute_margin_italy_galbani()
Parmalat : Step_06_Valuation_of_volume_effects.py → compute_margin_italy_parmalat()
Nouveau pays : Step_06_Valuation_of_volume_effects.py → compute_margin_{country}()

"Changer la formule de marge ajustée"¶

Galbani : Step_06_Valuation_of_volume_effects.py → compute_margin_italy_galbani() → Ligne ~100
```
df_sell_in['Adjusted_gross_margin'] = ...
```
Parmalat : Utilise marges pré-calculées de Step 3

"Modifier le calcul des coûts promotionnels"¶

Galbani : Step_03_Data_Cleaning.py → promo_costs_recomputation_italy_galbani()
Parmalat : Step_03_Data_Cleaning.py → promo_costs_recomputation_italy_parmalat()
Colonnes concernées : Rechercher On_invoice_promo_costs_ et Promo_funding_off_invoice_

"Calculer le ROI différemment"¶

Calcul principal : Step_07_Aggregation_at_promo_level.py → compute_performance_metrics()
Galbani : Step_07_Aggregation_at_promo_level.py → filter_promo_events_italy_galbani()

Parmalat : Step_07_Aggregation_at_promo_level.py → filter_promo_events_italy_parmalat()

df['ROI'] = ((df['Promo_margin_at_event_level'] * df['Adj_Promo_Volume'] - 
              df['Baseline_Margin'] * df['Baseline_Volume']) / df['Promo_Costs'])

📈 Baseline et méthodologies¶

Config : /app/inputs/{business_unit}/promo_config.json
"Promo_intensity_mid_lower_limit" (défaut: 0.60)
"Promo_intensity_mid_upper_limit" (défaut: 0.75)
Code : Step_04_Building_Model_Database.py → data_model_sell_in_{country}()

"Modifier le calcul du baseline"¶

Standard : Step_04_Building_Model_Database.py → compute_baseline_volume() ou compute_baseline_volume_parmalat()
Statistical : Step_04_Building_Model_Database.py → statistical_baseline_computation() ou statistical_baseline_computation_parmalat()
Nombre semaines : /app/inputs/{business_unit}/promo_config.json → "Number_of_weeks_lags_baseline"

"Changer les règles In&Out"¶

Galbani : Step_04_Building_Model_Database.py → apply_in_out_rules()
Parmalat : Step_04_Building_Model_Database.py → apply_in_out_rules_parmalat()
Tables ref : In_Out_Comparable_products_Italy ou In_Out_Comparable_products_parmalat

"Ajuster les seuils outliers"¶

Config : /app/inputs/{business_unit}/promo_config.json
"Outliers_percentile_lower_limit" (défaut: 0.05)
"Outliers_percentile_upper_limit" (défaut: 0.95)

🔄 Cannibalisation et effets¶

"Modifier le calcul de cannibalisation"¶

Galbani : Step_06_Valuation_of_volume_effects.py → compute_cannibalization_italy_galbani()
Parmalat : Step_06_Valuation_of_volume_effects.py → compute_cannibalization_italy_parmalat()

Catégories UHT : Ligne ~50 dans compute_cannibalization_italy_parmalat()

CANNIBALIZATION_CATEGORIES = ['UHT normal milk', 'UHT lactose free milk']

"Changer le forward buying"¶

Facteurs : /app/inputs/{business_unit}/promo_config.json
"Forward_buying_low_factor" (défaut: 0.2)
"Forward_buying_mid_factor" (défaut: 0.4)
"Forward_buying_high_factor" (défaut: 0.6)
Galbani sell-in/out : Step_05_Building_Baseline.py → fetch_promo_intensities_italy_galbani()
Parmalat : Step_07_Aggregation_at_promo_level.py → calculate_halo_pantry_and_forward_buying_parmalat()
Windows : Tables Forward_Buying_weeks_window_parmalat ou Forward_buying_classification_Italy_galbani

"Modifier uplift/halo/pantry loading"¶

Calcul uplift : Step_05_Building_Baseline.py → compute_volume_effects_{country}()
Halo/Pantry Galbani : Step_05_Building_Baseline.py → compute_volume_effects_with_sell_out()
Halo/Pantry Parmalat : Step_07_Aggregation_at_promo_level.py → calculate_halo_pantry_and_forward_buying_parmalat()

🏷️ Classification et filtrage¶

"Changer la classification des événements (Value/Volume generator)"¶

Galbani : Step_07_Aggregation_at_promo_level.py → classify_events()
Parmalat : Step_07_Aggregation_at_promo_level.py → classify_events_parmalat()
Seuils : Calculés dynamiquement (75e percentile ROI, moyenne uplift)

"Modifier les critères In_Scope"¶

Global : Step_07_Aggregation_at_promo_level.py → filter_promo_events_{country}()

Critères : Ligne ~50

df['In_Scope'] = (
    (df['Baseline_Volume'] >= 0) &
    (df['Adj_Promo_Volume'] >= 0) &
    (df['Promo_Costs'] > 0) &
    (df['New_category'] != 'not in scope')
).astype(int)

"Filtrer des catégories/produits"¶

Tables : Italy_category_filtering ou Category_filtering_parmalat
Code : Step_03_Data_Cleaning.py → categories_scoping_{country}()
Re-classification : Step_03_Data_Cleaning.py → re_classification_{country}()

📋 Agrégations et niveaux¶

"Changer le niveau d'agrégation"¶

Galbani : Toujours Retailer_name × EAN × EAN_desc
Parmalat : Toujours Retailer_classification × EAN (sans EAN_desc)
Modification : Chercher tous les groupby() dans les steps concernées

"Ajouter une dimension d'analyse"¶

Performance evolution : Step_07_Aggregation_at_promo_level.py → performance_evolution_{country}()
Agrégations : Modifier les groupby() dans compute_metrics()

📤 Exports et formats¶

"Modifier le format Excel de sortie"¶

Colonnes : Step_08_Simulation_Inputs.py → extract_and_export_data()

Renommage : Ligne ~120

df_step_6_03.columns = ['Retailer_name', 'EAN', ...]

Arrondi : Ligne ~140

df_step_6_03['Sell-in discount'] = df_step_6_03['Sell-in discount'].round(1)

"Ajouter un nouveau Quality Check"¶

Fonction : Step_03_Data_Cleaning.py → Ajouter new_quality_check()
Intégration : Step_03_Data_Cleaning.py → main_quality_checks() → dictionnaire quality_checks
Nom fichier : qc{N}_{description}_{business_unit}.csv

🔧 Configuration et paramètres¶

"Modifier les années à traiter"¶

Config : /app/inputs/{business_unit}/promo_config.json → "Years_in_scope_for_tool_refresh"
Format : "2023,2024,2025"

"Changer les seuils de volume minimum"¶

Config : /app/inputs/{business_unit}/promo_config.json → "Volume_filtering"
Code : Step_04_Building_Model_Database.py → adjust_volumes_based_on_threshold()
Seuil retailers : 25% des plus petits

"Ajouter un nouveau business unit"¶

Config : Ajouter dans promo_config.json
Mappings : Créer /app/MariaDB/Tool_architecture/{new_country}/
Pre-processing : Si nécessaire, créer dans Step_01_Specific_Pre_Processing.py
Fonctions spécifiques : Créer {operation}_{new_country}() dans les steps concernées

🐛 Debug et logs¶

"Ajouter des logs de debug"¶

Import : from logger import log_message
Usage : log_message(f"Debug: variable = {variable}")
Localisation : /app/logs/{business_unit}/

"Tracer les transformations de données"¶

Row count : Ajouter avant/après chaque transformation majeure

log_message(f"Rows before: {len(df)}")
# transformation
log_message(f"Rows after: {len(df)}")

"Debug mémoire"¶

Monitoring : Step_04_Building_Model_Database.py et Step_07_Aggregation_at_promo_level.py
Fonction : save_dataframe_in_batches() dans Step_07_Aggregation_at_promo_level.py

🔌 Connexions externes¶

"Modifier la connexion SFTP"¶

Download : Step_00_Download_Inputs.py
Upload : Step_09_Upload_Outputs.py
Retry : Paramètres max_retries, base_delay, max_delay

"Changer la connexion DB"¶

Config : Variables d'environnement dans .env ou docker-compose
Code : db_config.py → create_db_engine()

Index des fonctions principales par concept¶

Volumes et effets¶

Uplift : compute_volume_effects_{country}() dans Step_05
Cannibalisation : compute_cannibalization_{country}() dans Step_06
Forward buying : calculate_halo_pantry_and_forward_buying_parmalat() dans Step_07
Baseline : compute_baseline_volume() dans Step_04

Financier¶

Marges : compute_margin_{country}() dans Step_06
Coûts promo : promo_costs_recomputation_{country}() dans Step_03
ROI : compute_performance_metrics() dans Step_07

Classification¶

Intensité promo : data_model_sell_in_{country}() dans Step_04
Événements : classify_events_{country}() dans Step_07
In&Out : apply_in_out_rules_{country}() dans Step_04

Données¶

Nettoyage : re_classification_{country}() dans Step_03
Mapping : process_files() dans Step_02
Quality checks : quality_check_*() dans Step_03

Patterns de nommage¶

Fonctions¶

Par pays : {operation}_{country}() (ex: compute_margin_italy_galbani)
Générique : {operation}_default() pour fallback
Utils : safe_divide(), normalize_italian_chars(), etc.

Tables DB¶

Étapes : step_{N}_{MM}_{description} (ex: step_3_02_model_data_baseline)
Référence : {Description}_{Country} (ex: Forward_buying_classification_Italy_galbani)
Audit : {operation}_audit_{country} (ex: promo_costs_Italy_galbani)

Fichiers config¶

Mapping : {table}_mapping_{country}.txt
Types : {table}_mapping_types_{country}.txt
Schema : {table}_model_schema.txt

Tips de recherche dans le code¶

Recherche par grep¶

# Trouver où une colonne est utilisée
grep -r "Nom_Colonne" /app/src/scripts/

# Trouver toutes les fonctions d'un pays
grep -r "def.*italy_galbani" /app/src/scripts/

# Trouver les calculs de marge
grep -r "margin\|Margin" /app/src/scripts/Step_06*

# Trouver les groupby pour agrégations
grep -r "groupby.*EAN" /app/src/scripts/

Recherche par concept¶

# ROI
grep -r "ROI\|roi" /app/src/scripts/Step_07*

# Baseline
grep -r "baseline\|Baseline" /app/src/scripts/Step_04* /app/src/scripts/Step_05*

# Forward buying
grep -r "forward.*buying\|Forward.*Buying" /app/src/scripts/

Checklist modification¶

Avant de modifier : 1. ✅ Identifier le bon fichier via ce glossaire 2. ✅ Vérifier si la modification est spécifique à un pays 3. ✅ Chercher les dépendances (colonnes utilisées ailleurs) 4. ✅ Ajouter des logs pour tracer les changements 5. ✅ Tester sur un échantillon de données 6. ✅ Vérifier les Quality Checks après modification 7. ✅ Documenter le changement

Ce glossaire est maintenu à jour avec la version 1.0 de la pipeline