临床统计程序员的 Python 进阶路线图

这个项目解决什么问题

SAS 程序员的 Python 学习材料到处都是，但几乎都对不上你的工作：

本项目反过来：从你已经懂的业务出发，用真实数据把 Python 讲透。

适合谁

✅ 临床统计程序员 / 生物统计师，SAS 用得熟，Python 学过但半忘 ✅ 数据管理 / 统计编程相关岗位，想转向 Python 技术栈 ✅ 想了解 AI Agent 在临床数据场景怎么落地的人 ✅ 有编程基础、想了解 CDISC 数据结构的开发者

❌ 不适合：完全零编程基础的人（建议先补编程入门）

快速开始（3 条命令）

git clone https://github.com/jinbeiwang/clinical-python-roadmap.git
cd clinical-python-roadmap
pip install -r requirements.txt

# 直接跑（data/samples/ 里已有约 5MB 的样本数据，无需联网）
python cases/case01_数据体检.py

不需要装 SAS，不需要下载几十 MB 的 XPT，不需要 API Key。

想用完整原始数据（含 254 位受试者的全部 SDTM/ADaM 域）：

python scripts/download_data.py --core    # 从 CDISC 公开仓库下载 XPT
python scripts/make_samples.py            # 重新生成样本 CSV

💡 Agent 案例全部能离线跑：case07–case12 与 case_http_demo 默认都是 Mock 模式，不联网、不需要 API Key，但工具执行的是真实逻辑， 结论里的数字也来自真实数据。设置 OPENAI_API_KEY 即自动切到真实 LLM 模式。

bash python cases/case08_分层架构QC_Agent.py # 分层架构 + 预算 + 断点恢复 python cases/case10_TLF生成流水线.py # DAG 规划 + 并行 + 失败传播 python cases/case12_QC_Agent服务化.py # 起一个真能发请求的 HTTP 服务

目录结构

clinical-python-roadmap/
├── docs/                     # 25 章教程正文（00-24）
│   ├── *.md                  #   教程源文件（Markdown，GitHub 上可直接读）
│   ├── index.html            #   ★ 在线文档站首页（由 scripts/build_site.py 生成）
│   ├── guide/  code/         #   生成的章节页与源码阅读页
│   ├── assets/               #   站点样式、脚本与搜索索引
│   └── .nojekyll             #   关闭 Jekyll（文档里有 Liquid 会误解析的代码块）
├── cases/                    # 13 个可运行实战案例 ★ 核心
├── clinic/                   # 可复用的临床数据工具包
│   ├── io.py                 #   读 XPT/sas7bdat，保留标签，清洗伪缺失
│   ├── derive.py             #   SAS 语义的舍入、年龄分组、日期处理
│   ├── report.py             #   TFL 报表构造件（n (%)、Mean (SD)、移位表）
│   ├── qc.py                 #   数据质量检查、跨域一致性、PROC COMPARE 等价物
│   ├── agent_tools.py        #   暴露给 LLM Agent 的工具集
│   ├── agent_core.py         #   Agent 主循环、工具契约、预算闸门、观察者、指标
│   ├── agent_planner.py      #   任务 DAG、拓扑排序、并行调度、续跑
│   ├── agent_memory.py       #   分层记忆、结构化事实表、检索与引用
│   ├── agent_role.py         #   多 Agent 拓扑、角色契约、独立性守卫
│   ├── agent_http.py         #   带重试/退避/限流/脱敏审计的 HTTP 客户端
│   ├── config.py             #   12-Factor 配置、启动自检、密钥脱敏
│   └── agent_eval.py         #   确定性评估集（正向 + 否定式安全断言）
├── cheatsheets/              # 速查表 ★ 高频查阅（SAS→Python / Agent 开发）
├── resources/                # 精选资料索引（GitHub / CDISC / PHUSE / 论文）
├── ci/                       # GitHub Actions 工作流模板（见 ci/README.md）
├── scripts/                  # 数据下载、样本生成、文档站构建
│   ├── download_data.py      #   多通道下载 CDISC 公开 XPT
│   ├── make_samples.py       #   裁剪成入库的小体积样本 CSV
│   └── build_site.py         #   把 Markdown 与源码构建成 docs/ 下的静态站点
├── data/samples/             # 约 5MB 样本数据（已提交，离线可用）
└── outputs/                  # 运行结果（每次运行重新生成）

