メリディアン GeoX を活用して、MMM 調整を強化する方法をご覧ください。

Meridian GeoX API リファレンス

設計モジュール

設計モジュールは、テストパラメータを指定し、過去のデータに基づいて最適化された地域分割（介入群と対照群）を生成します。以降のセクションでは、入力パラメータと出力パラメータを定義するデータクラスと、設計の生成、比較、可視化を行う主な関数について説明します。

DesignConfig

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

属性	説明
`experiment_duration`	テストの期間。`datetime.timedelta` として指定します。サポートされている単位は `weeks` と `days` です。
`experiment_types`	ホールドバック、ゴーダーク、ヘビーアップなど、テストの性質を定義します。マルチセルテストの場合、辞書を使用してセルごとに異なるタイプを割り当てることができます。それ以外の場合は、指定された単一のタイプがすべてのセルに適用されます。
`methodology`	設計の選択に使用された方法（例:`TBR`）。
`geo_assignment_rule`	`RANDOM` や `STRATIFIED_SAMPLING` など、地域を異なるグループに割り当てるために使用されるルール。
`cell_count`	介入群セルの合計数。共通の対照群を共有する複数の介入群を扱うシナリオには `cell_count > 1` を使用します。
`alpha`	テストの有意水準。デフォルト値は 0.1（信頼度 90%）です。
`power`	目標とする統計的検出力（真の効果を検出する確率）。デフォルト値は 0.8 です。
`test_type`	実行する統計的検定のタイプ（`ONE_SIDED`、`TWO_SIDED` など）。デフォルトは `TWO_SIDED` です。
`design_output_count`	返されるランク付けされた推奨設計の数。デフォルト値は 10 です。
`cost_per_incremental_conversion`	収益データが使用されている場合は、1 / 目標 iROAS と同等です。ホールドバックテスト（セル）の予算要件を推定するために使用されます。ゴーダークテストとヘビーアップテスト（セル）では省略可能で無視されます。マルチセルテストの場合、辞書を使用してホールドバックセルごとに異なる値を割り当てることができます。マルチセル設計に単一の浮動小数点数が指定されている場合、すべてのホールドバックセルに適用されます。デフォルト値は 1.0 です。

高度な設計検索パラメータ

属性	説明
`n_candidates`	高速スコアリングステップの候補数。デフォルト値は 100,000 です。
`n_ranked_candidates`	完全にスコア付けされた候補数。デフォルト値は 100 です。
`max_candidate_generation_retries`	候補生成の最大再試行回数。デフォルト値は 10 です。
`seed`	乱数ジェネレータのシード。デフォルト値は 42 です。
`slope_tolerance`	勾配チェックで許容される最大対称差。デフォルト値は 0.2 です。
`min_r2`	設計で許容される最小 R²。デフォルト値は 0.8 です。
`num_strata`	層化サンプリングの層の数。デフォルト値は 4 です。
`k_means_iterations`	k 平均法クラスタリングの反復処理の回数。デフォルト値は 10 です。

予算

単一セルの予算制約。

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

属性	説明
`budget`	テスト設計の最大予算（セルごと）。合計予算額として指定します。ホールドバックセルに指定する必要があります。
`budget_pct`	テスト設計の最大予算変更率（セルごと）。ゴーダークセルとヘビーアップセルに指定する必要があります。ゴーダークの場合は負の値、ヘビーアップの場合は正の値にする必要があります。

制約

設計アルゴリズムの任意の運用上の制約を定義します。

@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

属性	説明
`included_control_geos`	対照群に含める必要がある特定の地域。
`excluded_geos`	テスト設計から除外する特定の地域。
`excluded_dates`	テスト設計から除外する特定の日付。
`budget_constraint`	テスト設計の予算制約（セルごと）。これは、合計予算額または予算変更率が該当します。マルチセルテストの場合、辞書を使用してセルごとに異なる値を割り当てることができます。それ以外の場合は、指定された単一の値がすべてのセルに適用されます。ゴーダークセルに予算変更率が指定されていない場合、デフォルト値は -100% です。ヘビーアップセルのデフォルト値は 100% です。
`max_conversions_percent`	介入群に許可される最大コンバージョン数。マルチセル設計の場合、この割合はすべての介入群セルの合計を指します。デフォルト値は 0.3 です。

DesignSet

生成されたテスト設計とその比較指標のコレクション。

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

属性	説明
`designs`	個々の `Design` オブジェクトに設計 ID をマッピングする辞書。
`design_metrics`	ランク付けされた設計と、それに関連する指標（MDE や予算など）を含む `DataFrame`。

設計指標の DataFrame 列

