python-analysis：Python 分析规程

目的

Python 是科研计算的主力工具，也是"跑过一次就复现不出来"的重灾区：依赖版本漂移、随机种子没固定、原始数据被顺手改掉、图只存了屏幕截图。本技能把每一次本地 Python 分析约束为可复现的最小闭环：

1. 环境可重建：隔离环境 + requirements.txt + 环境指纹进 provenance；
2. 结果可复算：随机种子固定并写进记录；
3. 数据可追溯：原始数据只读，清洗产物另存；
4. 产物可定位：统一落盘 output/<skill>/<slug>/，图表双格式；
5. 报告数字可机检：交付前过一遍 stats_integrity_check.py。

本技能只规定规程，不规定具体算法；算法选择由研究问题决定（必要时标注 [模型知识—待核实] 并与用户确认）。

前置检查

1. 确认当前目录是工作区根目录（结构约定见 research-workspace）；产物路径契约 output/<skill>/<slug>/latest/ 在这里同样适用，本技能的 <skill> 名即 python-analysis（用户自建脚本的分析产物可用 analysis 作为 skill 名，保持与既有产物一致即可）。
2. 确认原始数据已在 data/ 下且按只读原则管理；数据还没就位时先停下来请用户放数据，不要用"示例数据"冒充真实数据跑分析。
3. 检查是否已有可用环境：项目根存在 .venv/ 或 requirements.txt 时优先复用，不要每次分析都新建环境。
4. 涉及人体、患者、涉密数据的分析，先对照画像"伦理与数据合规要求"一节：红线数据不得离开规定机器，更不得上传到第三方在线工具（guardrail 第 8 条）。

1 · 环境：优先 uv，其次 venv

按以下优先级选择环境管理工具：

1. uv（已安装时）：uv venv 创建 .venv/，uv pip install -r requirements.txt 安装依赖。速度快、锁文件友好。
2. venv + pip（uv 不可用时）：python -m venv .venv，激活后 pip install -r requirements.txt。
3. 不用 conda 新建环境，除非画像"算力环境"一节明确写了 conda——与画像保持一致优先于本规程。

纪律：

• 每个项目一个 .venv/，放在工作区根目录；不在系统 Python 里 pip install 任何分析依赖。
• 新装依赖后立刻 pip freeze > requirements.txt（uv 同理）更新锁定；requirements.txt 是产物的一部分。
• 首次在某环境跑分析时，用 provenance-record 登记一次环境（脚本自动写 .openscience/env/<hash>.txt）；此后每次登记的 env_hash 自动关联。

2 · 随机种子：固定并登记

1. 脚本开头统一设种子：

   import random
   import numpy as np
   
   SEED = 42
   random.seed(SEED)
   np.random.seed(SEED)
   

   
   用到其他带随机性的库（如 torch、sklearn 的 random_state）时，把同一个 SEED 传进去。
2. 种子值写进 record_run 的 --note（如 seed=42）；换种子重跑视为一次新实验，登记新记录并说明换种子的原因。
3. 不允许"先不固定种子看看效果"——探索性运行同样登记，大不了 note 里写"探索性，未固定种子"，让读者知道这条结果的复现等级。

3 · 数据：原始只读，清洗另存

1. 从 data/ 读，永不写 data/ 下已存在的文件；任何脚本检测到自己在覆盖 data/ 文件，立即停止并报告（research-workspace 原始数据只读原则）。
2. 清洗、转换、筛选的产物是新文件：中间产物放 output/python-analysis/<slug>/<timestamp>/；需要跨分析复用的清洗后数据集放项目自建的 derived/（不存在则创建），并在 README 或 note 里写清由哪份原始数据经哪步处理而来。
3. 数据纠错走增补：发现原始数据有误时新存修正版 + README-correction.md，原文件保留。
4. 大文件读取失败（内存不足）时，改用分块（pandas.read_csv(..., chunksize=...)）或先抽样探索，不要在报告里假装全量分析过。

4 · 分析脚本：可重复执行

