Referência da API do Meridian GeoX

Módulo de projeto

Ver código-fonte

O módulo de projeto especifica os parâmetros do experimento e gera divisões geográficas otimizadas (tratamento x controle) com base em dados históricos. As classes de dados que definem os parâmetros de entrada e saída e as funções principais para gerar, comparar e visualizar projetos estão listadas nas seções a seguir.

DesignConfig

Uma classe de configuração que define os parâmetros principais de um experimento do 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	Descrição
experiment_duration	Duração do experimento, especificada como um datetime.timedelta. Unidades aceitas: weeks e days.
experiment_types	Define a natureza do teste, como retenção parcial, retirada de anúncios ou investimento em regiões específicas. Para experimentos com várias células, é possível atribuir tipos diferentes por célula usando um dicionário. Caso contrário, um único tipo fornecido será aplicado a todas elas.
methodology	O método escolhido para a seleção de projeto, por exemplo, TBR.
geo_assignment_rule	Regra usada para atribuir áreas geográficas a diferentes grupos, como RANDOM ou STRATIFIED_SAMPLING.
cell_count	Número total de células de tratamento. Use cell_count > 1 para cenários com vários tratamentos que compartilham um controle comum.
alpha	Nível de significância do teste. O padrão é 0,1 (90% de confiança).
power	Eficiência estatística desejada (probabilidade de detectar um efeito verdadeiro). O padrão é 0,8.
test_type	O tipo de teste estatístico a ser realizado, por exemplo, ONE_SIDED ou TWO_SIDED. O padrão é TWO_SIDED.
design_output_count	Número de projetos recomendados classificados a serem retornados. O padrão é 10.
cost_per_incremental_conversion	Equivalente a 1 / iROAS desejado se os dados de receita forem usados. Usado para estimar os requisitos de orçamento para experimentos de retenção parcial (célula). Opcional (e ignorado) para experimentos de retirada de anúncio e aumento de investimento em regiões específicas (célula). Para experimentos com várias células, é possível atribuir valores diferentes por célula de retenção usando um dicionário. Se um único ponto flutuante for fornecido para um design de várias células, ele será aplicado a todas as células de retenção. O padrão é 1,0.

Parâmetros avançados de pesquisa no projeto

Atenção: não recomendamos modificar os valores padrão dos parâmetros avançados de pesquisa no projeto.

Atributos	Descrição
n_candidates	Número de candidatos para a etapa de pontuação rápida. O padrão é 100.000.
n_ranked_candidates	Número de candidatos com pontuação completa. O padrão é 100.
max_candidate_generation_retries	Número máximo de novas tentativas de geração de candidatos. O padrão é 10.
seed	Semente do gerador de números aleatórios. O padrão é 42.
slope_tolerance	Diferença simétrica máxima permitida para verificação de inclinação. O padrão é 0,2.
min_r2	R^2 mínimo permitido para o projeto. O padrão é 0,8.
num_strata	Número de estratos para amostragem estratificada. O padrão é 4.
k_means_iterations	Número de iterações para o clustering k-means. O padrão é 10.

Orçamento

Restrição de orçamento para uma única célula.

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

Atributos	Descrição
budget	O orçamento máximo para o projeto do experimento (por célula), especificado como um valor total. Deve ser especificado para células de retenção.
budget_pct	A mudança percentual máxima do orçamento para o projeto do experimento (por célula). Deve ser especificado para células de retirada de anúncios e investimento em regiões específicas. Precisa ser negativo para retirada de anúncios e positivo para investimento em regiões específicas.

Restrições

Define restrições operacionais opcionais para o algoritmo de projeto.

@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	Descrição
included_control_geos	Áreas geográficas específicas que precisam ser incluídas no grupo de controle.
excluded_geos	Áreas geográficas específicas a serem excluídas do projeto do experimento.
excluded_dates	Datas específicas que serão deixadas de fora do projeto do experimento.
budget_constraint	A restrição de orçamento para o projeto do experimento (por célula). Pode ser um valor total de orçamento ou uma mudança percentual no orçamento. Para experimentos com várias células, é possível atribuir valores diferentes por célula usando um dicionário. Caso contrário, o valor único fornecido será aplicado a todas as células. Se a mudança percentual no orçamento não for especificada para uma célula de desativação, o valor padrão será -100%. Para a célula de aumento, o valor padrão é 100%.
max_conversions_percent	O volume máximo de conversão permitido para o grupo experimental. Para designs com várias células, essa porcentagem se refere ao total de todas as células de tratamento. O padrão é 0,3.

