Validação de dados e verificações de qualidade

Para garantir que as entradas de projeto e análise sejam sólidas e reduzir os riscos de erros de dados, o Meridian GeoX tem recursos integrados para verificar seu processo. A biblioteca avalia seus dados usando dois módulos distintos: verificações de validação de dados e verificações de qualidade de dados.

Tipos de verificações de dados

É importante entender como a biblioteca lida com diferentes tipos de problemas de dados:

  • Verificações de validação garantem que os dados atendam a determinados requisitos. Se uma verificação de validação falhar, a biblioteca vai gerar um ValueError e interromper a execução.

  • Verificações de qualidade: identificam anomalias que podem comprometer a qualidade do resultado, mas não impedem a execução do código. Em vez disso, elas registram mensagens de aviso no console e retornam detalhes em um objeto QualityCheckResult estruturado.

Verificações de validação de valor de referência

Antes de prosseguir para algoritmos específicos, a biblioteca executa validações fundamentais em todos os dados de entrada:

  • Conformidade com o esquema: os dados precisam conter date (sem nulos), location (strings não vazias e sem nulos) e conversions (sem nulos). Se spend for fornecido, os valores não poderão ser negativos nem nulos.
  • Conversões positivas: a soma total da coluna conversions no conjunto de dados precisa ser estritamente maior que 0.
  • Granularidade dos dados: os dados precisam seguir um padrão diário. Padrões semanais não são compatíveis e são bloqueados.

Verificações da fase de projeto

Quando você executa geox.run_design(), a biblioteca avalia os dados do pré-teste para garantir que ela possa gerar candidatos de estudo com boa capacidade.

Verificações de validação

As seguintes verificações de validação se aplicam durante a fase de projeto:

  • Duração dos dados de pré-teste: os dados precisam conter datas únicas iguais a pelo menos três vezes o experiment_duration.
  • Disponibilidade de regiões: depois de remover as regiões excluídas pelo usuário, o pool restante precisa conter pelo menos 2 * (cell_count + 1) regiões, em que cell_count é o número de células de tratamento.
  • Sobreposições de restrições: as regiões geográficas excluídas não podem se sobrepor às regiões de controle que precisam ser incluídas.
  • Limites de alfa e potência: os valores de alpha e power precisam estar estritamente entre 0 e 1.
  • Requisitos específicos do experimento: dependendo do tipo de teste designado, a biblioteca aplica requisitos rigorosos de dados e parâmetros:
    • GO_DARK e HEAVY_UP: seu conjunto de dados precisa conter uma coluna diária spend. Para um estudo de célula única ou a primeira célula em um estudo com várias delas, ele espera uma coluna chamada spend ou spend_cell_1. Para as células seguintes, ele espera uma coluna correspondente (por exemplo, spend_cell_2).
    • HOLDBACK: os dados de série temporal de gastos não são obrigatórios. No entanto, é preciso garantir que o parâmetro de custo por conversão incremental (cost_per_incremental_conversion) seja maior que 0. Observação: o cost_per_incremental_conversion padrão é 1,0. Portanto, essa validação só falha se você o definir explicitamente como 0 ou negativo ou se omitir uma célula de retenção específica ao transmitir um dicionário com várias delas.
  • Max. conversões: o max_conversions_percent precisa ser estritamente menor que 0,5.

Verificações de qualidade

As seguintes verificações de qualidade se aplicam durante a fase de projeto:

  • Avisos de configuração de orçamento: a biblioteca avisa se os constraints não estiverem alinhados com o tipo de experimento. Para GO_DARK ou HEAVY_UP, ela espera uma mudança percentual (budget_pct) e avisa se um orçamento absoluto é fornecido. Para HOLDBACK, ela espera um orçamento absoluto e avisa se uma porcentagem é fornecida.
  • Isolamento de outliers: a biblioteca verifica as regiões geográficas que têm gastos maiores que 0, mas nenhuma conversão registrada. Por padrão (exclude_geos_no_response=True), a biblioteca as exclui automaticamente das divisões candidatas.
  • Esparsidade de dados: os avisos são registrados se a fração de dias de conversão ausentes exceder 30% ou se os dias de gasto ausentes excederem 30% para células de tratamento GO_DARK ou HEAVY_UP ativas. Um aviso também será registrado se o total de conversões zero exceder 50%.
  • Alta cardinalidade: um aviso será registrado se a contagem geográfica exclusiva exceder 500, já que a granularidade excessiva geralmente pode contaminar as estimativas de lift devido ao fluxo populacional entre as regiões.
  • Entradas duplicadas: se houver várias entradas para a mesma data e local, um aviso será registrado e as entradas serão agregadas automaticamente.

Verificações da fase de análise

Ao executar a análise pós-teste usando geox.analyze(), a biblioteca impõe uma sincronização rigorosa com o projeto original do estudo pré-teste.

Verificações de validação

As seguintes verificações de validação se aplicam durante a fase de análise:

  • Consistência do conjunto geográfico: os locais no conjunto de dados de análise enviado precisam ser os mesmos da união exata das regiões de controle e de tratamento estabelecidas (após a remoção das regiões excluídas) durante a fase de projeto.
  • Duração do pré-teste: esse período nos dados de análise precisa ter uma duração de pelo menos três vezes o experiment_duration.
  • Sem sobreposição: a data de término do pré-teste (se definida) precisa ser estritamente anterior à data de início da análise.

Verificações de qualidade

Durante a análise, a biblioteca executa as seguintes verificações de qualidade, limitando a avaliação especificamente ao período de pré-teste para evitar o viés pós-tratamento:

  • Isolamento de outliers: a biblioteca verifica as regiões geográficas que têm gastos maiores que 0, mas nenhuma conversão registrada.
  • Esparsidade de dados: os avisos são registrados se a fração de dias de conversão ausentes exceder 30% ou se os dias de gasto ausentes excederem 30% para células de tratamento GO_DARK ou HEAVY_UP ativas. Um aviso também será registrado se o total de conversões zero exceder 50%.
  • Alta cardinalidade: um aviso será registrado se a contagem geográfica única exceder 500.
  • Entradas duplicadas: se houver várias entradas para a mesma data e local, um aviso será registrado e as entradas serão agregadas automaticamente.

Configurar e visualizar verificações de qualidade

É possível controlar os comportamentos de filtragem automatizada usando o objeto QualityCheckConfig e conferir os resultados da avaliação usando o objeto QualityCheckResult.

Para ver uma lista completa de parâmetros, limites padrão e tipos de dados retornados, consulte o módulo de qualidade de dados na referência da API.

O exemplo a seguir demonstra como configurar comportamentos de filtragem automática:

# 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)