本地预览文档站

站点是纯静态、零外部依赖的（不引任何 CDN），克隆后用任意静态服务器打开即可：

python scripts/build_site.py --clean     # 重新生成 docs/
python -m http.server -d docs 8000       # 然后访问 http://localhost:8000

build_site.py 做三件事：Markdown → HTML（表格、代码块、脚注）、 仓库内相对链接重写（能指向站内的就指向站内，否则指向 GitHub）、 以及生成侧边栏与搜索索引（497 条小节级条目，按 / 或 Ctrl+K 唤起）。

为什么不直接用 Jekyll：教程正文的代码块里有 ${{ matrix.python-version }} 这类 GitHub Actions 语法，会被 Jekyll 当 Liquid 标签解析而构建失败； 且仓库里全是中文文件名，Jekyll 的 permalink 会生成一串百分号编码的可分享 URL。 自己生成 HTML 更简单也更可控。

25 章学习路线

阶段一：打通基础（你已经有编程底子，这部分要快）

阶段二：数据操作（核心中的核心）

阶段三：临床数据实战

阶段四：AI 与工程化

阶段五：Agent 核心能力（从"能跑"到"可维护"）

阶段六：Agent 工程化（从"我电脑上能跑"到"团队能放心用"）

13 个实战案例（全部实测可跑通）

每个案例都对应你工作里真实存在的表或任务， 并且刻意把最容易出错的口径问题摆在明面上。

数据与报表（case01–case06）

Agent 开发（case07–case12 + caseA）

案例的输出

跑完会在 outputs/ 生成可直接查看的产物：

• table01_demographics.html —— Table 1（带样式）
• table03_lab_shift.html —— 实验室移位表
• adsl_derived.csv + adsl_validation.html —— ★ 双编程验证报告
• case06_summary.xlsx —— 多 sheet 汇总
• agent_report.md + agent_transcript.json —— Agent 的报告与可审计对话记录
• pair/case11_report.md —— ★ 双编程比对报告（含差异分级与受影响受试者）
• pair/agegr1_copied_independence.md —— ★ 独立性审计（含违规命中）
• service/eval_report.md —— ★ Agent 评估报告（5/5 通过）
• audit/app.log —— 结构化日志（可按 request_id 捞一次请求的完整轨迹）
• audit/http.jsonl —— 外部调用的审计（已脱敏）

case05 的验证结果（真实的，不是宣称的）

派生 ADSL 与 CDISC 官方参考实现逐变量比对 28 个变量：

一致 23 个 ｜ 近似 3 个 ｜ 近似·数据受限 1 个 ｜ 不可派生 1 个

每一个不是 100% 的变量，都定位到了具体根因并写在程序的输出里。 例如：TRTEDT 的 254/254 一致，靠的是正确识别出 "EX 末次给药记录未闭合（治疗仍在进行）时，应取参考结束日 RFENDTC"。

这个仓库和别人的有什么不同

1. 所有数字都来自真实数据，没有任何编造

教程里出现的每一个计数、每一个匹配率，都是从 CDISC SDTM/ADaM Pilot Project （CDISCPILOT01，2007 年阿尔茨海默症试验，306 位筛选 / 254 位随机化） 实际跑出来的。你可以自己复现每一个数字。

2. 刻意暴露"口径问题"，而不是藏起来

绝大多数教程只会说"这样做就对了"。本项目会告诉你：

• 同一个"治疗结束日"，三种合理口径给出 248 / 254 / 127 三个答案
• 同一个"实际治疗组"，抄 DM.ACTARM 会错 12 个人
• "完成 8 周治疗"按"治疗时长 ≥ 56 天"算会少 7 个人

这些不是 bug，这就是临床统计编程的本质工作。

3. 有一个真实可用的工具包

clinic/ 不是教学玩具，是能直接用到项目里的：

from clinic import io as cio
from clinic.derive import sas_round_series, derive_agegr1
from clinic.report import summarize_continuous, crosstab_shift
from clinic.qc import check_dataset, compare_frames