DesignSet

Uma coleção de projetos de experimentos gerados e suas métricas comparativas.

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

Atributos	Descrição
designs	Um dicionário que mapeia IDs de projeto para objetos Design individuais.
design_metrics	Um DataFrame que contém projetos classificados e as métricas associadas, como MDE e orçamento.

Colunas DataFrame das métricas do projeto

Coluna	Descrição
design_id	Identificador exclusivo do projeto.
cell	O ID da célula de tratamento.
design_methodology	A metodologia usada para o projeto.
r2	R^2 fora da amostra, calculado ao testar a acurácia preditiva do modelo em dados históricos não usados durante a fase de treinamento inicial.
mde	O efeito mínimo detectável (MDE, na sigla em inglês) representa o menor aumento no KPI principal que o experimento pode detectar com significância estatística. Um MDE menor indica um projeto mais sensível.
mde_abs	O número mínimo de conversões incrementais necessárias. Ele é calculado como mde * treatment_conversion_volume.
p_value (AA)	O resultado de uma verificação de robustez em que o modelo é aplicado a um período sem tratamento conhecido. Um valor-p maior que o nível de significância (normalmente 0,1) indica que o projeto passa no teste A/A e não é propenso a falsos positivos.
budget	As mudanças necessárias no gasto total projetado com marketing. Em estudos de retirada de anúncios ou investimento em regiões específicas, calculamos com base nos dados de gasto e na mudança percentual do orçamento inserida pelo usuário. Em estudos de retenção, usamos o CpIC para estimar o orçamento necessário.
design_implied_cpic	O custo por conversão incremental (CpIC) implícito no projeto, calculado como o orçamento dividido pelo número mínimo de conversões incrementais necessárias.
treatment_conversions_pct	Porcentagem de conversão do grupo experimental.
treatment_geo_count	Número de regiões geográficas no grupo experimental.

Projeto

Representa um único projeto de experimento, incluindo as atribuições geográficas e a configuração usada.

@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	Descrição
designs	Um dicionário que mapeia os IDs das células de tratamento para os respectivos resultados de PerCellDesign.
control_geos	O conjunto de áreas geográficas atribuídas ao grupo de controle.
excluded_geos	O conjunto de áreas geográficas que foram excluídas do experimento. Inclui regiões geográficas excluídas manualmente pelo usuário e regiões geográficas com outliers detectadas por verificações de qualidade de dados (se configuradas para serem removidas automaticamente).
excluded_dates	Datas excluídas do projeto. Inclui datas excluídas manualmente pelo usuário e datas de outliers detectadas por verificações de qualidade de dados (se configuradas para serem removidas automaticamente).
design_config	O objeto DesignConfig usado para criar esse projeto específico.
constraints	O objeto Constraints aplicado durante a pesquisa do projeto.
quality_check_result	Resultado das verificações de qualidade realizadas nos dados de entrada.
geo_stratum_labels	O rótulo de estrato de cada região geográfica, ordenado pelo nome da região. Ele é usado para análise.
data	Os dados usados para o projeto. São usados para análise.

Método	Descrição
export_to_json	Exporta o objeto de projeto para um arquivo JSON.
load_from_json	Carrega um objeto de projeto de um arquivo JSON.

PerCellDesign

Contém as atribuições específicas e as métricas estatísticas de uma única célula de tratamento em um projeto.

@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	Descrição
treatment_geos	O conjunto de áreas geográficas atribuídas ao grupo experimental para essa célula.
minimum_detectable_effect	O menor tamanho do efeito que pode ser detectado pelo projeto.
design_implied_cpic	O custo por conversão incremental (CpIC) implícito no projeto, calculado como o orçamento dividido pelo número mínimo de conversões incrementais necessárias.
p_value	O nível de significância de um teste A/A que verifica se os grupos de tratamento e de controle estão equilibrados antes do início do experimento.
budget	O custo estimado para essa célula de tratamento com base nos parâmetros do experimento.
counterfactual_conversions	Série temporal de conversão contrafactual. Inclui conversões observadas, contrafactuais e por data. É usada para a visualização de dados.