列	説明
`design_id`	設計の固有識別子。
`cell`	介入群のセル ID。
`design_methodology`	設計に使用される手法。
`r2`	サンプル外 R²。初期トレーニングフェーズで使用されなかった過去のデータでモデルの予測精度をテストして計算されます。
`mde`	最小検出可能効果（MDE）は、テストで統計的に統計的有意性を検出できる、主要 KPI の最小の伸びを表します。MDE が小さいほど、感度の高い設計であることを示します。
`mde_abs`	必要な増分コンバージョンの最小値。`mde` * `treatment_conversion_volume` として計算されます。
`p_value (AA)`	既知の介入群がない期間にモデルを適用した、頑健性チェックの結果。p 値が有意水準（通常は 0.1）より大きい場合は、設計が A/A テストに合格し、偽陽性が発生しにくいことを示します。
`budget`	マーケティング費用合計額に対して必要な変更の予測値。ゴーダークまたはヘビーアップの調査では、費用データとユーザーが入力した予算変更率に基づいて計算されます。ホールドバックの調査では、CpIC を使用して必要な予算を推定します。
`design_implied_cpic`	設計上想定される増分コンバージョン単価（CpIC）。予算を、必要な増分コンバージョンの最小値で割って算出します。
`treatment_conversions_pct`	介入群のコンバージョン率。
`treatment_geo_count`	介入群の地域数。

設計

地域割り当てや使用された構成など、単一のテスト設計を表します。

@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'

属性	説明
`designs`	介入群セル ID をそれぞれの `PerCellDesign` 結果にマッピングする辞書。
`control_geos`	対照群に割り当てられた地域のセット。
`excluded_geos`	テストから除外される地域のセット。ユーザーが手動で除外した地域と、データ品質チェックで検出された外れ値の地域（自動的に削除されるように設定されている場合）が含まれます。
`excluded_dates`	設計から除外される日付。ユーザーが手動で除外した日付と、データ品質チェックで検出された外れ値の日付（自動的に削除されるように設定されている場合）が含まれます。
`design_config`	この特定の設計の作成に使用される `DesignConfig` オブジェクト。
`constraints`	設計検索中に適用される `Constraints` オブジェクト。
`quality_check_result`	入力データに対して実行されるデータ品質チェックの結果。
`geo_stratum_labels`	各地域の階層ラベル。地域名の順で並べられます。これは分析に使用されます。
`data`	設計に使用されるデータ。これは分析に使用されます。

メソッド	説明
`export_to_json`	設計オブジェクトを JSON ファイルにエクスポートします。
`load_from_json`	JSON ファイルから設計オブジェクトを読み込みます。

PerCellDesign

設計内の単一の介入群セルに対する特定の割り当てと統計指標が含まれます。

@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

属性	説明
`treatment_geos`	このセルの介入群に割り当てられた地域のセット。
`minimum_detectable_effect`	設計で検出できる最小効果量。
`design_implied_cpic`	設計上想定される増分コンバージョン単価（CpIC）。予算を、必要な増分コンバージョンの最小値で割って算出します。
`p_value`	テストの開始前に介入群と対照群のバランスが取れていることを確認する A/A テストの有意水準。
`budget`	テストパラメータに基づく、この介入群セルの推定費用。
`counterfactual_conversions`	反事実的なコンバージョンの時系列。日付、観測されたコンバージョン数、反事実的コンバージョン数が含まれます。これはプロットに使用されます。

run_design()

潜在的なテスト設計を生成してランク付けするための主な関数。

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

パラメータ	説明
`data`	`date`、`location`、`conversions` と、省略可能な `spend` を含む過去のテスト前時系列。
`design_config`	テスト設計のパラメータ。
`constraints`	テスト設計の運用上の制約。
`data_quality_check_config`	自動データ品質チェックを構成するオプション。デフォルトでは、応答のない地域と外れ値の日付が自動的に削除されます。

戻り値: ランク付けされた Design オブジェクトのリストと、関連する指標（MDE や予算など）を含む DesignSet オブジェクト。

compare_designs()

異なる手法、割り当てルール、構成にわたって複数のテスト設計を比較します。

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

パラメータ	説明
`data`	過去のテスト前時系列データ。
`design_requirements`	タプルのリスト。各タプルには `DesignConfig` オブジェクトと `Constraints` オブジェクトが含まれます。
`design_output_count`	返す設計の数。デフォルト値は 10 です。

戻り値: 指定されたすべての構成のランク付けされた設計を含む、統合された DesignSet。

concat_design_reports()

複数の DesignSet オブジェクトを、ランク付けされた単一の DesignSet に連結します。

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

パラメータ	説明
`design_sets`	統合する `DesignSet` オブジェクトのリスト。
`design_output_count`	統合されたセットで返される上位設計の数。デフォルト値は 10 です。

戻り値: 指標に基づいて再ランク付けされた、すべての設計を含む単一の DesignSet オブジェクト。

plot_design()

特定の設計の視覚的な表現を生成します。

def plot_design(
    design_to_plot: Design
)

パラメータ	説明
`design_to_plot`	可視化する特定の `Design` オブジェクト。

説明: コンバージョンの時系列データをプロットし、介入群と反事実データを比較して、地域分割の有効性を可視化します。

