Referencia de la API de Meridian GeoX

Módulo de diseño

Ver código fuente

El módulo de diseño especifica los parámetros del experimento y genera divisiones geográficas optimizadas (tratamiento frente a control) en función de los datos históricos. Las clases de datos que definen los parámetros de entrada y de salida, y las funciones principales para generar, comparar y visualizar diseños se enumeran en las secciones que siguen.

DesignConfig

Es una clase de configuración que define los parámetros principales de un experimento de 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
Atributos Descripción
experiment_duration Es la duración del experimento, especificada como datetime.timedelta. Unidades admitidas: weeks y days.
experiment_types Define la naturaleza de la prueba, como aislamiento, supresión o aumento. En el caso de los experimentos de varias celdas, se pueden asignar diferentes tipos por celda con un diccionario. De lo contrario, se aplica un único tipo proporcionado a todas las celdas.
methodology Es el método elegido para la selección del diseño, por ejemplo, TBR.
geo_assignment_rule Es la regla que se usa para asignar áreas geográficas a diferentes grupos, como RANDOM o STRATIFIED_SAMPLING.
cell_count Es la cantidad total de celdas de tratamiento. Usa cell_count > 1 para situaciones de varios tratamientos que comparten un control común.
alpha Es el nivel de significancia de la prueba. El valor predeterminado es 0.1 (90% de confianza).
power Es el poder estadístico objetivo (probabilidad de detectar un efecto verdadero). El valor predeterminado es 0.8.
test_type Es el tipo de prueba estadística que se realizará, por ejemplo, ONE_SIDED o TWO_SIDED. El valor predeterminado es TWO_SIDED.
design_output_count Es la cantidad de diseños recomendados y clasificados que se devolverán. El valor predeterminado es 10.
cost_per_incremental_conversion Equivale a 1 / ROAS incremental objetivo si se usan datos de ingresos. Se usa para estimar los requisitos de presupuesto de los experimentos de aislamiento (celda). Opcional (y se ignora) para los experimentos de supresión y de aumento (celda). En los experimentos de varias celdas, se pueden asignar valores diferentes por celda de aislamiento con un diccionario. Si se proporciona un solo valor de número de punto flotante para un diseño de varias celdas, se aplicará a todas las celdas de aislamiento. El valor predeterminado es 1.0.

Parámetros de búsqueda de diseño avanzados

Atributos Descripción
n_candidates Es la cantidad de candidatos para el paso de puntuación rápida. El valor predeterminado es 100,000.
n_ranked_candidates Es la cantidad de candidatos con puntuación completa. El valor predeterminado es 100.
max_candidate_generation_retries Cantidad máxima de reintentos de generación de candidatos. El valor predeterminado es 10.
seed Es el valor de origen del generador de números aleatorios. El valor predeterminado es 42.
slope_tolerance Es la diferencia simétrica máxima permitida para la verificación de la pendiente. El valor predeterminado es 0.2.
min_r2 Es el valor mínimo permitido de R2 para el diseño. El valor predeterminado es 0.8.
num_strata Es la cantidad de estratos para el muestreo estratificado. El valor predeterminado es 4.
k_means_iterations Es la cantidad de iteraciones para el agrupamiento en clústeres de k-means. El valor predeterminado es 10.

Presupuesto

Restricción de presupuesto para una sola celda.

@dataclasses.dataclass
class Budget:
  budget: Optional[float] = None
  budget_pct: Optional[float] = None
Atributos Descripción
budget Es el presupuesto máximo para el diseño del experimento (por celda), especificado como un importe de presupuesto total. Debe especificarse para las celdas de aislamiento.
budget_pct Es el cambio porcentual máximo del presupuesto para el diseño del experimento (por celda). Se debe especificar para las celdas de supresión y aumento. Debe ser negativo para la estrategia de supresión y positivo para la de aumento.

Limitaciones

Define restricciones operativas opcionales para el algoritmo de diseño.

