Documentation de référence de l'API Meridian GeoX

Module de conception

Afficher la source

Le module de conception spécifie les paramètres du test et génère des répartitions géographiques optimisées (groupe de traitement par rapport au groupe de contrôle) en fonction des données historiques. Les classes de données qui définissent les paramètres d'entrée et de sortie, ainsi que les fonctions principales permettant de générer, de comparer et de visualiser les conceptions, sont listées dans les sections suivantes.

DesignConfig

Classe de configuration qui définit les paramètres principaux d'un test Meridian GeoX.

@dataclasses.dataclass
class DesignConfig:
  experiment_duration: datetime.timedelta
  experiment_types: Union[
      ExperimentType,
      dict[str, ExperimentType],
  ] = ExperimentType.HOLDBACK
  methodology: Methodology = Methodology.TBR
  geo_assignment_rule: GeoAssignmentRule = GeoAssignmentRule.STRATIFIED_SAMPLING
  cell_count: int = 1
  alpha: float = 0.1
  power: float = 0.8
  test_type: TestType = TestType.TWO_SIDED
  design_output_count: int = 10
  cost_per_incremental_conversion: Union[float, dict[str, float]] = 1.0
  n_candidates: int = 100_000
  n_ranked_candidates: int = 100
  max_candidate_generation_retries: int = 10
  seed: int = 42
  slope_tolerance: float = 0.2
  min_r2: float = 0.8
  num_strata: int = 4
  k_means_iterations: int = 10

Attributs	Description
experiment_duration	Durée du test, spécifiée en tant que datetime.timedelta. Unités acceptées : weeks et days.
experiment_types	Définit la nature du test, par exemple holdback, go-dark ou heavy-up. Pour les tests multicellulaires, différents types peuvent être attribués à chaque cellule à l'aide d'un dictionnaire. Sinon, un seul type fourni est appliqué à toutes les cellules.
methodology	Méthode choisie pour la sélection de la conception, par exemple TBR.
geo_assignment_rule	Règle utilisée pour attribuer des zones géographiques à différents groupes, comme RANDOM ou STRATIFIED_SAMPLING.
cell_count	Nombre total de cellules de traitement. Utilisez cell_count > 1 pour les scénarios multitraitements partageant un contrôle commun.
alpha	Seuil de signification du test. La valeur par défaut est 0,1 (90 % de confiance).
power	Puissance statistique cible (probabilité de détecter un effet réel). La valeur par défaut est 0,8.
test_type	Type de test statistique à effectuer, par exemple ONE_SIDED ou TWO_SIDED. La valeur par défaut est TWO_SIDED.
design_output_count	Nombre de conceptions recommandées classées à renvoyer. La valeur par défaut est 10.
cost_per_incremental_conversion	Équivaut à 1 / ROAS incrémental cible si les données sur les revenus sont utilisées. Utilisé pour estimer les besoins budgétaires des tests holdback (cellule). Facultatif (et ignoré) pour les tests go-dark et heavy-up (cellule). Pour les tests multicellulaires, différentes valeurs peuvent être attribuées à chaque cellule holdback à l'aide d'un dictionnaire. Si un seul float est fourni pour une conception multicellulaire, il sera appliqué à toutes les cellules holdback. La valeur par défaut est 1,0.

Paramètres avancés de recherche de conception

Attention : Il n'est pas recommandé de modifier les valeurs par défaut des paramètres avancés de recherche de conception.

Attributs	Description
n_candidates	Nombre de candidats pour l'étape de notation rapide. La valeur par défaut est 100 000.
n_ranked_candidates	Nombre de candidats entièrement évalués. La valeur par défaut est 100.
max_candidate_generation_retries	Nombre maximal de tentatives de génération de candidats. La valeur par défaut est 10.
seed	Graine du générateur de nombres aléatoires. La valeur par défaut est 42.
slope_tolerance	Différence symétrique maximale autorisée pour la vérification de la pente. La valeur par défaut est 0,2.
min_r2	R^2 minimal autorisé pour la conception. La valeur par défaut est 0,8.
num_strata	Nombre de strates pour l'échantillonnage stratifié. La valeur par défaut est 4.
k_means_iterations	Nombre d'itérations pour le clustering k-moyennes. La valeur par défaut est 10.

