biostat-principles

# 生物统计执行原则 ## 1. 开工前确认 只确认会改变答案的内容：研究问题或 estimand、数据与时间窗、分析集、纳排、暴露或干预、终点、比较、主要方法及输出。已有 PROTOCOL、SAP、代码或用户明确指定的结果来源时先读取，不重复提问。 - 多个合理口径并存且会改变结果时，列明差异和影响，等待用户决定。 - 路径、展示格式或可从工作区确定的实现细节直接核验后执行。 - Q/L 或显而易见的修复不补建项目文档；P/R 才同步实际受影响的唯一来源。 - 不猜数据、包、版本、文献、研究发现或项目状态。 复杂任务在计划中写清四项即可： ```text 范围：Q / L / P / R 输入：唯一输入与已确认来源 输出：目标文件或回答 验证：可判定的完成标准 ``` ## 2. 最小且可验证的实现 - 只增加回答研究问题所需的数据处理、模型、表图和文稿内容。 - 沿用既有分析语言和项目风格；未指定且无既定流程时使用 R。 - 代码写完必须用新的非交互进程实跑。R 多行代码写入脚本后用 `Rscript`；Python 使用项目现有且版本兼容的 Python。 - 检查完整 stdout、stderr、预期文件和关键断言，不以退出码或日志尾部代替核验。 - 修改已有流程时，每一处差异都应对应本轮请求；保留来源不明的既有改动。 验证强度服从范围：Q 只核验事实，L 验证受影响部件，P 验证受影响数据链，R 再运行发布检查。不得为显得完整而生成没有实际用途的产物。 已有项目在执行命令前先写清“改动—影响—验证对应关系”：列出实际改动、最早受影响的输入或步骤、实际受影响的表格、图件、论文、报告、PPT 或交付文件、必须运行的命令，以及能够复用最近一次成功结果的哈希值或运行记录。数据、定义、分析集、方法或实际生成正式结果的脚本发生变化时，从最早受影响步骤重跑；总入口不支持安全分段时完整运行一次。只改变表图或正文格式时，沿用来源和哈希值未变的已确认结果，只重新生成并检查受影响成品。不因检查脚本、状态说明、README、审计配置或文件格式变化重复重建数据和统计结果。 每项检查必须对应本次修改可能造成的一种具体科研或文件错误。L 只检查指定修改、范围外差异和实际使用该部件的成品；P 检查受影响数据链；R 再检查正式发布要求。内容 skill 已经核对的数字、论断或术语，文件 skill 只确认它们被正确写入和显示，不另做一套同义核验。输入、生成方法和被检查内容未改变时沿用最近一次成功证据；新的局部纠正只重查它可能影响的项目。 运行记录结构或记录器变化先在隔离的代表性项目中验证，不得直接改写历史运行记录。只有当前正式记录必须由真实执行重新生成、且不存在更小的可信入口时，才运行对应数据链一次。一次成功运行后，只要它记录的输入、数据定义、分析脚本和结果哈希值未变，后续检查和格式修复应复用该运行证据；检查失败先修检查或受影响成品，不把重复完整运行当作默认排错步骤。 验证项目还必须与本轮方法和正式产物直接对应。SHAP、特征重要性、替代模型、额外校准、敏感性分析、消融或其它可选诊断，只有在用户明确要求、PROTOCOL/SAP 预设、受影响的既有正式产物已经使用，或定位本轮发现的真实异常确有必要时才运行；不得把它们当作普通描述、回归、代码修复或模型复现的默认防御性检查。未生成这些不适用产物不构成缺项，也不为证明“没有问题”而补跑。 ## 3. 数据安全与异常处理 - 原始数据根永久只读。缺失、重复、异常范围、记录丢失或样本量跳变先回最早来源定位，不擅自填补、排除或覆盖。 - 分析、出图和写作全程监测 NA、NR、空值、warning、error、收敛失败、方向反转和结果来源不一致。 - 异常可能改变分析集、终点、分组、主模型或结论时停在安全点，报告发生了什么、证据位置、影响、已做检查和待决定事项。 - 代码缺陷修复后重跑；不得用异常捕获掩盖失败，也不得改代码迎合预期结果。 首次生成清洗数据、改变清洗规则，或正式分析读取清洗数据时，必须按 [分析就绪数据合同](references/data-readiness.md) 明确权威输入及其格式、区分待核对与分析就绪状态，并在正式统计估计前执行机器可检查的停止条件。简单 Q/L 不因此创建状态文件。 ## 4. 结果与来源 正式项目把关键结果及其来源保存在 `results/results.yaml`，文件结构见 [结果数据文件](references/result-summary-schema.md)。 - 实际生成结果的分析脚本，或导入已确认外部结果的专门脚本，是唯一写入者；不得直接编辑 YAML。 - 每项关键结果使用固定英文名称，并记录实际生成结果的脚本（`producer`）、脚本中提取结果的对象或查询（`source`）、输入路径或文件哈希值、分析集、运行编号（`run_id`），以及实际使用该结果的文件（`consumers`）。 - 该文件只保存数值、显示格式和来源，不保存结果解释或跨结果结论；解释与结论写在 `DECISIONS.md` 或对应正文，并由作者确认。 - 可以由该文件自动生成一份便于人工核对的文字摘要，但摘要不是数字来源。论文、报告、PPT 和表图按每项结果的固定名称取数，不手工输入关键数字。 - 旧项目可读取 `07_paper/results.yaml`；新流程不得写回旧路径或把旧字段复制到新文件。 方法选择或偏离写入 `DECISIONS.md`。只有需要后续补充数据、外部资源或由用户决定的事项才进入 `BACKLOG.md`。总运行脚本把实际命令、状态、脚本、输入输出文件哈希值和环境信息自动写入 `results/runs/<run_id>.json`，不创建或补写 `SESSION_LOG.md`。 ## 5. 总运行脚本与依赖 项目执行和正式发布只保留一个总运行脚本 `run_pipeline.R` 或 `run_pipeline.py`。该脚本应当： 1. 从项目根启动独立进程，按明确顺序运行主流程； 2. 失败即停止并保留完整日志； 3. 为随机过程传递已经确认的随机种子或数据划分标识； 4. 自动记录命令、时间、状态、脚本、输入输出文件的哈希值和环境信息； 5. 从声明输入重建预期结果、表和图。 长任务的调用超时、连接中断或没有收到完成输出，不等于分析进程已经终止。预计耗时超过调用默认等待时间时，优先使用能够继续等待同一任务的调用方式；需要重新启动前，只读确认原命令已经结束。无法确认时先报告当前状态，不盲目重复运行，也不为此给普通项目增加锁文件、PID 文件或新的状态机制。 脚本显式加载实际依赖，不依赖交互对象。已有锁文件时遵循锁文件；日常运行只记录本次实际环境，R 可用 `sessionInfo()`，Python 记录实际 Python 版本和已声明依赖。只有 R 正式发布或迁移运行环境时才完整记录依赖版本，不为轻量任务生成庞大环境清单。 缺失依赖按 [运行环境与普通分析包](references/runtime-dependencies.md) 处理：普通分析包只装入项目隔离环境；不升级运行时、系统依赖或共享环境；失败后不得静默换包、换方法或换语言。 ## 6. 探索分级 试新方法不得直接修改主流程。按决策影响选择最低充分级别： | 级别 | 适用场景 | 记录 | 纳入主流程 | | --- | --- | --- | --- | | E0 快速核验 | 一次报错复现、可行性或接口检查，不据此选择方法 | 当轮命令与验证结果，通常不建目录 | 不纳入；需要形成方法决定时改按 E1 处理 | | E1 决策实验 | 判断一个隔离方案是否值得采用，需要保存比较依据 | 在一个 `workbench` 批次中记录比较前提、实际运行和结论；可以分别用 `PLAN.md` 与 `FINDINGS.md`，也可以在一个记录文件中分节写清 | 达到事先确定的标准并经必要确认后纳入 | | E2 正式比较 | 多方案、模型优化、消融或将用于论文的探索性比较 | 在 E1 基础上建立项目 `EXPERIMENTS.md`，列出所有方案及其记录位置，保留失败、持平和未采用方案 | 使用相同数据和评价方法公平比较；改变主分析必须先确认并写入 `DECISIONS.md` | E1/E2 使用 `09_backup/workbench/<YYYY-MM-DD_HHMM>_<主题>_experiment/`。查看结果前，应写明问题、当前方法、唯一差异、数据划分、主要评价指标和采用新方案的标准；运行后记录当前方法与新方案的结果、差值、不确定性、异常信息和结论。记录可以拆分为 `PLAN.md` 与 `FINDINGS.md`，也可以合并，只要前后顺序和内容可核对。项目 `EXPERIMENTS.md` 只列出 E2 比较及其工作目录，不列正式归档。公平比较必须使用同一分析集、特征构造、数据划分和评价指标，并先复现当前方法。 未采用方案的结果不得写入正式结果数据文件。确需展示时应明确标为探索性分析或消融分析，不作为主要结论。 ## 7. 完成条件 - Q：问题已直接回答，事实边界明确。 - L：唯一输入和允许修改的范围已经确认，目标可打开或执行，范围外差异为零。 - P：原始数据未改，受影响代码已实跑，`results/results.yaml`、方法决定和实际使用结果的文件已同步，最近一次自动运行记录显示成功。 - R：在 P 基础上通过科学与合规发布检查；ERROR 为零，WARN/INFO 有明确处置或接受依据。 执行者也是监测者。无法完成时提供已核验证据和最小待决问题，不用重复试错或补建记录掩盖阻塞。