Validación de datos y verificaciones de calidad

Para garantizar que tus entradas de diseño y análisis sean sólidas y reducir los riesgos de errores en los datos, Meridian GeoX incluye funciones integradas para que verifiques tu proceso. La biblioteca evalúa tus datos usando dos módulos distintos: verificaciones de validación de los datos y verificaciones de calidad de los datos.

Tipos de verificaciones de datos

Es importante comprender cómo la biblioteca gestiona los diferentes tipos de problemas de datos:

• Verificaciones de validación: Estas verificaciones garantizan que tus datos cumplan con ciertos requisitos. Si falla una verificación de validación, la biblioteca genera un ValueError y detiene la ejecución.

• Verificaciones de calidad: Estas verificaciones identifican anomalías que podrían comprometer la calidad de los resultados, pero no impiden que se ejecute el código. En su lugar, registran mensajes de advertencia en la consola y devuelven los detalles en un objeto QualityCheckResult estructurado.

Verificaciones de validación de referencia

Antes de continuar con algoritmos específicos, la biblioteca ejecuta validaciones fundamentales en cualquier dato de entrada:

• Cumplimiento del esquema: Los datos deben contener date (sin valores nulos), location (cadenas no vacías y sin valores nulos) y conversions (sin valores nulos). Si se proporciona spend, los valores deben ser no negativos y no nulos.
• Conversiones positivas: La suma total de la columna conversions en todo el conjunto de datos debe ser estrictamente mayor que 0.
• Nivel de detalle de los datos: Los datos deben seguir un patrón diario. Los patrones semanales no se admiten y están bloqueados.

Verificaciones de la fase de diseño

Cuando ejecutas geox.run_design(), la biblioteca evalúa tus datos previos a la prueba para garantizar que pueda generar candidatos de estudio que tienen un alto poder estadístico.

Verificaciones de validación

Durante la fase de diseño, se aplican las siguientes verificaciones de validación:

• Duración de los datos previos a la prueba: Los datos deben contener fechas únicas equivalentes a, al menos, tres veces el valor de experiment_duration.
• Disponibilidad de ubicaciones geográficas: Después de quitar las ubicaciones geográficas excluidas por el usuario, el grupo restante debe contener, al menos, 2 * (cell_count + 1) ubicaciones geográficas, donde cell_count es la cantidad de celdas de tratamiento.
• Superposiciones de restricciones: Las ubicaciones geográficas excluidas no deben superponerse con las de control, que se deben incluir de forma obligatoria.
• Límites alfa y potencia: Los valores de alpha y power deben estar estrictamente entre 0 y 1.
• Requisitos específicos del experimento: Según el tipo de experimento que designes, la biblioteca aplica requisitos estrictos de datos y parámetros:
  • GO_DARK y HEAVY_UP: Tu conjunto de datos debe contener una columna spend diaria. Para un estudio de una sola celda o la primera celda de un estudio de varias celdas, se espera una columna llamada spend o spend_cell_1. Para las celdas posteriores, se espera una columna correspondiente (por ejemplo, spend_cell_2).
  • HOLDBACK: No se requieren los datos de series temporales de inversión. Sin embargo, debes asegurarte de que el parámetro de costo por conversión incremental (cost_per_incremental_conversion) sea mayor que 0. Nota: El valor predeterminado de cost_per_incremental_conversion es 1.0, por lo que esta validación solo falla si lo configuras de forma explícita como 0 o un valor negativo, o si omites una celda de aislamiento específica cuando pasas un diccionario de varias celdas.
• Max. conversiones: max_conversions_percent debe ser estrictamente menor que 0.5.

Verificaciones de calidad

Durante la fase de diseño, se aplican las siguientes verificaciones de calidad:

• Advertencias de configuración del presupuesto: La biblioteca te advierte si tus constraints no se alinean con tu tipo de experimento. Para GO_DARK o HEAVY_UP, se espera un cambio porcentual (budget_pct) y se muestra una advertencia si se proporciona un presupuesto absoluto. En el caso de HOLDBACK, se espera un presupuesto absoluto y se muestra una advertencia si se proporciona un porcentaje.
• Aislar los valores atípicos: La biblioteca verifica si hay ubicaciones geográficas que tienen una inversión superior a 0, pero que no registran conversiones. De forma predeterminada (exclude_geos_no_response=True), la biblioteca las excluye automáticamente de las divisiones candidatas.
• Dispersión de los datos: Se registran advertencias si la fracción de días de conversiones perdidas supera el 30% o si los días de inversión faltantes superan el 30% para las celdas de tratamiento activas de GO_DARK o HEAVY_UP. También se registra una advertencia si las conversiones nulas generales superan el 50%.
• Cardinalidad alta: Se registra una advertencia si el recuento de ubicaciones geográficas únicas es mayor que 500, ya que un nivel de detalle excesivo suele contaminar las estimaciones de efectividad debido al flujo de población entre las ubicaciones geográficas.
• Entradas duplicadas: Si existen varias entradas para la misma fecha y ubicación, se registra una advertencia y las entradas se agregan automáticamente.

Verificaciones de la fase de análisis

Cuando se ejecuta un análisis después de la prueba con geox.analyze(), la biblioteca aplica una sincronización estricta con el diseño original del estudio previo a la prueba.

Verificaciones de validación

Durante la fase de análisis, se aplican las siguientes verificaciones de validación:

• Coherencia del conjunto de ubicaciones geográficas: Las ubicaciones de tu conjunto de datos de análisis subido deben coincidir con la unión exacta de las ubicaciones geográficas de control y tratamiento establecidas (después de quitar las ubicaciones geográficas excluidas) durante la fase de diseño.
• Duración del período previo a la prueba El período previo a la prueba de tus datos de análisis debe ser de, al menos, tres veces experiment_duration.
• Sin superposición: La fecha de finalización del período previo a la prueba (si se establece) debe ser estrictamente anterior a la fecha de inicio del análisis.

Verificaciones de calidad

Durante el análisis, la biblioteca ejecuta las siguientes verificaciones de calidad, lo que limita su evaluación específicamente al período previo a la prueba para evitar el sesgo posterior al tratamiento:

• Aislar los valores atípicos: La biblioteca verifica si hay ubicaciones geográficas que tienen una inversión superior a 0, pero que no registran conversiones.
• Dispersión de los datos: Se registran advertencias si la fracción de días de conversiones perdidas supera el 30% o si los días de inversión faltantes superan el 30% para las celdas de tratamiento activas de GO_DARK o HEAVY_UP. También se registra una advertencia si las conversiones nulas generales superan el 50%.
• Cardinalidad alta: Se registra una advertencia si el recuento de ubicaciones geográficas únicas es mayor que 500.
• Entradas duplicadas: Si existen varias entradas para la misma fecha y ubicación, se registra una advertencia y las entradas se agregan automáticamente.

Configura y visualiza las verificaciones de calidad

Puedes controlar los comportamientos de filtrado automatizado usando el objeto QualityCheckConfig y ver los resultados de la evaluación usando el objeto QualityCheckResult.

Para obtener una lista completa de los parámetros, los umbrales predeterminados y los tipos de datos devueltos, consulta el módulo de calidad de los datos en la referencia de la API.

En el siguiente ejemplo, se muestra cómo configurar los comportamientos de filtrado automático:

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