Budget

Contrainte budgétaire pour une seule cellule.

@dataclasses.dataclass
class Budget:
  budget: Optional[float] = None
  budget_pct: Optional[float] = None

Attributs	Description
budget	Budget maximal pour la conception du test (par cellule), spécifié sous la forme d'un montant total de budget. Doit être spécifié pour les cellules holdback.
budget_pct	Variation maximale en pourcentage du budget pour la conception du test (par cellule). Doit être spécifiée pour les cellules go-dark et heavy-up. Doit être négative pour le type go-dark et positive pour le type heavy-up.

Contraintes

Définit des contraintes opérationnelles facultatives pour l'algorithme de conception.

@dataclasses.dataclass
class Constraints:
  included_control_geos: Set[str]
  excluded_geos: Set[str]
  excluded_dates: Set[pd.Timestamp]
  budget_constraint: Union[Budget, dict[str, Budget], None] = None
  max_conversions_percent: Optional[float] = 0.3

Attributs	Description
included_control_geos	Zones géographiques spécifiques devant être incluses dans le groupe de contrôle.
excluded_geos	Zones géographiques spécifiques à exclure de la conception du test.
excluded_dates	Dates spécifiques à exclure de la conception du test.
budget_constraint	Contrainte budgétaire pour la conception du test (par cellule). Il peut s'agir d'un montant total du budget ou d'une variation en pourcentage. Pour les tests multicellulaires, différentes valeurs peuvent être attribuées à chaque cellule à l'aide d'un dictionnaire. Sinon, la seule valeur fournie est appliquée à toutes les cellules. Si la variation en pourcentage du budget n'est pas spécifiée pour une cellule go-dark, la valeur par défaut est -100 %. Pour une cellule heavy-up, la valeur par défaut est de 100 %.
max_conversions_percent	Volume de conversions maximal autorisé pour le groupe de traitement. Pour les conceptions multicellulaires, ce pourcentage correspond au total de toutes les cellules de traitement. La valeur par défaut est 0,3.

DesignSet

Ensemble de conceptions de tests générées et de leurs métriques comparatives.

@dataclasses.dataclass
class DesignSet:
  designs: dict[str, Design]
  design_metrics: pd.DataFrame

Attributs	Description
designs	Dictionnaire mappant les ID de conception à des objets Design individuels.
design_metrics	DataFrame contenant les conceptions classées et leurs métriques associées, telles que l'effet minimal détectable et le budget.

Colonnes de métriques de conception DataFrame

Colonne	Description
design_id	Identifiant unique de la conception.
cell	ID de la cellule de traitement.
design_methodology	Méthodologie utilisée pour la conception.
r2	R^2 hors échantillon, calculé en testant la justesse prédictive du modèle sur des données historiques non utilisées lors de la phase d'entraînement initiale.
mde	L'effet minimal détectable (MDE, Minimum Detectable Effect) représente la plus petite amélioration du KPI principal que le test est en mesure de détecter avec une pertinence statistique. Plus le MDE est faible, plus la conception est sensible.
mde_abs	Nombre minimal de conversions incrémentales requis. Il est calculé comme suit : mde * treatment_conversion_volume.
p_value (AA)	Résultat d'un contrôle de robustesse où le modèle est appliqué à une période sans traitement connu. Une valeur p supérieure au seuil de signification (généralement 0,1) indique que la conception réussit le test A/A et n'est pas sujette aux faux positifs.
budget	Modifications nécessaires des dépenses marketing totales prévues. Dans les études go-dark ou heavy-up, ceci est calculé en fonction des données de dépenses et de la variation en pourcentage du budget saisie par l'utilisateur. Dans les études holdback, le CpIC est utilisé pour estimer le budget requis.
design_implied_cpic	Coût par conversion incrémentale (CpIC) implicite de la conception, calculé en divisant le budget par le nombre minimal de conversions incrémentales requis.
treatment_conversions_pct	Pourcentage de conversion du groupe de traitement.
treatment_geo_count	Nombre de zones géographiques dans le groupe de traitement.

