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）#

列名说明示例Variable / Field Name字段变量名，CDISC规范sex, ie_1, dm_3Form Name表单英文名demography, inclusion_exclusionSection Header****分节标题（仅首字段填写）患者基本信息Field Type字段类型text, dropdown, radio, checkbox, calc, notes, fileField Label字段中文标签性别, 年龄（岁）Choices, Calculations, OR Slider Labels选项或计算公式1, 男 | 2, 女 或 round([weight]/(([height]/100)^2),1)Field Note特殊说明/格式要求单位：岁, YYYY-MM-DDText Validation Type验证类型date, number, integer, datetimeText Validation Min/Max数值范围0, 120Identifier?是否隐私字段（仅限姓名、身份证等直接身份标识）y（是）或留空Branching Logic分支逻辑[dm_10] = "7"Required Field?是否必填y（是）或留空

⚠️ 关键规则#

1. Section Header 仅首字段填写

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

csv

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"。

csv

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

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

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

csv

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

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

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

csv

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

选项数推荐类型示例2-4radio``1, 是 | 0, 否≥5dropdown``1, HBV | 2, HCV | 3, DILI | 4, PBC | 5, 肿瘤 | 6, 其他多选checkbox``1, 血流 | 2, 肺部 | 3, 腹腔 | 4, 泌尿系统

支持的字段类型#

类型说明Choices 格式text单行文本无notes多行文本/备注无radio单选按钮（≤4个选项）0, 否 | 1, 是``dropdown下拉选择（≥5个选项）0, 否 | 1, 是 | 2, 其他``checkbox多选框1, 选项1 | 2, 选项2 | 3, 选项3``calc计算字段round([weight]*10000/([height]^2),1)``file文件上传无date日期（用 text + date 验证）无datetime日期时间（用 text + datetime 验证）无

处理复杂文档的技巧#

1. 文档结构识别#

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

2. 图片 OCR 识别#

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

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

3. 括号兼容性#

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

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

4. 分支逻辑处理#

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

python

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

CDISC 变量命名建议#

前缀表单示例ie_inclusion_exclusion 入排标准ie_1, ie_2``dm_demography 患者基本信息dm_1, dm_3``meld_pre_meld MELD评分meld_inr, meld_score``sofa_p_pre_sofa 术前SOFAsofa_p_gcs, sofa_p_total``apach_pre_apache APACHE评分apach_p_temp, apach_p_total``cci_pre_cci Charlson合并症cci_1, cci_total``infrf_preop_infrf 术前感染因素infrf_1, infrf_3_detail``op_op_info 手术信息op_date, op_blood_rbc``don_donor_info 供体信息don_age, don_hbsag``inf_infection_info 感染信息inf_date, inf_site``sofa_i_infection_sofa 感染时SOFAsofa_i_pf, sofa_i_total``apach_i_infection_apache 感染时APACHEapach_i_gcs, apach_i_total``bsi_bsi_criteria 血流感染标准bsi_1, bsi_2_symptom``abi_abi_criteria 腹腔感染标准abi_ssi, abi_ia_clinical``pulm_pulm_criteria 肺部感染标准pulm_img_1, pulm_symptom``fu_treatment_fu 随访fu_date, fu_abx``out_outcome 结局out_clinical, out_survive_90d

使用方式#

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

text

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

依赖#

bash

pip install python-docx lxml markitdown