数据验证和质量检查

为了确保您的设计和分析输入准确可靠并降低数据错误风险，Meridian GeoX 内置了多项功能，可对您的操作流程进行检查。该库通过两个独立的模块来评估您的数据：数据验证检查和数据质量检查。

数据检查的类型

请务必了解该库如何处理不同类型的数据问题：

  • 校验检查：这些检查可确保您的数据符合特定要求。如果校验检查未通过，该库将抛出 ValueError 并中断执行。

  • 质量检查：这些检查旨在识别可能损害结果质量的异常情况，但它们并不会中断代码的运行。相反，它们会将警告消息记录到控制台，并在结构化的 QualityCheckResult 对象中返回详细信息。

基础校验检查

在调用特定算法进行处理之前，该库会首先对所有输入数据进行基础校验：

  • 架构合规性：数据必须包含 date（不得为 null）、location（非空字符串且不得为 null）以及 conversions（不得为 null）。若提供了 spend，则其值必须为非负数且不得为 null。
  • 正向转化次数：整个数据集中 conversions 列的总和必须严格大于 0。
  • 数据粒度：数据必须以天为单位。系统不支持每周数据模式，此类模式将被屏蔽。

设计阶段检查

运行 geox.run_design() 时，该库会评估您的测试前数据，以确保能够生成具有足够统计功效的研究候选集。

校验检查

在设计阶段，系统会执行以下校验检查：

  • 测试前数据长度：数据中包含的唯一日期数量必须至少为 experiment_duration 的 3 倍。
  • 地理区域可用性：排除用户指定的地理区域后，剩余的地理区域池必须至少包含 2 * (cell_count + 1) 个地理区域，其中 cell_count 为实验组单元的数量。
  • 限制条件重叠：排除的地理区域不得与强制包含的对照组地理区域重叠。
  • Alpha 和功效范围：alpha 和 power 的值都必须严格介于 0 和 1 之间。
  • 特定实验要求：根据您指定的实验类型，该库会强制执行严格的数据和参数要求：
    • GO_DARK 和 HEAVY_UP：您的数据集必须包含一个每日 spend 列。对于单一单元研究或多单元研究中的第一个单元，要求提供名为 spend 或 spend_cell_1 的列。对于后续单元，要求一个对应的列（例如 spend_cell_2）。
    • HOLDBACK：不需要支出时间序列数据。不过，您必须确保单位增量转化费用 (cost_per_incremental_conversion) 参数大于 0。注意：默认 cost_per_incremental_conversion 为 1.0，因此只有在您明确将其设置为 0 或负数，或者在传递多单元字典时省略了特定预留对照单元时，此校验才会失败。
  • 最大转化次数：max_conversions_percent 必须严格小于 0.5。

质量检查

在设计阶段，需要进行以下质量检查：

  • 预算配置警告：如果您的 constraints 与实验类型不匹配，该库会发出警告。对于 GO_DARK 或 HEAVY_UP，系统要求提供百分比变化 (budget_pct)，若提供了绝对预算，则会发出警告。对于 HOLDBACK，则要求提供绝对预算，如果提供百分比，则会发出警告。
  • 识别离群值：该库会检查是否存在支出大于 0 但没有转化记录的地理区域。默认情况下 (exclude_geos_no_response=True)，库会自动从候选分块中排除这些分块。
  • 数据稀疏性：如果缺失转化数据的天数占比超过 30%，或者有效GO_DARK或HEAVY_UP实验组缺失支出数据的天数超过 30%，系统会记录警告。如果总体零转化率超过 50%，系统也会记录警告。
  • 高基数：如果唯一地理区域数量超过 500，系统会记录警告。这是因为地理区域之间的人口流动会导致粒度过细，通常会干扰提升效果估算的准确性。
  • 重复条目：如果同一日期和地点存在多个条目，系统会记录警告并自动汇总这些条目。

分析阶段检查

使用 geox.analyze() 执行测试后分析时，该库会强制要求分析过程与原始的测试前研究设计保持严格同步。

校验检查

在分析阶段，系统会执行以下校验检查：

  • 地理区域集合一致性：您上传的分析数据集中的地理区域，必须与设计阶段确定的对照组和实验组地理区域（移除排除的地理区域后）的并集完全一致。
  • 测试前阶段时长：分析数据中的测试前阶段时长必须至少为 experiment_duration 的 3 倍。
  • 不重叠：测试前阶段结束日期（如果已设置）必须严格早于分析开始日期。

质量检查

在分析过程中，该库会运行以下质量检查，并将其评估范围专门限定在测试前阶段，以避免处理后偏差：

  • 识别离群值：该库会检查是否存在支出大于 0 但没有转化记录的地理区域。
  • 数据稀疏性：如果缺失转化数据的天数占比超过 30%，或者有效GO_DARK或HEAVY_UP实验组缺失支出数据的天数超过 30%，系统会记录警告。如果总体零转化率超过 50%，系统也会记录警告。
  • 高基数：如果唯一地理区域数量超过 500，系统会记录一条警告消息。
  • 重复条目：如果同一日期和地点存在多个条目，系统会记录警告并自动汇总这些条目。

配置和查看质量检查

您可以通过 QualityCheckConfig 对象来管理自动过滤行为，并通过 QualityCheckResult 对象查看评估结果。

如需查看参数、默认阈值和返回的数据类型的完整列表，请参阅 API 参考文档中的数据质量模块。

以下示例演示了如何配置自动过滤行为：

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