dm = cio.read_xpt("data/raw/dm.xpt")          # 保留变量标签
df["BMIBL"] = sas_round_series(df["BMI"], 1)  # 与 SAS 一致的四舍五入

4. Agent 案例全部能离线跑

case07–case12 默认都是 Mock 模式：不联网、不需要 API Key， 用确定性的决策序列调用工具，但工具执行的是真实逻辑， 结论里的数字也来自真实数据。这解决了一个很现实的问题 —— 内网 / 合规环境没法调外部 LLM，但你又想先把流程验证通。

外部依赖同样可注入：agent_http 的传输层让"对面超时、限流、401、 返回缺字段的 JSON"都能在离线状态下被复现和断言。

5. 每条"经验之谈"都配了一个能跑给你看的证据

这是本项目最不像教程的地方：它不满足于告诉你结论。

只记 5 个坑的话，记这 5 个

如果你的时间只够记几条，就记这些（每一条都有对应的可运行代码）：

1. round() 不是 SAS 的 ROUND()

round(2.5)          # 2   ← 银行家舍入
round(2.675, 2)     # 2.67（浮点误差）
sas_round(2.5, 1)   # 3.0  ✅ SAS 语义：四舍五入
sas_round(2.675, 0.01)  # 2.68 ✅

→ clinic/derive.py · cases/case02

2. .std() 和 np.std() 不一样

s.std()      # ddof=1 —— 与 SAS 的 STD 一致 ✅
np.std(s)    # ddof=0 —— 与 SAS **不一致** ❌

3. 空字符串在 pandas 里不是缺失值

if x = '' then ...      /* SAS：能命中 */
df["x"].isna()          # pandas：空串不算缺失 ❌
cio.clean_missing(df)   # ✅ 先统一清洗

→ clinic/io.py · cases/case01

4. groupby 默认按字母序排，且会丢掉空组

df.groupby("TRT01P").agg(...)                 # ❌ High Dose 跑到 Low Dose 前面
df["TRT01P"] = pd.Categorical(df["TRT01P"], categories=TRT, ordered=True)
df.groupby("TRT01P", observed=False).agg(...) # ✅ 按 SAP 指定顺序，空组显示 0

→ cases/case02 · cases/case03

5. merge 右表主键重复会静默成倍膨胀

a.merge(b, on="USUBJID")   # 右表有重复 → 行数悄悄变多，不报错
assert not b.duplicated(subset=["USUBJID"]).any()   # ✅ 先断言
assert len(a) == n0        # ✅ 合并后必查行数

→ cases/case05

完整的 20 个坑见 SAS → Python 速查表。

只记 3 个 Agent 的坑的话，记这 3 个

写 Agent 的坑和写脚本完全不同 —— 脚本错了会报错，Agent 错了会安静地给你一个像模像样的答案。

1. "静默替换"比崩溃危险一百倍

# 用户问 adata，代码认不出来，于是"顺手"换成第一个可用的数据集
ds = pick_dataset(goal) or "adsl"     # ❌ 结论看起来完全正常，只是分析的是另一个数据集

本项目的评估集第一次跑就抓出了这个缺陷（clinic/agent_core.py）。 正确做法是先枚举、再如实说没有，而不是猜一个顶上。

→ clinic/agent_core.py · cases/case12

2. 独立性一旦破坏，"零差异"是坏消息

B 抄了 A        → 0 处差异，独立性 ✗  → 零价值（同一份错误被复制了一遍）
真正独立的 A、B  → 2 处差异，独立性 ✓  → 找到了 2 个真问题

所以独立性必须靠架构强制（上下文物理隔离、产物命名空间隔离、 比对由第三方代码执行），不能靠自觉。而且审计覆盖率为 0 的"通过"等于没查。

→ clinic/agent_role.py · cases/case11

3. 缓存键漏掉数据版本 = 静默返回旧数据

key = f"{tool}|{args}"                    # ❌ 数据更新后仍返回旧结果
key = f"{data_version}|{tool}|{args}"     # ✅ mtime + size 参与键

这类事故不报错、不崩溃、表看起来完全正常，只是数字是上一版的。 同理：水位线必须在落盘成功之后才推进，顺序反了就是永远补不回来的丢数。