Conception

Représente une conception de test unique, y compris les attributions géographiques et la configuration utilisée.

@dataclasses.dataclass
class Design:
  designs: dict[str, PerCellDesign]
  control_geos: Set[str]
  excluded_geos: Set[str]
  excluded_dates: Set[pd.Timestamp]
  design_config: Optional[DesignConfig] = None
  constraints: Optional[Constraints] = None
  quality_check_result: Optional[QualityCheckResult] = None
  geo_stratum_labels: Optional[JnpArray] = None
  data: Optional[pd.DataFrame] = None

  def export_to_json(self) -> str

  @classmethod
  def load_from_json(cls, json_str: str) -> 'Design'

Attributs	Description
designs	Dictionnaire mappant les ID de cellule de traitement à leurs résultats PerCellDesign respectifs.
control_geos	Ensemble des zones géographiques attribuées au groupe de contrôle.
excluded_geos	Ensemble des zones géographiques exclues du test. Inclut les zones géographiques exclues manuellement par l'utilisateur et les zones géographiques aberrantes détectées par les contrôles de qualité des données (si elles sont configurées pour être supprimées automatiquement).
excluded_dates	Dates exclues de la conception. Inclut les dates exclues manuellement par l'utilisateur et les dates aberrantes détectées par les contrôles de qualité des données (si elles sont configurées pour être supprimées automatiquement).
design_config	Objet DesignConfig utilisé pour créer cette conception spécifique.
constraints	Objet Constraints appliqué lors de la recherche de conception.
quality_check_result	Résultat des contrôles de qualité des données effectués sur les données d'entrée.
geo_stratum_labels	Libellé de strate de chaque zone géographique, classé par nom de zone géographique. Ceci est utilisé à des fins d'analyse.
data	Données utilisées pour la conception. Ceci est utilisé à des fins d'analyse.

Méthode	Description
export_to_json	Exporte l'objet de conception vers un fichier JSON.
load_from_json	Charge un objet de conception à partir d'un fichier JSON.

PerCellDesign

Contient les attributions spécifiques et les métriques statistiques d'une seule cellule de traitement dans une conception.

@dataclasses.dataclass
class PerCellDesign:
  treatment_geos: Set[str]
  minimum_detectable_effect: float
  design_implied_cpic: float
  p_value: float
  budget: float
  counterfactual_conversions: Optional[pd.DataFrame] = None

Attributs	Description
treatment_geos	Ensemble des zones géographiques attribuées au groupe de traitement pour cette cellule.
minimum_detectable_effect	La plus petite taille d'effet que la conception est capable de détecter.
design_implied_cpic	Coût par conversion incrémentale (CpIC) implicite de la conception, calculé en divisant le budget par le nombre minimal de conversions incrémentales requis.
p_value	Seuil de signification d'un test A/A vérifiant que les groupes de traitement et de contrôle sont équilibrés avant le début du test.
budget	Coût estimé pour cette cellule de traitement en fonction des paramètres du test.
counterfactual_conversions	Série temporelle de conversion contrefactuelle. Inclut la date, les conversions observées et contrefactuelles. Ceci est utilisé à des fins de représentation graphique.

run_design()

Fonction principale permettant de générer et de classer les conceptions de tests potentielles.

def run_design(
    data: pd.DataFrame,
    design_config: DesignConfig,
    constraints: Constraints,
    data_quality_check_config: QualityCheckConfig = QualityCheckConfig()
)-> DesignSet

