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-means 聚类的迭代次数。默认值为 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 将设计 ID 映射到各个 Design 对象的字典。
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 用于配置自动数据质量检查的选项。默认设置为自动移除无响应的地理区域和离群日期。

返回：一个 DesignSet 对象，其中包含排序后的 Design 对象列表以及 MDE 和预算等相关指标。

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 保留安慰剂设计以供分析所需的最低样本外 R 平方值。默认值为 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 每美元带来的增量转化次数。如果使用收入数据，则等同于 iROAS。若有支出数据，则会自动填充。
cumulative_icpd 分析期内每美元增量转化次数 (iCPD) 估算值的时间序列数据。仅在有支出数据时自动填充。
descriptive_metrics 单一单元分析的描述性指标。该数据用于 Meridian 集成。

估算

估算值及其置信区间。

@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 对象。