run_design()

A função principal para gerar e classificar possíveis projetos de experimentos.

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

Parâmetros	Descrição
data	Série temporal histórica de pré-teste que contém date, location, conversions e (opcional) spend.
design_config	Parâmetros para o projeto do experimento.
constraints	Restrições operacionais para o projeto do experimento.
data_quality_check_config	Uma opção para configurar verificações automáticas de qualidade de dados. O padrão é remover automaticamente as regiões geográficas sem resposta e as datas de outliers.

Retorna: um objeto DesignSet que contém uma lista de objetos Design classificados e métricas associadas, como MDE e orçamento.

compare_designs()

Compara vários projetos de experimentos em diferentes metodologias, regras de atribuição ou configurações.

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

Parâmetros	Descrição
data	Série temporal histórica de pré-teste.
design_requirements	Uma lista de tuplas, cada uma contendo um objeto DesignConfig e um objeto Constraints.
design_output_count	O número de projetos que serão retornados. O padrão é 10.

Retorna: um DesignSet unificado que contém os projetos classificados de todas as configurações fornecidas.

concat_design_reports()

Concatena vários objetos DesignSet em um só DesignSet.

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

Parâmetros	Descrição
design_sets	Uma lista de objetos DesignSet a serem mesclados.
design_output_count	O número de projetos principais a serem retornados no conjunto mesclado. O padrão é 10.

Retorna: um único objeto DesignSet que contém todos os projetos, reclassificados com base nas métricas.

plot_design()

Gera uma representação visual de um projeto específico.

def plot_design(
    design_to_plot: Design
)

Parâmetros	Descrição
design_to_plot	O objeto Design específico a ser visualizado.

Descrição: mostra a série temporal de conversões, comparando o grupo experimental com o contrafactual para visualizar a eficácia da divisão geográfica.

Módulo de análise

Ver código-fonte

O módulo de análise calcula o impacto incremental de um experimento concluído usando modelagem contrafactual e inferência robusta. As classes de dados que definem os parâmetros de entrada e saída e as funções principais para gerar e visualizar relatórios de experimentos estão listadas nas seções a seguir.

AnalysisConfig

Parâmetros necessários para executar uma análise de lift em um estudo GeoX que está concluído.

@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	Descrição
design	As informações específicas de divisão geográfica e procedência usadas durante a fase de projeto.
analysis_start_date	Data de início da análise.
analysis_end_date	Data de término da análise, que pode incluir um período de espera.
pretest_end_date	A data de término do período de pré-teste. Se não for informada, o período de pré-teste abrangerá todas as datas anteriores a analysis_start_date.
excluded_dates	Datas específicas a serem excluídas da análise, como dias de outliers.
alpha	Nível de significância. Se omitido, ele será inferido da configuração do projeto.
test_type	O tipo de teste estatístico a ser realizado. Se não for fornecido, ele será inferido da configuração do projeto.

Parâmetros avançados de análise

Cuidado: não é recomendável modificar os valores padrão dos parâmetros avançados de análise.

Atributos	Descrição
n_placebo_candidates	Número de candidatos a placebo iniciais gerados antes da seleção. O padrão é 100.000.
n_top_placebos	Número de candidatos a placebo principais e válidos usados para análise. O padrão é 500.
min_placebo_r2	Pontuação mínima de R ao quadrado fora da amostra necessária para que um projeto de placebo seja mantido para análise. O padrão é 0,6.
min_placebo_count_warning	Número de candidatos a placebo válidos que, em caso de valor abaixo, vai gerar um aviso. O padrão é 100.
min_placebo_count_error	Número de candidatos a placebo válidos que, em caso de valor abaixo, vai gerar um erro. O padrão é 10.

AnalysisResult

Contém a saída estatística agregada de um experimento GeoX correspondente a todas as células.

@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	Descrição
results	Um dicionário que mapeia cada célula de tratamento ao seu objeto AnalysisMetrics correspondente.
analysis_config	A configuração usada para a análise.
excluded_geos	Regiões excluídas da análise. Inclui todas as regiões excluídas durante a fase de projeto.
excluded_dates	Datas excluídas da análise. Inclui datas que o usuário excluiu manualmente da configuração de análise e datas de outliers e da fase de análise (se configuradas para serem removidas automaticamente).
quality_check_result	Resultado das verificações de qualidade de dados realizadas nos dados de entrada.