Paramètres	Description
data	Série temporelle historique de prétest contenant date, location, conversions et (facultatif) spend.
design_config	Paramètres de la conception du test.
constraints	Contraintes opérationnelles pour la conception du test.
data_quality_check_config	Option permettant de configurer des contrôles automatiques de la qualité des données. Par défaut, les zones géographiques sans réponse et les dates aberrantes sont automatiquement supprimées.

Renvoie : un objet DesignSet contenant une liste d'objets Design classés et les métriques associées, telles que l'effet minimal détectable et le budget.

compare_designs()

Compare plusieurs conceptions de test selon différentes méthodologies, règles d'attribution ou configurations.

def compare_designs(
    data: pd.DataFrame,
    design_requirements: list[tuple[DesignConfig, Constraints]],
    design_output_count: int = 10,
) -> DesignSet

Paramètres	Description
data	Série temporelle historique de prétest.
design_requirements	Liste de tuples, chacun contenant un objet DesignConfig et un objet Constraints.
design_output_count	Nombre de conceptions à renvoyer. La valeur par défaut est 10.

Renvoie : un DesignSet unifié contenant les conceptions classées de toutes les configurations fournies.

concat_design_reports()

Concatène plusieurs objets DesignSet en un seul DesignSet classé.

def concat_design_reports(
    design_sets: list[DesignSet], design_output_count: int = 10
) -> DesignSet

Paramètres	Description
design_sets	Liste d'objets DesignSet à fusionner.
design_output_count	Nombre de conceptions principales à renvoyer dans l'ensemble fusionné. La valeur par défaut est 10.

Résultat : un seul objet DesignSet contenant toutes les conceptions, reclassées en fonction de leurs métriques.

plot_design()

Génère une représentation visuelle d'une conception spécifique.

def plot_design(
    design_to_plot: Design
)

Paramètres	Description
design_to_plot	Objet Design spécifique à visualiser.

Description : représente graphiquement la série temporelle des conversions, en comparant le groupe de traitement au contrefactuel pour visualiser l'efficacité de la répartition géographique.

Module d'analyse

Afficher la source

Le module d'analyse calcule l'impact incrémental d'un test terminé à l'aide d'une modélisation contrefactuelle et d'une inférence robuste. Les classes de données qui définissent les paramètres d'entrée et de sortie, ainsi que les fonctions principales permettant de générer et de visualiser les rapports de test, sont listées dans les sections suivantes.

AnalysisConfig

Paramètres requis pour exécuter une analyse de l'impact d'une étude GeoX terminée.

@dataclasses.dataclass
class AnalysisConfig:
  design: Design
  analysis_start_date: pd.Timestamp
  analysis_end_date: pd.Timestamp
  pretest_end_date: Optional[pd.Timestamp] = None
  excluded_dates: Set[pd.Timestamp]
  alpha: Optional[float] = None
  test_type: Optional[TestType] = None
  n_placebo_candidates: int = 100_000
  n_top_placebos: int = 500
  min_placebo_r2: float = 0.6
  min_placebo_count_warning: int = 100
  min_placebo_count_error: int = 10

Attributs	Description
design	Informations spécifiques sur la répartition géographique et la provenance utilisées lors de la phase de conception.
analysis_start_date	Date de début de l'analyse.
analysis_end_date	Date de fin de l'analyse, qui peut inclure une période d'attente.
pretest_end_date	Date de fin de la période de prétest. Si cette information n'est pas fournie, la période de prétest correspondra à toutes les dates antérieures à analysis_start_date.
excluded_dates	Dates spécifiques à exclure de l'analyse, telles que les jours aberrants.
alpha	Seuil de signification. S'il est omis, il est déduit à partir de la configuration de la conception.
test_type	Type de test statistique à effectuer. S'il n'est pas fourni, il sera déduit à partir de la configuration de la conception.

Paramètres d'analyse avancés

Attention : Il n'est pas recommandé de modifier les valeurs par défaut des paramètres d'analyse avancés.

