Validation des données et contrôles qualité

Afin d'assurer la fiabilité de vos données de conception et d'analyse et de réduire les risques d'erreurs, Meridian GeoX intègre des fonctionnalités de double vérification de votre processus. La bibliothèque évalue vos données à l'aide de deux modules distincts : les contrôles de validation des données et les contrôle de la qualité des données.

Types de vérifications des données

Il est important de comprendre comment la bibliothèque gère les différents types de problèmes de données :

  • Contrôles de validation : ces vérifications permettent de s'assurer que vos données respectent certaines exigences. Si un contrôle de validation échoue, la bibliothèque génère une exception ValueError et interrompt l'exécution.

  • Contrôles de qualité : ces vérifications identifient les anomalies susceptibles de compromettre la qualité des résultats, mais n'empêchent pas l'exécution du code. À la place, elles consignent des messages d'avertissement dans la console et renvoient des détails dans un objet QualityCheckResult structuré.

Contrôles de validation de référence

Avant de passer à des algorithmes spécifiques, la bibliothèque effectue des validations de base sur toutes les données d'entrée :

  • Conformité du schéma : les données doivent contenir date (aucune valeur nulle), location (chaînes non vides et aucune valeur nulle) et conversions (aucune valeur nulle). Si l'attribut spend est fourni, les valeurs doivent être non négatives et non nulles.
  • Conversions positives : la somme totale de la colonne conversions dans l'ensemble de données doit être strictement supérieure à 0.
  • Précision des données : les données doivent suivre un schéma quotidien. Les schémas hebdomadaires ne sont pas acceptés et sont bloqués.

Vérifications de la phase de conception

Lorsque vous exécutez geox.run_design(), la bibliothèque évalue vos données de prétest pour s'assurer qu'elle peut générer des candidats à l'étude efficaces.

Contrôles de validation

Les contrôles de validation suivants s'appliquent pendant la phase de conception :

  • Durée des données de prétest : les données doivent contenir des dates uniques correspondant à au moins trois fois la experiment_duration.
  • Disponibilité des zones géographiques : après avoir supprimé les zones géographiques exclues par l'utilisateur, le groupe restant doit contenir au moins 2 * (cell_count + 1) zones géographiques, où cell_count correspond au nombre de cellules de traitement.
  • Chevauchement des contraintes : les zones géographiques exclues ne doivent pas chevaucher les zones géographiques de contrôle devant être incluses.
  • Limites alpha et de puissance : les valeurs alpha et power doivent être strictement comprises entre 0 et 1.
  • Exigences spécifiques au test : selon le type de test que vous avez conçu, la bibliothèque applique des exigences strictes en matière de données et de paramètres :
    • GO_DARK et HEAVY_UP : votre ensemble de données doit contenir une colonne spend quotidienne. Pour une étude à cellule unique ou la première cellule d'une étude multicellulaire, une colonne nommée spend ou spend_cell_1 est attendue. Pour les cellules suivantes, une colonne correspondante est attendue (par exemple, spend_cell_2).
    • HOLDBACK : les données de séries temporelles sur les dépenses ne sont pas nécessaires. Toutefois, vous devez vous assurer que le paramètre de coût par conversion incrémentale (cost_per_incremental_conversion) est supérieur à 0. Remarque : la valeur par défaut de cost_per_incremental_conversion est 1,0. Par conséquent, cette validation n'échoue que si vous la définissez explicitement sur 0 ou sur une valeur négative, ou si vous omettez une cellule holdback spécifique lorsque vous transmettez un dictionnaire multicellulaire.
  • Maximiser les conversions : la valeur max_conversions_percent doit être strictement inférieure à 0,5.

Contrôles qualité