AnalysisMetrics

Contém métricas para a análise de célula única.

@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	Descrição
lift	A estimativa pontual e os intervalos de confiança para conversões incrementais absolutas.
percent_lift	O aumento percentual estimado com intervalos de confiança.
cumulative_lift	A série temporal de estimativa do aumento de conversão incremental ocorrido durante o período de análise.
counterfactual_conversions	Série temporal de conversão contrafactual. Inclui data, dados observados, dados contrafactuais e intervalos de confiança (somente período de teste).
pointwise_difference	Diferença pontual entre as conversões observadas e contrafactuais. Inclui data, diferença e intervalos de confiança (somente período de teste).
icpd	Conversão incremental por dólar. Equivalente ao iROAS se forem usados os dados de receita. Preenchido se os dados de gastos estiverem disponíveis.
cumulative_icpd	A série temporal de estimativa de conversão incremental por dólar (iCPD, na sigla em inglês) durante o período de análise. Preenchido apenas se os dados de gastos estiverem disponíveis.
descriptive_metrics	Métricas descritivas para uma análise de célula única. Atributo usado para a integração do Meridian.

Estimativa

Uma estimativa com o intervalo de confiança.

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

Atributos	Descrição
point_estimate	O valor estimado principal.
lower_bound	O limite mínimo do intervalo de confiança.
upper_bound	O limite máximo do intervalo de confiança.
standard_deviation	O desvio padrão da estimativa.
p_value	O nível de significância associado à estimativa.

DescriptiveMetrics

Métricas descritivas para uma análise de célula única.

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

Atributo	Descrição
estimated_bau_spend	Representa o gasto estimado de BAU para as regiões incluídas na análise desta célula (as regiões de tratamento e de controle específicas da célula). Não inclui gastos de outras células de tratamento nem de regiões não experimentais e, portanto, não representa o gasto nacional total do anunciante.

analyze()

Executa a análise de lift.

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

Parâmetros	Descrição
data	Série temporal completa com dados de pré-teste e de teste para todas as regiões.
analysis_config	Configuração que define a metodologia e os períodos.
data_quality_check_config	Uma opção para configurar verificações automáticas de qualidade de dados. O padrão é remover automaticamente as datas de outliers.

Retorna: um objeto AnalysisResult com métricas para cada célula de tratamento.

plot_analysis()

Gera uma visualização da análise do experimento.

def plot_analysis(
    analysis_result: AnalysisResult
)

Parâmetros	Descrição
analysis_result	A saída estatística da função analyze().

Descrição: produz gráficos de série temporal relativos à diferença pontual, contrafactual, aumento cumulativo e iCPD cumulativo para visualizar o impacto incremental estimado de cada célula de tratamento.

Módulo de qualidade de dados

Ver código-fonte

QualityCheckConfig

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

Atributos	Descrição
exclude_geos_no_response	Determina se as regiões sem resposta durante a fase de projeto serão excluídas automaticamente. O padrão é True.
exclude_outlier_dates	Determina se as datas de outliers devem ser excluídas automaticamente durante as fases de projeto ou análise. O padrão é True.

QualityCheckResult

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

Atributos	Descrição
quality_check_config	As definições de configuração usadas para a verificação de qualidade.
quality_metrics	Um DataFrame que contém métricas detalhadas resultantes da verificação de qualidade.
outlier_geos	O conjunto de áreas geográficas de outliers identificadas sem resposta.
outlier_dates	O conjunto de datas de outliers identificadas durante a verificação de qualidade.

check_design_data_quality()

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

Descrição: verifica a qualidade dos dados de entrada para a fase de projeto. Essa verificação é integrada diretamente ao método run_design(), o que significa que as verificações de qualidade de dados são realizadas automaticamente ao gerar projetos.

Retorna: um objeto QualityCheckResult.

check_analysis_data_quality()

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

Descrição: verifica a qualidade dos dados de entrada para a fase de análise. Essa verificação é integrada diretamente ao método analyze(), o que significa que as verificações de qualidade de dados são realizadas automaticamente durante a análise.

Retorna: um objeto QualityCheckResult.