HarshikaReddyUppula/ab-test-lab

# ab-test-lab 一个用于设计、运行和**隐私保护** A/B 测试分析的轻量级 Python 工具包——专为生产级实验平台真正需要的功能而构建：准确的样本量计算、可靠的置信区间、不会因为“偷看”数据而失效的序贯检验，以及在用户级数据无法离开数据仓库时使用的差分隐私聚合。       ## 为什么会有这个项目 GitHub 上的大多数 A/B 测试“教程”仅止步于 `scipy.stats.ttest_ind`。而真正的生产级实验平台必须回答更棘手的问题： - *要检测到 1% 的提升，我实际上需要多少用户？* → 基于功效的样本量设计 - *我们昨天偷看了仪表盘并得出了结论。我们确定吗？* → 具备适当 alpha 消耗的序贯检验 - *我们可以对欧盟用户进行实验而不暴露用户级数据吗？* → 对聚合数据采用差分隐私 本工具包为上述每一项提供了简洁且经过测试的实现，并通过 notebook 展示了在公开数据集上的真实世界用法。 ## 架构 ``` flowchart LR subgraph Design D1[Sample-size calculator] D2[Power simulator] end subgraph Analyze A1[Frequentist tests] A2[Bootstrap CIs] A3[Sequential tests] end subgraph Private P1[Laplace mechanism] P2[Gaussian mechanism] P3[Private proportion test] end subgraph Scale S1[PySpark aggregations] S2[BigQuery user-level → bucketed] end D1 --> A1 D2 --> A1 A1 -.privacy noise.-> P1 A1 -.privacy noise.-> P2 S1 --> A1 S2 --> A1 ``` ## 库中包含的内容 ``` from ab_test_lab import design, analyze, private, simulate # 1. Design — 我需要多少用户？ n = design.required_sample_size_proportion( baseline_rate=0.10, mde=0.005, alpha=0.05, power=0.80 ) # 2. Analyze — 增长是多少，带有 95% 的 CI？ result = analyze.proportion_test( control_conversions=520, control_n=10_000, treatment_conversions=565, treatment_n=10_000, ) # result.lift, result.ci_lower, result.ci_upper, result.p_value # 3. Private — 相同的测试，在聚合数据上添加 (epsilon=1.0)-DP 噪声 private_result = private.private_proportion_test( control_conversions=520, control_n=10_000, treatment_conversions=565, treatment_n=10_000, epsilon=1.0, ) # private_result.lift, private_result.ci_lower, ... # 4. Simulate — 给定我实际的用户量曲线，我的功效是多少？ power = simulate.power_simulation( baseline_rate=0.10, true_lift=0.01, n_per_arm=10_000, n_sims=2_000 ) ``` ## Notebooks | # | Notebook | 展示内容 | |---|---|---| | 01 | `01_design_and_analyze.ipynb` | 端到端流程：设计实验、模拟用户、分析结果 | | 02 | `02_privacy_preserving.ipynb` | 相同的测试，但采用差分隐私。隐私/效用边界 | | 03 | `03_case_study_at_scale.ipynb` | 在 BigQuery + PySpark 中分桶处理 Criteo Uplift 数据集（约 1400 万行） | ## 技术栈 | 层级 | 工具 | | --- | --- | | 核心统计 | `scipy.stats`、`numpy`、`statsmodels` | | 差分隐私 | 自定义 Laplace/Gaussian 机制（并使用 `diffprivlib` 进行对比） | | 规模演示 | PySpark、BigQuery | | 测试 | `pytest` | | Notebooks | Jupyter、Matplotlib、Seaborn | | 打包 | `pyproject.toml`（可通过 `pip install -e .` 安装） | ## 仓库结构 ``` ab-test-lab/ ├── ab_test_lab/ # library code (importable as `ab_test_lab`) │ ├── design.py # sample size & power │ ├── analyze.py # frequentist tests & CIs │ ├── sequential.py # sequential / always-valid inference │ ├── private.py # differential privacy mechanisms │ └── simulate.py # Monte Carlo simulations ├── notebooks/ # end-to-end demonstrations ├── tests/ # pytest suite ├── pipelines/ # PySpark + BigQuery scale demos ├── docs/methodology.md # methodology deep-dive └── pyproject.toml ``` ## 快速开始 ``` git clone https://github.com/HarshikaReddyUppula/ab-test-lab.git cd ab-test-lab python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" # 运行测试 pytest # 打开 demo jupyter lab notebooks/01_design_and_analyze.ipynb ``` ## 方法论 完整说明：[docs/methodology.md](docs/methodology.md)。主题包括： - 为什么当转化率较低时，标准的双比例公式会将 *n* 低估约 10%。 - “偷看问题”以及 Pocock 与 O'Brien-Fleming 消耗函数。 - 隐私/效用权衡：ε 能带来什么，它在可检测效应方面又需要付出什么代价。 - 何时使用此方法对比 Bayesian 框架（以及何时*两者*结合使用）。 ## 路线图 - [ ] **design** — 比例 + 连续样本量，集群随机化调整 - [ ] **analyze** — Welch's t-test、双比例 z-test、bootstrap 置信区间、CUPED 方差缩减 - [ ] **sequential** — Pocock 和 O'Brien-Fleming alpha 消耗；mSPRT - [ ] **private** — Laplace + Gaussian 机制、组合计费、隐私比例测试 - [ ] **simulate** — 功效曲线、偷看数据下的假阳性率验证 - [ ] **notebooks** — 01 设计+分析、02 隐私、03 规模化（Criteo + PySpark + BigQuery） - [ ] **tests** — ≥80% 代码覆盖率；通过 `hypothesis` 对噪声机制进行基于属性的测试 - [ ] **CI** — GitHub Actions：在 PR 上运行 ruff + pytest ## License MIT — 随意使用，尽情 fork，放心发布。

标签：A/B测试, Python, 假设检验, 安全规则引擎, 差分隐私, 数据隐私, 无后门, 统计分析, 逆向工具