3. 自动化工程环境搭建

临床研究报告数据自动化工程的核心矛盾在于：分析代码必须在数月甚至数年后仍能复现出与首次交付完全一致的结果。环境搭建不是安装几个软件，而是建立一套让"代码—数据—依赖—运行环境"四者绑定的工程约束。本节围绕 Python/R 双工具链、版本控制、虚拟环境、依赖锁定、目录规范与可复现性设计展开，并给出可直接落地的配置示例。

一、双工具链的分工与协同

临床数据自动化通常不是单一语言能覆盖的。Python 在数据抽取、清洗、批量文件处理、API 对接和自动化调度上生态成熟；R 在统计建模、CDISC 相关包（如 admiral、metacore、gtsummary）以及图表输出上更贴近统计师习惯。合理的分工是：Python 负责"把数据变成干净的分析集"，R 负责"把分析集变成统计结果与报表"，两者通过中间数据文件（如 Parquet、CSV 或 SAS7BDAT）交换，而不是互相调用脚本。

协同的关键是接口约定：中间文件的列名、类型、缺失值编码、日期格式必须固定。例如约定所有日期统一为 ISO 8601 字符串 YYYY-MM-DD，缺失值统一为空字符串而非 NA/NaN/. 混用。接口一旦约定，就写入项目文档并由校验脚本自动检查，避免"Python 输出能跑、R 读入报错"的隐性故障。

二、版本控制：不只是代码，还有配置与文档

版本控制使用 Git，但临床项目有几个特殊要求。第一，数据不进入仓库：受试者级别数据、含 PHI 的原始文件、大体积中间结果一律通过 .gitignore 排除，仓库只保留代码、配置、文档和小体积的脱敏样例。第二，配置进入仓库：环境文件、依赖锁定文件、目录结构说明、运行入口脚本必须纳入版本控制，否则复现时缺少关键信息。第三，提交粒度与信息：每次提交应聚焦一个可描述的逻辑变更，提交信息说明"改了什么、为什么改"，便于审计追溯。

# .gitignore 关键条目示例
data/raw/          # 原始数据，含受试者信息
data/interim/      # 中间结果，体积大
output/            # 生成报表，可重建
*.sas7bdat
*.xpt
.env               # 本地路径与凭据
__pycache__/
.Rhistory
.RData

三、虚拟环境与依赖锁定

虚拟环境解决的是"同一台机器上不同项目依赖冲突"和"换机器后版本漂移"两个问题。Python 侧推荐 venv 或 conda，R 侧推荐 renv。核心原则是：环境可重建，依赖可锁定。

Python 项目用 requirements.in 声明直接依赖，用 pip-compile 生成带精确版本号的 requirements.txt；或使用 poetry/uv 生成 lock 文件。R 项目用 renv::init() 初始化，renv::snapshot() 生成 renv.lock，其中记录每个包的版本与来源。锁定文件必须提交到 Git，重建时执行 renv::restore() 或 pip install -r requirements.txt 即可还原。

# Python 环境重建
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# R 环境重建
Rscript -e "renv::restore()"

需要特别注意的是，临床统计中 R 包版本差异可能改变默认算法或输出格式。例如某些汇总函数在不同版本间对缺失值的处理策略可能调整，导致表格数字变化。因此锁定文件不是可选项，而是交付物的一部分。

四、项目目录规范

目录结构应让任何人打开仓库就能判断"数据放哪、代码放哪、结果放哪、配置放哪"。推荐采用分层结构，并保持命名稳定：

clinical-automation/
├── config/            # 环境配置、路径映射、参数文件
│   ├── config.yaml
│   └── paths.yaml
├── data/
│   ├── raw/           # 原始数据（不入库）
│   ├── interim/       # 中间结果（不入库）
│   └── sample/        # 脱敏样例（入库）
├── src/
│   ├── python/        # 抽取、清洗、转换
│   └── r/             # 统计、制表、制图
├── scripts/           # 运行入口、调度脚本
├── tests/             # 数据校验与单元测试
├── docs/              # 接口约定、运行说明
├── output/            # 报表与图表（不入库）
├── requirements.txt
├── renv.lock
└── README.md

路径不应硬编码在脚本中，而应通过 config/paths.yaml 统一管理，脚本读取配置获得路径。这样换机器或换目录时只改一处。

五、可复现性设计：从"能跑"到"可验证"

可复现性有三个层次：环境可复现（依赖锁定）、过程可复现（脚本化、无手工步骤）、结果可验证（有校验与比对）。前两层靠前述工具实现，第三层需要额外设计。

建议在 tests/ 下放置数据校验脚本，检查关键字段的非空率、取值范围、唯一性、日期逻辑（如结束日期不早于开始日期）。每次运行后输出校验报告，异常时中断流程而非静默继续。对于统计结果，可保存关键指标的哈希或摘要值，下次运行时比对，若不一致则提示人工复核。

下面用一张图概括环境搭建中各要素之间的依赖与约束关系，帮助理解"锁定—重建—验证"的闭环。

把上述要素落到日常操作上，一个典型的工作节奏是：修改代码后运行 pytest 或校验脚本，确认数据检查通过；若新增依赖，更新 requirements.in 并重新编译锁定文件；提交时同时提交代码、配置和锁定文件；在另一台机器上执行重建命令验证环境可还原。这样，环境搭建就不再是一次性的安装动作，而是贯穿项目生命周期的工程习惯。