→ clinic/config.py（data_version_of）· cases/case12 · cases/case_http_demo

数据来源与许可

数据：来自 CDISC SDTM/ADaM Pilot Project （CDISCPILOT01）。这是唯一被 FDA 审阅过的公开完整数据集， 包含 SDTM + ADaM + 原始 TFL 输出 —— 所以你可以拿自己的结果去和官方输出逐个数字对。

代码：MIT License。可以自由用于学习、公司内部培训，乃至商业项目。

合规提醒（重要）

⚠️ 这是一个学习项目，不是监管文件，也不构成合规建议。

在药企 / CRO 环境里使用 Python 或任何开源工具前，请务必注意：

🧠 务实的落地路径： 先把 Python / Agent 用在不接触患者数据的场景 —— 代码迁移、程序审查、从规范文档找答案、生成程序骨架。 这些价值高、风险低，是最现实的切入点。

精选资料索引

速查表（高频查阅）

如果只打开 3 个链接：

1. CDISC 试点数据 —— 本项目的数据来源
2. PHUSE OSTCDA —— SAS/R/Python 方法学对照
3. CDISC CORE —— 官方开源一致性规则引擎

常见问题

Q: 我 SAS 很熟，需要从头学 Python 语法吗？ 不用。看第 02 章快速过一遍， 然后直接从第 06-07 章（向量化与 DataFrame）切入。 难点从来不在语法，在思维方式。

Q: 会不会学了 Python 就不用 SAS 了？ 不是替代关系。现实里 Python 和 SAS 长期共存。 本项目的目标是让你能用 Python 做 SAS 现在做的事， 并在某些场景（自动化、Agent、大文件处理、元数据驱动）做得更好。

Q: 没有 SAS 环境能跑通吗？ 可以。全部案例只需要 Python 就能跑，读 XPT 用 pyreadstat，不需要装 SAS。

Q: 需要联网吗？ 不需要。data/samples/ 里已有约 5MB 样本数据，克隆后直接就能跑。 只有想用完整原始数据时才需要 scripts/download_data.py。

Q: 案例的数字我能对得上官方输出吗？ 能，而且你应该去对。 建议拿 CDISC 试点项目的原始 TFL 输出 （仓库里有 PDF/RTF）自己比一遍 —— 对不上的地方就是你要学的地方。

Q: 学完能做什么？ - 把现有的 SAS 程序用 Python 重写并做双编程验证 - 搭建自动化的数据体检 / QC 流水线 - 用元数据驱动的思路替代手写映射 - 开发辅助性的 Agent（代码审查、文档检索、程序骨架生成） - 把 Agent 做成团队能放心用的服务：接口、指标、审计、评估集齐全

Q: 第 18–24 章和前面的 Agent 内容重复吗？ 不重复。第 16 章解决的是"Agent 是什么、 最小可用长什么样"；18–24 章解决的是"怎么让它可维护、可上线、 可审计" —— 分层架构、任务规划、工具契约、记忆检索、多 Agent 独立性、 外部集成、部署与监控，每一章都配一个能跑的案例。

Q: Agent 部分要花钱吗？ 不需要。13 个案例全部可在 Mock 模式离线跑完， 包括第 24 章那个真能发请求的 HTTP 服务（它自己用标准库起服务， 再用标准库发请求，全程在回环地址上）。想验证真实 LLM 行为时， 设置 OPENAI_API_KEY 即可切换。

参与贡献

欢迎提 Issue 和 PR，特别是：

• 🐛 发现的错误：任何数字对不上、代码跑不通、口径写错了
• 💡 补充真实案例：你工作里的表型，脱敏后可以作为案例
• 📚 补充资料：新的权威仓库、有价值的论文
• 🌐 翻译：英文版会很有价值

提 PR 前请确认：代码实测可跑通，数字能从真实数据复现。

许可

代码：MIT License 数据：见 LICENSE 末尾的数据声明 —— 来自 CDISC 公开项目， 再分发时请遵守原始许可。

如果这个项目帮你省下了摸索的时间，欢迎 Star ⭐ —— 也欢迎告诉身边的同行。