REDCap Data Dictionary Generator

开发者：邹和建、刘从进 REDCap Data Dictionary Generator - 将 Word/Excel 文档（CRF/方案）转换为 CSV 格式的 REDCap 数据字典。 ⚠️ 原 redcap-crf-generator 已不再更新，请使用本版本。 适用场景： - 用户上传临床试验 CRF/方案 Word/Excel 文档，要求生成数据字典 - 将问卷/调查表转换为 REDCap 可导入的 CSV 格式 功能特点： - 智能识别表单、分节、字段结构 - 支持单选题、多选题、Likert量表、频率量表 - 自动生成 CDISC 兼容的变量名 - 自动识别图片内容（OCR）用于评分表 - 支持分支逻辑、计算字段、文件上传字段

⚠️ 原 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_3
Form Name	表单英文名	demography, inclusion_exclusion
Section Header	分节标题（仅首字段填写）	患者基本信息
Field Type	字段类型	text, dropdown, radio, checkbox, calc, notes, file
Field Label	字段中文标签	性别, 年龄（岁）
Choices, Calculations, OR Slider Labels	选项或计算公式	1, 男 | 2, 女 或 round([weight]/(([height]/100)^2),1)
Field Note	特殊说明/格式要求	单位：岁, YYYY-MM-DD
Text Validation Type	验证类型	date, number, integer, datetime
Text Validation Min/Max	数值范围	0, 120
Identifier?	是否隐私字段（仅限姓名、身份证等直接身份标识）	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-4	radio	1, 是 | 0, 否
≥5	dropdown	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 术前SOFA	sofa_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 感染时SOFA	sofa_i_pf, sofa_i_total
apach_i_	infection_apache 感染时APACHE	apach_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