Attributs	Description
n_placebo_candidates	Nombre de candidats placebo initiaux générés avant la sélection. La valeur par défaut est 100 000.
n_top_placebos	Nombre des meilleurs candidats placebo valides utilisés pour l'analyse. La valeur par défaut est 500.
min_placebo_r2	Score R-carré hors échantillon minimal requis pour qu'une conception placebo soit conservée pour l'analyse. La valeur par défaut est 0,6.
min_placebo_count_warning	Nombre de candidats placebo valides en dessous duquel un avertissement sera consigné. La valeur par défaut est 100.
min_placebo_count_error	Nombre de candidats placebo valides en dessous duquel une erreur sera générée. La valeur par défaut est 10.

AnalysisResult

Contient le résultat statistique agrégé d'un test GeoX sur toutes les cellules.

@dataclasses.dataclass
class AnalysisResult:
  results: dict[str, AnalysisMetrics]
  analysis_config: AnalysisConfig
  excluded_geos: Set[str]
  excluded_dates: Set[pd.Timestamp]
  quality_check_result: Optional[QualityCheckResult] = None

Attributs	Description
results	Dictionnaire mappant chaque cellule de traitement à l'objet AnalysisMetrics correspondant.
analysis_config	Configuration utilisée pour l'analyse.
excluded_geos	Zones géographiques exclues de l'analyse. Inclut toutes les zones géographiques exclues lors de la phase de conception.
excluded_dates	Dates exclues de l'analyse. Inclut les dates exclues manuellement par l'utilisateur de la configuration de l'analyse et les dates aberrantes de la phase d'analyse (si elles sont configurées pour être supprimées automatiquement).
quality_check_result	Résultat des contrôles de qualité des données effectués sur les données d'entrée.

AnalysisMetrics

Contient des métriques pour l'analyse d'une seule cellule.

@dataclasses.dataclass
class AnalysisMetrics:
  lift: Estimate
  percent_lift: Estimate
  cumulative_lift: pd.DataFrame
  counterfactual_conversions: pd.DataFrame
  pointwise_difference: pd.DataFrame
  icpd: Optional[Estimate] = None
  cumulative_icpd: Optional[pd.DataFrame] = None
  descriptive_metrics: Optional[DescriptiveMetrics] = None

Attributs	Description
lift	Estimation ponctuelle et intervalles de confiance pour les conversions incrémentales absolues.
percent_lift	Pourcentage d'impact estimé avec les intervalles de confiance.
cumulative_lift	Série temporelle des estimations de l'impact des conversions incrémentales sur la période d'analyse.
counterfactual_conversions	Série temporelle de conversion contrefactuelle. Inclut la date, les valeurs observées, les valeurs contrefactuelles et les intervalles de confiance (période de test uniquement).
pointwise_difference	Différence ponctuelle entre les conversions observées et contrefactuelles. Inclut la date, la différence et les intervalles de confiance (période de test uniquement).
icpd	Conversions incrémentales par dollar. Équivaut au ROAS incrémental si des données sur les revenus sont utilisées. Ceci est renseigné si des données sur les dépenses sont disponibles.
cumulative_icpd	Série temporelle des estimations de conversion incrémentale par dollar (iCPD) sur la période d'analyse. Ceci n'est renseigné que si des données sur les dépenses sont disponibles.
descriptive_metrics	Métriques descriptives pour l'analyse d'une seule cellule. Ceci est utilisé pour l'intégration de Meridian.

Estimation

Une estimation avec son intervalle de confiance.

@dataclasses.dataclass
class Estimate:
  point_estimate: float
  lower_bound: float
  upper_bound: float
  standard_deviation: float
  p_value: float

Attributs	Description
point_estimate	Valeur estimée principale.
lower_bound	Limite inférieure de l'intervalle de confiance.
upper_bound	Limite supérieure de l'intervalle de confiance.
standard_deviation	Écart type de l'estimation.
p_value	Seuil de signification associé à l'estimation.