@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
Atributos Descripción
included_control_geos Son las áreas geográficas específicas que se deben incluir en el grupo de control.
excluded_geos Son las áreas geográficas específicas que se excluirán del diseño del experimento.
excluded_dates Son las fechas específicas que se excluirán del diseño del experimento.
budget_constraint Es la restricción de presupuesto para el diseño del experimento (por celda). Podría ser un importe de presupuesto total o un cambio en el porcentaje del presupuesto. En el caso de los experimentos de varias celdas, se pueden asignar valores diferentes por celda con un diccionario. De lo contrario, se aplica el único valor proporcionado a todas las celdas. Si no se especifica el cambio porcentual del presupuesto para una celda de supresión, el valor predeterminado es -100%. Para la celda de aumento, el valor predeterminado es 100%.
max_conversions_percent Es la cantidad máxima de conversiones permitida para el grupo de tratamiento. En el caso de los diseños de varias celdas, este porcentaje se refiere al total de todas las celdas de tratamiento. El valor predeterminado es 0.3.

DesignSet

Es una colección de diseños de experimentos generados y sus métricas comparativas.

@dataclasses.dataclass
class DesignSet:
  designs: dict[str, Design]
  design_metrics: pd.DataFrame
Atributos Descripción
designs Es un diccionario que asigna IDs de diseño a objetos Design individuales.
design_metrics Es un DataFrame que contiene diseños clasificados y sus métricas asociadas, como el MDE y el presupuesto.

Diseña métricas para DataFrame columnas

Columna Descripción
design_id Es el identificador único del diseño.
cell Es el ID de la celda de tratamiento.
design_methodology Es la metodología que se usó para el diseño.
r2 Es el R2 fuera de la muestra, que se calcula probando la exactitud predictiva del modelo con datos históricos que no se usaron durante la fase de entrenamiento inicial.
mde El efecto mínimo detectable (MDE) representa el aumento más pequeño en el KPI principal que el experimento puede detectar con importancia estadística. Un MDE más bajo indica un diseño más sensible.
mde_abs Es la cantidad mínima de conversiones incrementales requeridas. Se calcula como mde * treatment_conversion_volume.
p_value (AA) Es el resultado de una verificación de solidez en la que el modelo se aplica a un período sin tratamiento conocido. Un valor p mayor que el nivel de significancia (por lo general, 0.1) indica que el diseño supera la prueba A/A y no es propenso a falsos positivos.
budget Son los cambios necesarios en la inversión de marketing total proyectada. En los estudios de supresión o aumento, lo calculamos en función de los datos de inversión y el cambio porcentual del presupuesto que ingresa el usuario. En los estudios de aislamiento, usamos el CpIC para estimar el presupuesto requerido.
design_implied_cpic Es el costo por conversión incremental (CpIC) implícito en el diseño, que se calcula dividiendo el presupuesto por la cantidad mínima de conversiones incrementales requeridas.
treatment_conversions_pct Es el porcentaje de conversiones del grupo de tratamiento.
treatment_geo_count Es la cantidad de ubicaciones geográficas en el grupo de tratamiento.

Diseño

Representa un solo diseño de experimento, incluidas las asignaciones geográficas y la configuración utilizada.

@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'
Atributos Descripción
designs Es un diccionario que asigna los IDs de las celdas de tratamiento a sus respectivos resultados de PerCellDesign.
control_geos Es el conjunto de áreas geográficas asignadas al grupo de control.
excluded_geos Es el conjunto de áreas geográficas que se excluyeron del experimento. Incluye las ubicaciones geográficas excluidas de forma manual por el usuario y las atípicas detectadas por las verificaciones de calidad de los datos (si se configuraron para quitarse automáticamente).
excluded_dates Fechas excluidas del diseño. Incluye las fechas excluidas de forma manual por el usuario y las de valores atípicos detectadas por las verificaciones de calidad de los datos (si se configuraron para quitarse automáticamente).
design_config Es el objeto DesignConfig que se usa para crear este diseño específico.
constraints Es el objeto Constraints que se aplicó durante la búsqueda de diseño.
quality_check_result Es el resultado de las verificaciones de calidad de los datos realizadas en los datos de entrada.
geo_stratum_labels Es la etiqueta de estrato de cada ubicación geográfica, ordenada por el nombre de la ubicación. Se utiliza para el análisis.
data Son los datos que se usan para el diseño. Se utilizan para el análisis.
Método Descripción
export_to_json Exporta el objeto de diseño a un archivo JSON.
load_from_json Carga un objeto de diseño desde un archivo JSON.

