REDCap Data Dictionary Generator

⚠️ 原 redcap-crf-generator 已不再更新，请使用本版本。

概述

本技能将临床试验 CRF/方案文档（Word/Excel/PDF）转换为符合 REDCap 标准的数据字典 CSV 文件。

核心流程

1. 文档解析 → 使用 markitdown 转换为 Markdown，充分理解文档结构
2. 图片识别 → 对文档中的评分表/诊断标准图片进行 OCR 识别
3. 字段生成 → 按照 REDCap 规范生成数据字典
4. 格式修正 → 确保 Section Header、验证类型、计算字段等符合规范

数据字典格式（REDCap CSV）

⚠️ 关键规则

1. Section Header 仅首字段填写

同组字段只在第一个字段设置 Section Header，后续字段留空。

Variable / Field Name,Form Name,Section Header,Field Type,Field Label,...
record_id,inclusion_exclusion,,text,Record ID,...
enroll_date,inclusion_exclusion,入排标准判定,text,入组日期,...
ie_1,inclusion_exclusion,,dropdown,纳入标准1：≥18周岁,...
ie_2,inclusion_exclusion,,dropdown,纳入标准2：同种异体肝移植术后,...

2. record_id 必须为第一行

第一个字段必须是 record_id，类型为 text，标签为 "Record ID"。

Variable / Field Name,Form Name,Section Header,Field Type,Field Label,...
record_id,inclusion_exclusion,,text,Record ID,...

3. Identifier? 仅用于直接身份标识字段

仅当字段涉及患者直接身份标识（如姓名、身份证号、住院号、手机号等）时设置 y。 一般人口学资料（年龄、性别、体重等）不属于隐私标识，不要设置。

Variable / Field Name,Field Type,Identifier?,...
dm_1,text,y,...  # 编号（含姓名首字母），属于隐私
dm_3,text,,...   # 年龄，不属于隐私，无需设置

4. calc 字段不需要验证类型

计算字段（calc）的 Text Validation Type / Min / Max 留空。

Variable / Field Name,Field Type,Choices, Calculations, OR Slider Labels,Text Validation Type,...
dm_bmi,calc,round([dm_6]/(([dm_5]/100)^2),1),,...

字段类型选择规则

选项数量决定字段类型：

• ≤4个选项 → 使用 radio（单选按钮），界面更直观
• ≥5个选项 → 使用 dropdown（下拉选择），避免界面拥挤
• 多选 → 使用 checkbox

支持的字段类型

处理复杂文档的技巧

1. 文档结构识别

• 使用 markitdown 将文档转为 Markdown
• 识别 表X： 或 表X 格式的表单标题（注意可能混用全角/半角空格）
• 段落中的 {}、（） 包含字段定义

2. 图片 OCR 识别

当文档包含评分表图片（如 SOFA、APACHE、GCS、诊断标准）时：

• 从 docx 中提取图片（word/media/ 目录）
• 使用 image 工具识别图片内容
• 将识别结果转换为结构化字段

3. 括号兼容性

文档可能混用 ASCII 和全角括号：

• ASCII: {单选，是，否}
• 全角: ｛单选，是，否｝
• 处理时需同时检查两种格式

4. 分支逻辑处理

分支逻辑写在 Choices 中，通过 [字段] = "值" 格式标注：

choices = "1, 是 | 0, 否"
branching = '[dm_10] = "7"'  # 当选择"其他"时显示备注文本

CDISC 变量命名建议

使用方式

当用户上传文档并要求生成数据字典时：

1. 读取文档（markitdown 转换为 Markdown）
2. 提取并识别文档中的图片（如有评分表）
3. 解析表单结构和字段定义
4. 按上述规则生成数据字典
5. 确保 record_id 为第一行
6. 通过飞书发送 CSV 文件

依赖

pip install python-docx lxml markitdown