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 設計で許容される最小 R2。デフォルト値は 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 サンプル外 R2。初期トレーニング フェーズで使用されなかった過去のデータでモデルの予測精度をテストして計算されます。
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 の時系列プロットを生成し、各介入群セルの推定増分効果を可視化します。

データ品質モジュール

ソースを表示

QualityCheckConfig

@dataclasses.dataclass
class QualityCheckConfig:
  exclude_geos_no_response: bool = True
  exclude_outlier_dates: bool = True
属性 説明
exclude_geos_no_response 設計フェーズで、応答のない地域を自動的に除外するかどうかを指定します。デフォルトは True です。
exclude_outlier_dates 設計フェーズまたは分析フェーズで外れ値の日付を自動的に除外するかどうかを指定します。デフォルトは True です。

QualityCheckResult

@dataclasses.dataclass
class QualityCheckResult:
  quality_check_config: QualityCheckConfig
  quality_metrics: pd.DataFrame
  outlier_geos: Set[str]
  outlier_dates: Set[pd.Timestamp]
属性 説明
quality_check_config 品質チェックに使用される構成設定。
quality_metrics 品質チェックの結果として得られた詳細な指標を含む DataFrame。
outlier_geos 応答がない、特定された外れ値の地域のセット。
outlier_dates 品質チェック中に検出された外れ値の日付のセット。

check_design_data_quality()

def check_design_data_quality(
    data: pd.DataFrame,
    design_config: DesignConfig,
    quality_check_config: QualityCheckConfig
) -> QualityCheckResult

説明: 設計フェーズの入力データの品質をチェックします。このチェックは run_design() メソッドに直接統合されているため、設計の生成時にデータ品質チェックが自動で実行されます。

戻り値: QualityCheckResult オブジェクト。

check_analysis_data_quality()

def check_analysis_data_quality(
    data: pd.DataFrame,
    analysis_config: AnalysisConfig,
    quality_check_config: QualityCheckConfig
) -> QualityCheckResult

説明: 分析フェーズの入力データの品質を確認します。このチェックは analyze() メソッドに直接統合されているため、分析中にデータ品質チェックが自動で実行されます。

戻り値: QualityCheckResult オブジェクト。