PerCellDesign

Contiene las asignaciones específicas y las métricas estadísticas de una sola celda de tratamiento dentro de un diseño.

@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
Atributos Descripción
treatment_geos Es el conjunto de áreas geográficas asignadas al grupo de tratamiento de esta celda.
minimum_detectable_effect Es el tamaño del efecto más pequeño que el diseño tiene la capacidad de detectar.
design_implied_cpic Es el costo por conversión incremental (CpIC) implícito en el diseño, que se calcula dividiendo el presupuesto por la cantidad mínima de conversiones incrementales requeridas.
p_value Es el nivel de significancia de una prueba A/A que verifica que los grupos de tratamiento y de control estén equilibrados antes de que comience el experimento.
budget Es el costo estimado de esta celda de tratamiento en función de los parámetros del experimento.
counterfactual_conversions Es la serie temporal de conversiones contrafácticas. Incluye la fecha, las conversiones observadas y las contrafácticas. Se usa para trazar.

run_design()

Es la función principal para generar y clasificar posibles diseños de experimentos.

def run_design(
    data: pd.DataFrame,
    design_config: DesignConfig,
    constraints: Constraints,
    data_quality_check_config: QualityCheckConfig = QualityCheckConfig()
)-> DesignSet
Parámetros Descripción
data Es una serie temporal histórica previa a la prueba que contiene date, location, conversions y, de forma opcional, spend.
design_config Son los parámetros para el diseño del experimento.
constraints Son las restricciones operativas para el diseño del experimento.
data_quality_check_config Es una opción para configurar verificaciones automáticas de la calidad de los datos. La configuración predeterminada consiste en quitar automáticamente las ubicaciones geográficas sin respuesta y las fechas con valores atípicos.

Devuelve: Un objeto DesignSet que contiene una lista de objetos Design clasificados y métricas asociadas, como el MDE y el presupuesto.

compare_designs()

Compara varios diseños de experimentos con diferentes metodologías, reglas de asignación o parámetros de configuración.

def compare_designs(
    data: pd.DataFrame,
    design_requirements: list[tuple[DesignConfig, Constraints]],
    design_output_count: int = 10,
) -> DesignSet
Parámetros Descripción
data Son las series temporales históricas previas a la prueba.
design_requirements Es una lista de tuplas, cada una con un objeto DesignConfig y un objeto Constraints.
design_output_count Es la cantidad de diseños que se devolverán. El valor predeterminado es 10.

Devuelve: Un DesignSet unificado que contiene los diseños clasificados de todos los parámetros de configuración proporcionados.

concat_design_reports()

Concatena varios objetos DesignSet en un solo DesignSet clasificado.

def concat_design_reports(
    design_sets: list[DesignSet], design_output_count: int = 10
) -> DesignSet
Parámetros Descripción
design_sets Es una lista de objetos DesignSet que se combinarán.
design_output_count Es la cantidad de diseños principales que se mostrarán en el conjunto combinado. El valor predeterminado es 10.

Devuelve: Un solo objeto DesignSet que contiene todos los diseños, reclasificados según sus métricas.

plot_design()

Genera una representación visual de un diseño específico.

def plot_design(
    design_to_plot: Design
)
Parámetros Descripción
design_to_plot Es el objeto Design específico que se visualizará.

Descripción: Traza la serie temporal de las conversiones. Para ello, compara el grupo de tratamiento con la situación contrafáctica para visualizar la efectividad de la segmentación geográfica.

Módulo de análisis

Ver código fuente

