moon-experiment

moon-experiment 是一个面向 MoonBit 的实验分析与指标工程库。它将实验设计、因果估计、用户行为分析、时间序列、隐私统计、数据质量、发布决策和可复现报告组织成一套可组合的纯 MoonBit API，适合产品实验、增长实验和数据管道中的本地分析任务。

项目定位

项目为 MoonBit 应用提供从实验设计到分析交付的基础能力：

• 让实验设计、功效分析和样本量估计可以在 MoonBit 工具链内完成。
• 为比例、均值、计数、比率和分层指标提供可解释的统计结果。
• 将 SRM、缺失、异常、漂移和护栏检查放在正式分析之前。
• 通过确定性模拟、结构化报告和固定 checksum 支持可复现研发。

项目遵循 Apache-2.0 许可，面向可复用的科学计算和实验分析场景。

核心能力

• 样本量、功效、分配比例和敏感性分析。
• Welch、合并方差、单样本、配对、卡方、置换和 bootstrap 检验。
• Wilson、Agresti–Coull、均值、比率、风险差和相对提升置信区间。
• Cohen’s d、Hedges’ g、风险比、NNT、log odds ratio 等效应量。
• Bonferroni、Holm、Hochberg、Benjamini–Hochberg 和 Benjamini–Yekutieli 校正。
• CUPED、线性回归、分层估计、Mantel–Haenszel 和序贯分析。
• SRM、缺失率、异常率、漂移、样本量和护栏策略检查。
• 数据集清洗、确定性分流、实验生命周期、监控告警和报告渲染。
• 因果推断、倾向得分、IPW/AIPW、双重差分和协变量平衡。
• 漏斗、会话、路径、留存 cohort、复购和收入分析。
• 滚动统计、季节性分解、预测区间、变点检测、控制图和回测。
• 隐私预算、拉普拉斯/高斯机制、随机响应、贡献裁剪和小样本抑制。
• 指标目录、分组聚合、质量管线、归因模型和渐进式放量决策。
• 实验分流、曝光一致性、SRM 监测、运行编排和审计轨迹。
• 二项/连续/计数模拟，以及可复核的原生 benchmark CLI。

快速开始

安装

从 Mooncakes 安装指定版本：

moon add pla678889/moon-experiment@0.2.3

或在 moon.mod 中添加：

import {
  "pla678889/moon-experiment"
}

第一个分析

let result = @metrics.proportion_test(120, 1000, 150, 1000)
let interval = @metrics.wilson_interval(120, 1000)
println(result.p_value.to_string())
println(interval.low().to_string())

一个完整实验流程通常是：先用 dataset 验证和整理观测，再用 guardrail 检查分流与数据质量，然后使用 metrics 或 sequential 分析效果，最后由 report 固化结果。

可运行的最小样例

仓库提供一个不依赖外部数据的 quickstart，可直接运行两组比例指标检验：

moon run examples/quickstart --target native

该样例会输出 p_value 和差异的置信区间，源码位于 examples/quickstart/main.mbt。

CLI

仓库提供一个可重复的 benchmark CLI：

moon run cmd/benchmark --target native

程序输出 CSV，包含 workload、输入规模、迭代次数、操作数和 checksum。它适合在本地或 CI 中做算法回归检查；真实机器的输入、输出和五次实测耗时记录在 docs/benchmark-results.md。

架构

包	职责
core	描述统计、在线统计量、分布函数、概率校验和随机数工具
size	样本量、功效、分配和敏感性分析
metrics	检验、效应量、置信区间、回归、重采样和多重校正
guardrail	SRM、缺失、异常、漂移、比例和护栏策略
sequential	alpha spending、mixture SPRT、e-process 和置信序列
stratified	分层均值、方差、分配和 Mantel–Haenszel 估计
dataset	观测模型、验证、清洗、确定性分配和变换
experiment	实验启动、摄入、暂停、完成、决策和流程编排
monitor	滚动统计、EWMA、CUSUM、趋势预测、告警和质量评分
simulation	二项、连续、计数数据生成与经验功效/错误率
report	结构化实验报告、Markdown/CSV 渲染和质量摘要
benchmark	workload、checksum、基线比较和汇总
causal	倾向得分、IPW/AIPW、双重差分、协变量平衡和敏感性分析
funnel	事件去重、会话化、漏斗转化、留存、路径和收入分析
timeseries	滚动统计、预测、季节性分解、变点检测、控制图和回测
privacy	隐私预算、噪声机制、随机响应、贡献裁剪和小样本抑制
decision	指标/护栏门禁、风险评分、放量阶段、回滚和审计输出
catalog	指标定义、目录注册、分组/周期聚合、快照比较和健康检查
pipeline	指标清洗、去重、插补、窗口聚合、质量评分和导出
attribution	首末触点、线性、时间衰减、位置模型和增量归因
quality	完整性、有效性、唯一性、范围、漂移、异常和数据剖析
orchestration	将指标、管线、质量和放量决策编排为一次分析运行
experimentops	实验计划、确定性分流、曝光监测、注册、诊断和审计

各包通过 moon.pkg 声明依赖；公共接口由 moon info 生成 pkg.generated.mbti，便于下游调用和 CI 一致性检查。

基准

标准 benchmark 固定输入规模为 256、迭代次数为 100，覆盖正态 CDF、描述统计、比例检验、bootstrap 和数据扫描五类 workload。每次运行都输出确定性 checksum，用于识别算法行为变化；端到端计时数据和测量口径见 docs/benchmark-results.md。

基准数据用于同一机器、同一工具链下的回归比较，不代表跨平台性能承诺，也不替代业务数据上的统计验证。

测试

推荐在项目根目录执行：

moon check --deny-warn --target all
moon test --deny-warn --target all
moon coverage analyze -- -f summary

测试覆盖核心统计、数据流、实验生命周期、监控和报告集成路径，并覆盖空输入、单样本、零分母、零方差、极端比例、无流量 SRM、重复 ID、缺失观测、短序列、无效参数和退化回归等边界条件。

CI

GitHub Actions 使用 MoonBit 官方安装脚本获取最新 stable 工具链，并在 Ubuntu、macOS、Windows 上执行：

• moon version --all 和 moon update；
• moon check --deny-warn --target all；
• moon build --deny-warn --target all；
• moon test --deny-warn --target all；
• 运行 examples/quickstart 最小样例；
• moon fmt 与 moon info 生成物一致性检查；
• Ubuntu native coverage summary。

许可证

本项目采用 Apache License 2.0。