データ検証チェックとデータ品質チェック

設計と分析の入力が適切であることを確認し、データエラーのリスクを軽減するため、Meridian GeoX にはプロセスをダブルチェックする機能が組み込まれています。このライブラリは、データ検証チェックとデータ品質チェックの 2 つのモジュールを使用してデータを評価します。

データチェックの種類

ライブラリがさまざまな種類のデータの問題をどのように処理するかを理解することが重要です。

  • 検証チェック: データが特定の要件に準拠していることを確認します。検証チェックが失敗すると、ライブラリは 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 と 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)