El módulo de análisis calcula el impacto incremental de un experimento completado con un modelado contrafáctico y una inferencia sólida. Las clases de datos que definen los parámetros de entrada y de salida, y las funciones principales para generar y visualizar los informes de experimentos se enumeran en las siguientes secciones.

AnalysisConfig

Son los parámetros necesarios para ejecutar un análisis de efectividad de un estudio de GeoX completado.

@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
Atributos Descripción
design Es la información específica de la división geográfica y la procedencia que se usó durante la fase de diseño
analysis_start_date Es la fecha de inicio del análisis.
analysis_end_date Es la fecha de finalización del análisis, que puede incluir un período de inactividad.
pretest_end_date Es la fecha de finalización del período previo a la prueba. Si no se proporciona, el período previo a la prueba incluirá todas las fechas anteriores a analysis_start_date.
excluded_dates Son las fechas específicas que se excluirán del análisis, como los días con valores atípicos.
alpha Es el nivel de significancia. Si se omite, se infiere de la configuración de diseño.
test_type Es el tipo de prueba estadística que se realizará. Si no se proporciona, se inferirá de la configuración de diseño.

Parámetros de análisis avanzados

Atributos Descripción
n_placebo_candidates Es la cantidad de candidatos placebo iniciales que se generaron antes de la selección. El valor predeterminado es 100,000.
n_top_placebos Es la cantidad de candidatos placebo válidos principales que se usaron para el análisis. El valor predeterminado es 500.
min_placebo_r2 Es la puntuación mínima de R cuadrado fuera de la muestra que se requiere para que un diseño de placebo se conserve para el análisis. El valor predeterminado es 0.6
min_placebo_count_warning Es la cantidad de candidatos de placebo válidos por debajo de la cual se registrará una advertencia. El valor predeterminado es 100.
min_placebo_count_error Es la cantidad de candidatos de placebo válidos por debajo de la cual se generará un error. El valor predeterminado es 10.

AnalysisResult

Contiene el resultado estadístico agregado de un experimento de GeoX en todas las celdas.

@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
Atributos Descripción
results Es un diccionario que asigna cada celda de tratamiento a su objeto AnalysisMetrics correspondiente.
analysis_config Es la configuración que se usa para el análisis.
excluded_geos Son las ubicaciones geográficas excluidas del análisis. Incluye todas las ubicaciones geográficas excluidas durante la fase de diseño.
excluded_dates Son las fechas excluidas del análisis. Incluye las fechas excluidas de la configuración del análisis de forma manual por el usuario y las fechas de los valores atípicos de la fase de análisis (si se configuraron para quitarse automáticamente).
quality_check_result Es el resultado de las verificaciones de calidad de los datos realizadas en los datos de entrada.

AnalysisMetrics

Contiene métricas para un análisis de una sola celda.

@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
Atributos Descripción
lift Es la estimación puntual y los intervalos de confianza de las conversiones incrementales absolutas.
percent_lift Es el porcentaje estimado de efectividad con intervalos de confianza.
cumulative_lift Es la serie temporal de las estimaciones de efectividad de las conversiones incrementales durante el período de análisis.
counterfactual_conversions Es la serie temporal de conversiones contrafácticas. Incluye la fecha, los valores observados, los contrafácticos y los intervalos de confianza (solo para el período de prueba).
pointwise_difference Es la diferencia puntual entre las conversiones observadas y las contrafácticas. Incluye la fecha, la diferencia y los intervalos de confianza (solo el período de prueba).
icpd Son las conversiones incrementales por dólar. Equivale al ROAS incremental si se usan datos de ingresos. Se completa si hay datos de inversión disponibles.
cumulative_icpd Es la serie temporal de las estimaciones de conversiones incrementales por dólar (iCPD) durante el período de análisis. Solo se completa si hay datos de inversión disponibles.
descriptive_metrics Son las métricas descriptivas para un análisis de una sola celda. Se usan para la integración de Meridian.

Estimación

Una estimación con su intervalo de confianza.