分析モジュール

ソースを表示

分析モジュールは、反事実モデリングと堅牢な推論を使用して、完了したテストの増分効果を計算します。以降のセクションでは、入出力パラメータを定義するデータクラスと、テスト結果レポートを生成して可視化する主な関数について説明します。

AnalysisConfig

完了した GeoX 調査のリフト値分析を実行するために必要なパラメータ。

@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

属性	説明
`design`	設計フェーズで使用される特定の地域分割と来歴情報。
`analysis_start_date`	分析の開始日。
`analysis_end_date`	分析の終了日。クールダウン期間が含まれる場合があります。
`pretest_end_date`	テスト前期間の終了日。指定しない場合、テスト前期間は `analysis_start_date` より前のすべての日付になります。
`excluded_dates`	外れ値の日など、分析から除外する特定の日付。
`alpha`	有意水準。省略すると、設計構成から推測されます。
`test_type`	実施する統計的検定の種類。指定しない場合、設計構成から推測されます。

高度な分析パラメータ

属性	説明
`n_placebo_candidates`	選択前に生成される初期プラセボ候補の数。デフォルト値は 100,000 です。
`n_top_placebos`	分析に使用される上位の有効プラセボ候補の数。デフォルト値は 500 です。
`min_placebo_r2`	プラセボ設計を分析用に保持するために必要な、サンプル外の決定係数の最小値。デフォルト値は 0.6 です。
`min_placebo_count_warning`	有効なプラセボ候補の数がこの値を下回ると、警告がログに記録されます。デフォルト値は 100 です。
`min_placebo_count_error`	有効なプラセボ候補の数がこの値を下回ると、エラーが発生します。デフォルト値は 10 です。

AnalysisResult

すべてのセルにわたる GeoX テストの集計された統計出力が含まれます。

@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

属性	説明
`results`	各介入群セルを対応する `AnalysisMetrics` オブジェクトにマッピングする辞書。
`analysis_config`	分析に使用される構成。
`excluded_geos`	分析から除外される地域。設計フェーズで除外されたすべての地域が含まれます。
`excluded_dates`	分析から除外される日付。ユーザーが分析構成から手動で除外した日付と、分析フェーズの外れ値の日付（自動的に削除されるように構成されている場合）が含まれます。
`quality_check_result`	入力データに対して実行されるデータ品質チェックの結果。

AnalysisMetrics

単一セル分析の指標が含まれます。

@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

属性	説明
`lift`	絶対増分コンバージョンの点推定値と信頼区間。
`percent_lift`	信頼区間を含む推定リフト率。
`cumulative_lift`	分析期間におけるコンバージョンリフトの推定増分値の時系列。
`counterfactual_conversions`	反事実的なコンバージョンの時系列。日付、観測値、反事実、信頼区間（テスト期間のみ）が含まれます。
`pointwise_difference`	観測されたコンバージョンと反事実的なコンバージョンのポイントワイズ差分。日付、差分、信頼区間（テスト期間のみ）が含まれます。
`icpd`	1 ドルあたりの増分コンバージョン。収益データが使用されている場合は、iROAS と同等です。費用データが利用可能な場合に入力されます。
`cumulative_icpd`	分析期間における 1 ドルあたりの増分コンバージョン（iCPD）の推定値の時系列。費用データが利用可能な場合にのみ入力されます。
`descriptive_metrics`	単一セル分析の記述指標。これは、メリディアンの統合に使用されます。

推定

信頼区間を含む推定値。

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

属性	説明
`point_estimate`	メインの推定値。
`lower_bound`	信頼区間の下限値です。
`upper_bound`	信頼区間の上限値です。
`standard_deviation`	推定値の標準偏差。
`p_value`	推定値に関連付けられた有意水準。

DescriptiveMetrics

単一セル分析の記述指標。

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

属性	説明
`estimated_bau_spend`	このセルの分析に含まれる地域（特定のセルの介入地域と対照地域）の推定 BAU 費用を表します。他の介入群セルやテスト対象外の地域での費用は含まれないため、広告主様の国内での総費用を表すものではありません。

analyze()

リフト分析を実行します。

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

パラメータ	説明
`data`	すべての地域のテスト前データとテストデータの両方を含む完全な時系列。
`analysis_config`	手法と期間を定義する構成。
`data_quality_check_config`	自動データ品質チェックを構成するオプション。デフォルトでは、外れ値の日付が自動的に削除されます。

戻り値: 各介入群セルの指標を含む AnalysisResult オブジェクト。

plot_analysis()

テスト分析の可視化を生成します。

def plot_analysis(
    analysis_result: AnalysisResult
)

パラメータ	説明
`analysis_result`	`analyze()` 関数からの統計出力。

説明: 反事実、ポイントワイズ差分、累積リフト、累積 iCPD の時系列プロットを生成し、各介入群セルの推定増分効果を可視化します。

データ品質モジュール