科研方法¶
这一页写给植物科学研究者:DiAGRI 在一顶帐篷里怎样设计和分析实验,它给出的结论可以信到什么程度。读这一页不需要会编程,文中的代码链接只是为了让每条规则都能核对。
先说明一点:下面的方法只在模拟的 AC5 和人造数据上测试过,还没有用它做过真实实验,而且有些步骤目前没有对应的命令或按钮(见最后一节和状态与已知限制)。设计背景在架构设计文档的 4.8、6.3、6.5 节和第 9 节。
帐篷就是实验单位¶
AC5 控制的是整顶帐篷的灯、排风和循环风扇。帐篷里的每一株植物,在同一时间接受的是同一个处理。所以这些植株只是同一个实验单位里的重复观测,不是独立重复。70 % 光照下的十株植物,说明的是这顶帐篷在这几周里的情况,说明不了 70 % 光照的一般效果。
DiAGRI 把这一点写进了计算过程。做任何比较之前,research/stats.py 的 unit_table 先把同一轮、同一顶帐篷里所有植株、所有测量日的数值平均成一个值。六株植物测五天,和一株植物测一次,得到的单位值相同,独立重复数也相同(见测试)。
这对重复意味着:独立重复只能是另一顶帐篷,或者同一顶帐篷的另一轮。只有一顶帐篷时,重复要用时间来换。
单帐篷系列与区组¶
只有一顶帐篷,不同处理只能先后进行。“先做对照、再做处理”的方案,分不清差异来自处理,还是来自季节、种子批次或灯具老化。解决办法是把多轮组成一个系列,再分成区组。一个区组是相邻的几轮,每个处理在其中各出现一次。处理之间的比较在区组内部进行,因为区组内的条件最接近。
sim/fixtures.py 里的示例协议 make_protocol 要回答的问题是:70 % 光照下冠层面积的增长,是否快于 40 % 光照(对照)。它有四轮、两个区组:
| 轮次 | 区组 | 帐篷 | 处理 |
|---|---|---|---|
| 1 | 1 | tent-1 |
high(光照 70 %) |
| 2 | 1 | tent-1 |
control(光照 40 %) |
| 3 | 2 | tent-1 |
control(光照 40 %) |
| 4 | 2 | tent-1 |
high(光照 70 %) |
主要终点是 canopy_area_growth,预定的分析方法是 paired_block。每一轮都由操作员发起,见运行一轮研究。
可以复现的随机化¶
区组内各处理的先后顺序是随机的。这样谁也没法把条件更好的那几周留给某个处理,哪怕是无意的。planning/design.py 的 randomize_series 对每个区组各打乱一次处理顺序,所用的随机数发生器由协议里的种子(randomization_seed)初始化。同一个种子永远得到同一个顺序,种子 20261118 得到的正是上面这张表。
种子记录在案,任何人都可以把抽签重做一遍。check_experimental_design 做的就是这件事:协议里登记的分配和种子生成的结果不一致时,它报告 seed_mismatch。这是一条提示性的结果,不会拦下设计,但能让审阅者知道这个顺序不是由登记的随机化产生的。
有多顶帐篷时,randomize_tents 在每一轮里把处理随机分给各顶帐篷,轮次就是区组。
设计检查¶
check_experimental_design 读入一份研究协议,返回若干检查结果。除最后一项外,其余都会拦下设计。
| 检查结果 | 含义 | 例子 |
|---|---|---|
unknown_treatment |
分配里出现了协议没有定义的处理。 | |
missing_control |
对照不在处理列表里,或者从未被分配。 | |
no_replication |
某个处理的实验单位少于两个。一个单位指一顶帐篷的一轮。 | 每个处理只做一轮。 |
unbalanced_block |
区组内各处理出现的次数不相等。 | 某个区组里 high 做了两轮,control 一轮也没有。 |
confounded_with_time |
单帐篷系列里,每个处理各占连续的一段轮次。 | control、control、high、high。 |
seed_mismatch |
分配不是由登记的种子生成的。仅作提示。 |
示例协议通过检查,没有任何结果。计划 Agent 通过 check_experimental_design 工具运行这项检查。
需要多少个区组:样本量估计¶
estimate_sample_size 用正态近似计算。输入是想要检出的效应和标准差 sd。显著性水平 alpha 默认 0.05,检验效能默认 0.8。
- 设计为
paired_block时,sd是区组内差值的标准差。代码再加上小样本修正z(1 - alpha/2)² / 2,然后向上取整。结果是区组数。 - 设计为
two_group时,结果是2n向上取整,即每组的实验单位数。
结果有两个下限。任何情况下不小于 2(MIN_SAMPLE_SIZE)。paired_block 的结果还不能小于下文那种检验有可能达到 alpha 的最少区组数:alpha 为 0.05 时是 6 个区组,0.01 时是 8 个。
用这个函数算出的例子:效应 0.5、sd 1.0,需要 34 个区组。效应 100、sd 0.1,仍然需要 6 个区组,这是下限在起作用。
sd 描述的必须是轮与轮之间的差异。同一顶帐篷里株与株之间的变异不是这个数;架构文档 6.3 节说明,单帐篷的先导轮给不出它。
手算一遍估计和检验¶
假设四轮都已做完,每轮测了三株。下面的数字是为本页编的。
| 轮次 | 区组 | 处理 | 各株数值 | 单位值(均值) |
|---|---|---|---|---|
| 1 | 1 | high |
2.1、1.9、2.0 | 2.0 |
| 2 | 1 | control |
1.0、1.1、0.9 | 1.0 |
| 3 | 2 | control |
1.3、1.2、1.1 | 1.2 |
| 4 | 2 | high |
2.0、1.8、1.9 | 1.9 |
估计。 paired_block_estimate 在每个区组里用处理减对照:区组 1 是 2.0 − 1.0 = 1.0,区组 2 是 1.9 − 1.2 = 0.7。效应是各区组差值的平均:(1.0 + 0.7) / 2 = 0.85。
检验。 假如光照没有影响,区组里哪一轮叫 high 就无所谓,每个区组的差值完全可能是相反的符号。精确符号翻转置换检验把所有符号组合列出来,数一数有多少种组合的和,离零至少和实际观察到的和(1.7)一样远。
| 区组 1 | 区组 2 | 和 | 离零是否不小于 1.7? |
|---|---|---|---|
| +1.0 | +0.7 | +1.7 | 是。这就是实际观察到的。 |
| +1.0 | −0.7 | +0.3 | 否 |
| −1.0 | +0.7 | −0.3 | 否 |
| −1.0 | −0.7 | −1.7 | 是 |
四种组合里有两种算数,所以 p = 2 / 4 = 0.5。把这些数值交给 unit_table、paired_block_estimate 和 conclusion,得到的结果相同:效应 0.85,2 个区组,p = 0.5,结论是 uncertain。
为什么两个区组不够¶
实际观察到的组合和它的镜像,永远算数。n 个区组共有 2ⁿ 种组合,所以不管效应多大,这个检验能给出的最小 p 值是 2 / 2ⁿ。
| 区组数 | 符号组合数 | 可能的最小 p 值 |
|---|---|---|
| 2 | 4 | 0.5 |
| 3 | 8 | 0.25 |
| 4 | 16 | 0.125 |
| 5 | 32 | 0.0625 |
| 6 | 64 | 0.03125 |
两个区组的 p 值永远不会低于 0.5,五个区组仍然到不了 0.05 以下,六个区组才第一次有可能。一顶帐篷、两个处理,六个区组就是十二轮。
代码里的几个下限:
- 完整区组少于 2 个(
MIN_BLOCKS):不估计效应,报告里会写明。对照和处理都有数据的区组才算完整。 - 区组少于 6 个(水平 0.05):报告效应和 p 值,但结论是
uncertain。 - 区组多于 20 个:检验不再是精确的。代码用固定的种子抽取 20,000 种符号组合,并把实际观察到的组合算作其中一种,所以 p 值不会是 0;报告里注明 p 值是近似的。
确认性分析的关口¶
确认性分析,是指方法在看到数据之前就已经定下来的分析。只有下面几条全部成立,结果才可以标为确认性。代码是 research/analysis.py 里的 ConfirmatoryRunner。
- 脚本在任何阶段启动之前按哈希冻结。 操作员用
POST /wb/protocols/PROTOCOL_ID/analysis冻结它,这会调用freeze_analysis。它为协议的一个版本登记 SHA-256、脚本原文和冻结人。一个版本只有一个脚本。脚本和登记的哈希不同,或者和协议里写明的哈希不同,就被拒绝(script_hash)。冻结时脚本只被编译、从不运行,编译不过的脚本被拒绝(param):冻结的脚本不能更正,不能让一个笔误用掉唯一的机会。运行这个协议版本的任何一轮里一旦有阶段启动,冻结就被拒绝(state),因为分析必须在能看到结局数据之前定下来(架构文档 6.5 节)。 - 数据是冻结的、完整的、校验通过的快照。 运行之前,数据快照的清单和每个文件都重新计算哈希并比对,而且快照必须是完整的(覆盖率不低于 0.9)。否则拒绝运行(
snapshot_incomplete)。见数据、档案与可追溯性。 - 只跑一次。 由操作员用
POST /wb/analysis/runs启动,运行的是保存下来的脚本。一个协议版本的脚本在同一份快照上只能跑一次。再跑就被拒绝(already_run)。运行失败或超过 600 秒,同样用掉这一次机会,并且记为探索性。 - 所有数据都是在冻结之后收集的。 快照背后的每个阶段都在冻结时或之后启动,快照里的每条人工测量都在冻结时或之后记录(以档案自己的记录时间为准,不看操作员填的
measured_at)。否则运行被拒绝(state)。如果协议版本各轮所用的实验已经有快照或测量,冻结也会被拒绝。冻结之前收集的数据永远不能是确认性的:在新协议版本的某一轮里重用旧实验,并不会让它变成新数据;一个实验被不止一个版本的轮次共用,就根本不能运行。 - 按变量 ID 过滤。 脚本直接读取快照里的
measurements.jsonl,所以应当按标准变量 ID(metric字段)选行,绝不能按自由文本的名称。快照里的catalog.json记录数据用的是哪个目录版本和哪些变量。见变量目录。 - 脚本在沙箱里运行,不能联网,对快照只读(
research/sandbox.py)。沙箱目前只在 macOS 上可用。在其他系统上(包括树莓派),它拒绝运行任何脚本(sandbox_unavailable)。
报告按它的数据被收集时所在的协议版本来分析,这个版本从它引用的快照所属的轮次读出,从不取最新保存的版本;快照来自不止一个版本,就被拒绝(param)。发布报告时,服务端会检查报告用到的每一份快照是否都有一次这样的成功运行。没有的话,标签最高只能是探索性。协议版本已经冻结脚本时,报告引用的每一份快照的运行都结束之前,发布会被拒绝(state),这样一轮就不会在操作员还没有运行分析的时候,就带着探索性的结论被交付。运行以失败告终的,报告可以发布,但标为探索性。从冻结到确认性报告的整条路径,由 test_e2e_confirmatory.py 用假沙箱走了一遍。
如实降级¶
报告的标签由服务端根据研究协议和冻结的数据算出来,研究 Agent 不能自己指定。classify 执行五条规则:
| 规则 | 代码里的阈值 | 标签 | 事实从哪里来 |
|---|---|---|---|
| 独立重复太少 | 对照或处理的实验单位少于 2 个(MIN_REPLICATES) |
描述性 | 有数据的那些轮次的分配 |
| 处理和时间分不开 | confounded_with_time |
描述性 | 对有数据的轮次做设计检查 |
| 缺失过多 | 超过协议里的 max_missing_fraction,默认 0.2 |
探索性 | 两个数里较大的一个:计划的实验单位中没有主要终点测量的比例;1 减去各快照中最低的覆盖率。只计已经运行的协议轮次,即报告引用的轮次和有阶段已开始的轮次。还没人运行的轮次不算缺失(轮次不够时由重复数规则降级);运行过却没写进报告的轮次仍算缺失。 |
| 看到结局之后改了方案 | 标记 changed_after_outcomes |
探索性 | 由研究 Agent 申报,服务端看不到 |
| 实际处理偏离了批准的方案 | 超过 max_deviation_fraction,默认 0.1 |
探索性 | 两个数里较大的一个:有干预记录、设备记录的档位从未达到本轮分配处理、或计划的人工任务有超过 10% 没有按时完成的实验所占比例;研究 Agent 申报的比例 |
描述性优先于探索性,所有降级原因都写进报告。发布路径上还有三道上限,会把确认性降为探索性(agents/handlers_report.py、research/report.py):不是每份快照都有成功的确认性运行;快照不完整;留出数据已经被读过一次。
人工任务。 快照里保存运行单在阶段时间窗内计划的人工任务,以及操作员在阶段页上做的记录(planning/manual_tasks.py)。某次任务的最新记录为"已完成",且完成时间不晚于到期后两小时(ON_TIME_SECONDS),就算按时完成;make_up_allowed 的任务只要在阶段结束前完成即可;而且这条记录必须在截止时间后一天内录入(LATE_ENTRY_SECONDS),事后很久填写的完成时间不能让它算作按时。延迟、跳过和没有记录的都算没完成。每个快照按它冻结的那一刻、用当时已有的记录来判断(清单里的 manual_tasks_judged_at):还没到期或仍在时限内的任务不计入,所以在阶段结束时或阶段中途冻结的快照不会显示尚未发生的偏离。但这些任务并没有被核对:报告会按轮次注明(manual_tasks_unsettled),并把结论标签最高限为探索性(manual_tasks_unchecked);要完整核对,请在最后一次任务的截止时间之后重新冻结。有这类任务的轮次会在报告局限里写一条说明,超过 10%(MAX_MISSED_SHARE)的轮次算作偏离。在人工任务随快照冻结之前冻结的旧快照不参与这项核对。
说明的语言。 服务器加进报告的每条原因和局限都是一条带代码的说明(research/notes.py),同时有英文和中文。报告把它们存在 notes 里,每条有 code、kind(reason 或 limitation)、params 和 text(en、zh),模型自己写的局限另存在 model_limitations。轮次页按控制台当前语言显示。纯文本字段 reasons、limitations、conclusion_text 仍保存中文,旧的读取方式看到的内容不变。
研究 Agent 可以传三个标记:changed_after_outcomes、early_terminated 和 deviation_fraction。每一个都只能让结果更严格。本来可以标为确认性、但还有未解决的问题,或者因为快照不完整而失去这个标签的报告,转入待复核(needs_review),这一轮不会交付。
写“不确定”,不写“无效应”¶
小实验没有发现差异,并不等于证明了没有差异。所以 conclusion 只有三种结果:supported(支持)、not_supported(未获支持)和 uncertain(不确定)。没有哪一种叫“无效应”。
下面任何一条成立,结论就是 uncertain:
- 实验提前终止(标记
early_terminated); - 实际完成的完整区组数少于协议计划的区组数;
- 无法估计效应(完整区组少于 2 个);
- 区组太少,检验达不到 0.05(少于 6 个)。
都不成立时才看 p 值:小于 0.05 是 supported,大于等于 0.05 是 not_supported。
代码不计算置信区间,也不去判断区间有多宽,用的就是上面这四条规则。示例协议只有两个区组,结论永远是 uncertain。它只有先导实验的规模。
预测模型与留出数据¶
评价一个预测模型,必须用它从没碰过的数据。research/holdout.py 的 HoldoutRegistry 负责记这本账:
- 名称通过变量目录解析。 目录无法解析的名称按留出的结局处理:在留出批次里、以及没有批次的测量里都被隐藏。登记要求每个结局字段都能解析;如果留出批次里已有测量的名称无法解析,登记以
state被拒绝,错误里列出这些名称。在这条规则之前登记、结局字段里含有目录无法解析的名称的留出集,分不清哪些是它的结局,所以它的留出批次里的每一条测量(以及每一条没有批次的测量)都被隐藏。 - 留出数据用
POST /wb/holdouts按批次登记,请求里写明留出批次、开发批次和结局字段。至少要有 2 个开发批次(MIN_DEVELOPMENT_BATCHES),同一个批次不能同时在两边,名字不能为空或重复。登记会保存开发批次和登记人。 - 登记必须早于结局数据。 项目的任何实验里,只要已有一条人工测量属于留出批次、指标又是结局指标,登记就被拒绝(
state):那些数据可能已经被看过。没有批次的测量也算,被更正过的测量同样算,没有任何阶段拥有的实验里的测量也算(无法证明它属于别的项目;测量路由现在也不再接受这样的测量)。这个检查是对已保存的测量做一次查询。这和“先冻结分析脚本、后有数据”是同一个道理。 - 登记之后,冻结数据集时会排除留出批次的结局测量。没有批次信息的结局测量也按留出处理。被排除的条数记在快照清单里。
- 评估之前,模型、特征和预处理都按哈希登记。没有登记的模型被拒绝(
model_unregistered)。 - 对同一份留出数据的第一次评估可以是确认性的,之后每一次都是探索性的。每次读取都记录时间和读取者。
late_features列出在预测时点之后才收到的特征。- 目前没有用留出数据给模型打分的流程。
register_model和evaluate只是一道标签关卡:核对哈希、统计读取次数。没有任何流程能在不把留出结局暴露给模型的前提下算出预测得分,这需要单独设计。登记模型没有路由。
研究 Agent 能接触到什么¶
研究 Agent 是语言模型,所以它的工具有明确的边界(agents/handlers_common.py、agents/handlers_researcher.py):
- 限定在任务所属的项目内。
inspect_stage_data、freeze_dataset、run_local_analysis和publish_research_report都要指明一个研究任务,而且所指明的必须就是调度器正在运行的任务:服务器在运行期间绑定任务,模型给出的编号只和这个绑定比对,从不直接采信。别的角色或别的项目的任务、同一项目的另一个任务、以及在调度运行之外发起的调用,一律拒绝。阶段、轮次和快照,只有和这个任务属于同一个项目才能使用。其他情况一律以scope拒绝;别的项目的快照,看上去和不存在的快照没有区别。 - 每个实验只有一个所属项目。 快照所属的项目,就是运行其实验的阶段所属的项目。工作流会拒绝复用别的项目
experiment_id的运行单;一个实验若被两个项目的阶段同时占用,就没有所有者,所有范围检查都会拒绝它。 - 不碰留出数据。 测量文件里含有留出批次结局的快照,在读取或挂载任何内容之前就被拒绝。这能拦住那些在登记留出数据之前冻结的快照。
- 限值取自运行单。 冻结数据时,时间窗和采样限值来自运行单,不由模型提供。
- 自己跑的分析都是探索性的。 研究 Agent 用
run_local_analysis跑出的任何结果,都标为探索性。
目前还没有的部分¶
- 没有任何模型工具或 CLI 命令能冻结或运行分析脚本;这两件事都由操作员通过工作台来做。
register_model没有路由或工具,只有测试在调用。 randomize_series、randomize_tents和失败轮次的补做规则(make_up_allocation)都只是函数,没有对应的工具。设计检查只负责把分配和种子对一遍。- 报告里的效应和 p 值由服务端用
paired_block_estimate计算。冻结脚本自己的输出留在运行目录里,不会写进报告。 - 一次确认性运行只对应一份快照。架构文档 6.5 节描述的是对系列各轮快照做一次总的运行,代码里没有这种运行。
- 没有置信区间,也没有可检测差异的计算。
另见¶
页面最近一次对照代码核对是在 2026-11-11。DiAGRI 模式目前只在模拟的 AC5 上测试过,见状态与已知限制。修改页面之前,请先读编写约定。