@dataclasses.dataclass
class Estimate:
  point_estimate: float
  lower_bound: float
  upper_bound: float
  standard_deviation: float
  p_value: float
Atributos Descripción
point_estimate Es el valor estimado principal.
lower_bound Es el límite inferior del intervalo de confianza.
upper_bound Es el límite superior del intervalo de confianza.
standard_deviation Es la desviación estándar de la estimación.
p_value Es el nivel de significancia asociado con la estimación.

DescriptiveMetrics

Son las métricas descriptivas para un análisis de una sola celda.

@dataclasses.dataclass
class DescriptiveMetrics:
  estimated_bau_spend: Optional[float] = None
Atributo Descripción
estimated_bau_spend Representa la inversión estimada en condiciones normales para las ubicaciones geográficas incluidas en el análisis de esta celda (las ubicaciones geográficas de tratamiento de la celda específica más las ubicaciones geográficas de control). No incluye la inversión de otras celdas de tratamiento ni de ubicaciones geográficas no experimentales y, por lo tanto, no representa la inversión nacional total del anunciante.

analyze()

Ejecuta el análisis de efectividad.

def analyze(
    data: pd.DataFrame,
    analysis_config: AnalysisConfig,
    data_quality_check_config: QualityCheckConfig = QualityCheckConfig()
)-> AnalysisResult
Parámetros Descripción
data Es una serie temporal completa que contiene datos previos a la prueba y de la prueba para todas las ubicaciones geográficas.
analysis_config Es la configuración que define la metodología y los períodos.
data_quality_check_config Es una opción para configurar verificaciones automáticas de la calidad de los datos. De forma predeterminada, se quitan automáticamente las fechas atípicas.

Devuelve: Un objeto AnalysisResult que contiene métricas para cada celda de tratamiento.

plot_analysis()

Genera una visualización del análisis del experimento.

def plot_analysis(
    analysis_result: AnalysisResult
)
Parámetros Descripción
analysis_result Es el resultado estadístico de la función analyze().

Descripción: Produce gráficos de series temporales para el impacto contrafáctico, la diferencia puntual y la efectividad y el iCPD acumulados para visualizar el impacto incremental estimado de cada celda de tratamiento.

Módulo de calidad de los datos

Ver código fuente

QualityCheckConfig

@dataclasses.dataclass
class QualityCheckConfig:
  exclude_geos_no_response: bool = True
  exclude_outlier_dates: bool = True
Atributos Descripción
exclude_geos_no_response Determina si se deben excluir automáticamente las ubicaciones geográficas sin respuesta durante la fase de diseño. El valor predeterminado es True.
exclude_outlier_dates Determina si se deben excluir automáticamente las fechas con valores atípicos durante las fases de diseño o análisis. El valor predeterminado es True.

QualityCheckResult

@dataclasses.dataclass
class QualityCheckResult:
  quality_check_config: QualityCheckConfig
  quality_metrics: pd.DataFrame
  outlier_geos: Set[str]
  outlier_dates: Set[pd.Timestamp]
Atributos Descripción
quality_check_config Son los parámetros de configuración que se usan para la verificación de calidad.
quality_metrics Un DataFrame que contiene métricas detalladas que resultan de la verificación de calidad
outlier_geos Es el conjunto de áreas geográficas atípicas identificadas sin respuesta.
outlier_dates Es el conjunto de fechas de valores atípicos identificados que se detectaron durante la verificación de calidad.

check_design_data_quality()

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

Descripción: Verifica la calidad de los datos de entrada para la fase de diseño. Esta verificación se integra directamente en el método run_design(), lo que significa que las verificaciones de calidad de los datos se realizan automáticamente cuando se generan los diseños.

Devuelve: Un objeto QualityCheckResult.

check_analysis_data_quality()

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

Descripción: Verifica la calidad de los datos de entrada para la fase de análisis. Esta verificación se integra directamente en el método analyze(), lo que significa que las verificaciones de calidad de los datos se realizan automáticamente durante el análisis.

Devuelve: Un objeto QualityCheckResult.