Les contrôles qualité suivants s'appliquent pendant la phase de conception :

  • Avertissements sur configuration du budget : la bibliothèque vous avertit si vos constraints ne correspondent pas à votre type de test. Pour GO_DARK ou HEAVY_UP, elle attend une variation en pourcentage (budget_pct) et affiche un avertissement si un budget absolu est fourni. Pour HOLDBACK, elle attend un budget absolu et affiche un avertissement si un pourcentage est fourni.
  • Isolation des anomalies : la bibliothèque recherche les zones géographiques dont les dépenses sont supérieures à 0, mais qui n'enregistrent aucune conversion. Par défaut (exclude_geos_no_response=True), la bibliothèque les exclut automatiquement des répartitions candidates.
  • Rareté des données : des avertissements sont consignés si la fraction de jours de conversion manquants dépasse 30 % ou si les jours de dépenses manquants dépassent 30 % pour les cellules de traitement GO_DARK ou HEAVY_UP actives. Un avertissement est également consigné si le nombre total de conversions nulles dépasse 50 %.
  • Cardinalité élevée : un avertissement est consigné si le nombre de zones géographiques uniques dépasse 500, car une précision excessive peut généralement fausser les estimations du lift en raison du flux de population entre les zones géographiques.
  • Entrées en double : si plusieurs entrées existent pour la même date et le même emplacement, un avertissement est consigné et les entrées sont automatiquement agrégées.

Vérifications de la phase d'analyse

Lors de l'exécution d'une analyse post-test à l'aide de geox.analyze(), la bibliothèque applique une synchronisation stricte avec la conception de votre étude pré-test d'origine.

Contrôles de validation

Les contrôles de validation suivants s'appliquent pendant la phase de d'analyse :

  • Cohérence de l'ensemble géographique : les zones géographiques de l'ensemble de données d'analyse importé doivent correspondre exactement à l'union des zones géographiques de contrôle et de traitement définies (après suppression des zones géographiques exclues) lors de la phase de conception.
  • Durée du prétest : la période de prétest de vos données d'analyse doit durer au moins trois fois la experiment_duration.
  • Aucun chevauchement : la date de fin du prétest (si elle est définie) doit être strictement antérieure à la date de début de l'analyse.

Contrôles qualité

Pendant l'analyse, la bibliothèque effectue les contrôles de qualité suivants, en limitant son évaluation spécifiquement à la période de prétest pour éviter les biais post-traitement :

  • Isolation des anomalies : la bibliothèque recherche les zones géographiques dont les dépenses sont supérieures à 0, mais qui n'enregistrent aucune conversion.
  • Rareté des données : des avertissements sont consignés si la fraction de jours de conversion manquants dépasse 30 % ou si les jours de dépenses manquants dépassent 30 % pour les cellules de traitement GO_DARK ou HEAVY_UP actives. Un avertissement est également consigné si le nombre total de conversions nulles dépasse 50 %.
  • Cardinalité élevée : un avertissement est consigné si le nombre de zones géographiques uniques dépasse 500.
  • Entrées en double : si plusieurs entrées existent pour la même date et le même emplacement, un avertissement est consigné et les entrées sont automatiquement agrégées.

Configurer et afficher les contrôles de qualité

Vous pouvez contrôler les comportements de filtrage automatisé à l'aide de l'objet QualityCheckConfig et afficher les résultats de l'évaluation à l'aide de l'objet QualityCheckResult.

Pour obtenir la liste complète des paramètres, des seuils par défaut et des types de données renvoyés, consultez le module de qualité des données dans la documentation de référence de l'API.

L'exemple suivant montre comment configurer des comportements de filtrage automatique :

# Configure automatic filtering behavior
import meridian_geox as geox

quality_config = geox.QualityCheckConfig(
    # Automatically excludes geos with spend but no conversions (design phase
    # only)
    exclude_geos_no_response=True,
    exclude_outlier_dates=True,  # Automatically excludes outlier dates
)

# QualityCheckResult is returned as part of your design or analysis outputs.
# It contains:
# - quality_metrics (pd.DataFrame with metric, value, message, and threshold)
# - outlier_geos (Set of identified outlier locations)
# - outlier_dates (Set of identified outlier dates)