1. 脚本放 scripts/，命名 kebab-case（如 analyze-cycle-life.py）；一次性探索可以用 notebooks/，但进入产物的分析必须落成脚本。
2. 脚本满足"从头跑到尾不交互"：python scripts/xxx.py 一条命令完成，不弹 input()、不依赖 notebook 单元格顺序。
3. 参数用 argparse 或脚本顶部常量集中声明；硬编码路径只允许指向工作区内相对路径。
4. 输出目录按时间戳创建（YYYYMMDD-HHMMSS），本次全部产物写入其中。

5 · 产物落盘与图表规范

1. 目录契约（与 research-workspace 一致）：

   output/python-analysis/<slug>/<timestamp>/   # 本次运行全部产物
   output/python-analysis/<slug>/latest/        # 运行结束后的完整副本
   

2. 图表一律双格式导出：PNG（预览、贴报告）+ PDF（排版、投稿矢量），均 300 dpi：

   fig.savefig(out / "cycle-life.png", dpi=300, bbox_inches="tight")
   fig.savefig(out / "cycle-life.pdf", bbox_inches="tight")
   

3. 统计结果（表格、模型参数、p 值）同时落一份机器可读文件（CSV 或 JSON），不要只存在图里或打印在 stdout——报告里的每个数字都应能指回这份文件。
4. 运行结束后刷新 latest/（先清空再放副本），然后用 provenance-record 登记：

   python <插件包路径>/skills/provenance-record/scripts/record_run.py \
     --path output/python-analysis/<slug>/latest/ \
     --tool "python scripts/analyze-cycle-life.py" \
     --note "循环寿命分析，seed=42，数据 data/2026-08-cycling/"
   

6 · 报告数字体检：stats_integrity_check.py

分析结论写进 markdown 报告后、交付前，运行本技能自带脚本做确定性数字检查（纯标准库）：

python <插件路径>/skills/python-analysis/scripts/stats_integrity_check.py \
  --path reports/<报告>.md --format json

检查项：

1. 百分比在 0-100 内；同一行疑似构成组的百分比之和 ≈ 100±0.5；
2. p 值格式（p<0.001 或 p=0.xxx）与取值在 0-1 内；
3. N=n 多次出现时数值一致；
4. 置信区间下界不超过上界。

脚本输出 {issues: [{check, location, detail, level}]}，error 级问题修复前不得交付（guardrail 第 7 条）；脚本退出码为 1 表示存在 error 级问题，可接入流水线。脚本是确定性规则，不替代统计判断——它查"数字写得对不对"，不查"数字算得对不对"。

输出模板

分析完成后的汇报：

## Python 分析完成（<任务名>）

- 环境：.venv/（uv / venv），requirements.txt 已更新，env_hash=<hash>
- 种子：seed=<N>（已登记）
- 产物：output/python-analysis/<slug>/latest/（清单：…）
- 图表：…（PNG+PDF，300dpi）
- 数字体检：stats_integrity_check 通过 / N 条 warn（列出）/ N 条 error（修复中）
- provenance：已登记（note：…）

下一步：…

本技能不做什么

• 不替用户选统计方法或模型：方法适用性是领域判断，本技能最多提示"该选择需要领域依据"，必要时标注 [模型知识—待核实] 并请用户确认。
• 不动原始数据：任何清洗、纠错都生成新文件（research-workspace 只读原则）。
• 不管理远程与集群任务：SSH 远程算力见 remote-compute，Slurm 集群见 hpc-slurm，长任务后台管理见 run-monitor。
• 不保证统计正确性：stats_integrity_check.py 只做格式与一致性机检，显著性解释、多重比较校正等仍需用户与 reviewer 把关。
• 不自动安装系统级软件：装 Python 本身、装 uv 属环境准备，向用户说明后由用户执行。

收尾与下一步

• 产物进入报告或论文前：刷新 latest/、确认 provenance 登记完整、跑 stats_integrity_check.py 清零 error。
• 分析结论要支撑论文级论断时，进入 evidence-capsule 冻结流程（脚本、环境、数据版本一并打包）。
• 报告交付前按 reviewer-protocol 接受审查；数字类意见（check=number）与本技能体检结果一并处理。
• 分析耗时超过分钟级时，改用 run-monitor 后台运行，不要让人机会话空等任务结束。