DescriptiveMetrics

Métriques descriptives pour l'analyse d'une seule cellule.

@dataclasses.dataclass
class DescriptiveMetrics:
  estimated_bau_spend: Optional[float] = None

Attribut

Description

estimated_bau_spend

Représente l'estimation des dépenses habituelles (BAU) pour les zones géographiques incluses dans l'analyse de cette cellule (les zones géographiques de traitement de la cellule spécifique et les zones géographiques de contrôle). Cet attribut n'inclut pas les dépenses des autres cellules de traitement ni des zones géographiques non expérimentales. Il ne représente donc pas les dépenses nationales totales de l'annonceur.

analyze()

Exécute l'analyse de l'impact.

def analyze(
    data: pd.DataFrame,
    analysis_config: AnalysisConfig,
    data_quality_check_config: QualityCheckConfig = QualityCheckConfig()
)-> AnalysisResult

Paramètres	Description
data	Série temporelle complète contenant les données de prétest et de test pour toutes les zones géographiques.
analysis_config	Configuration définissant la méthodologie et les périodes.
data_quality_check_config	Option permettant de configurer des contrôles automatiques de la qualité des données. Par défaut, les dates aberrantes sont automatiquement supprimées.

Renvoie : un objet AnalysisResult contenant les métriques de chaque cellule de traitement.

plot_analysis()

Génère une visualisation de l'analyse du test.

def plot_analysis(
    analysis_result: AnalysisResult
)

Paramètres	Description
analysis_result	Résultat statistique de la fonction analyze().

Description : produit des graphiques de séries temporelles pour les valeurs contrefactuelles, la différence ponctuelle, le lift cumulé et l'iCPD cumulé afin de visualiser l'impact incrémental estimé pour chaque cellule de traitement.

Module sur la qualité des données

Afficher la source

QualityCheckConfig

@dataclasses.dataclass
class QualityCheckConfig:
  exclude_geos_no_response: bool = True
  exclude_outlier_dates: bool = True

Attributs	Description
exclude_geos_no_response	Détermine s'il faut exclure automatiquement les zones géographiques sans réponse pendant la phase de conception. La valeur par défaut est True.
exclude_outlier_dates	Détermine s'il faut exclure automatiquement les dates aberrantes lors des phases de conception ou d'analyse. La valeur par défaut est True.

QualityCheckResult

@dataclasses.dataclass
class QualityCheckResult:
  quality_check_config: QualityCheckConfig
  quality_metrics: pd.DataFrame
  outlier_geos: Set[str]
  outlier_dates: Set[pd.Timestamp]

Attributs	Description
quality_check_config	Paramètres de configuration utilisés pour le contrôle qualité.
quality_metrics	DataFrame contenant les métriques détaillées résultant du contrôle qualité.
outlier_geos	Ensemble des zones géographiques aberrantes identifiées sans réponse.
outlier_dates	Ensemble des dates aberrantes identifiées lors du contrôle qualité.

check_design_data_quality()

def check_design_data_quality(
    data: pd.DataFrame,
    design_config: DesignConfig,
    quality_check_config: QualityCheckConfig
) -> QualityCheckResult

Description : vérifie la qualité des données d'entrée pour la phase de conception. Cette vérification est intégrée directement à la méthode run_design(), ce qui signifie que les contrôles de la qualité des données sont effectués automatiquement lors de la génération des conceptions.

Renvoie : un objet QualityCheckResult.

check_analysis_data_quality()

def check_analysis_data_quality(
    data: pd.DataFrame,
    analysis_config: AnalysisConfig,
    quality_check_config: QualityCheckConfig
) -> QualityCheckResult

Description : vérifie la qualité des données d'entrée pour la phase d'analyse. Cette vérification est intégrée directement à la méthode analyze(), ce qui signifie que les contrôles de la qualité des données sont effectués automatiquement pendant l'analyse.

Renvoie : un objet QualityCheckResult.