alterlab-redcap-cdisc

REDCap 与 CDISC — 研究数据采集与标准对齐

在 REDCap 中设计**经验证的电子数据采集（EDC）**工具，并将研究变量与 CDISC 提交标准对齐。它负责两项工作，这两项工作仅在边缘部分与同类技能重叠：

1. REDCap 项目与工具设计 — 将研究需求转化为 REDCap 数据字典（可导入的 18 列 CSV），并正确设置字段类型、验证、分支逻辑、纵向事件和调查设置。
2. CDISC 对齐 — 将采集的变量映射到 CDASH（采集）和 SDTM（制表）域，并将编码值关联到 CDISC 受控术语（NCI-EVS），以便数据可用于提交和重复利用。

这是设计与标准相关的工作，不是实时 API 连接器。生成 CSV 和映射属于此技能范围；将其导入运行中的 REDCap 服务则由实例所有者负责（使用 REDCap 自带的 API/UI）。

快速开始

Build me a REDCap data dictionary for a 3-arm RCT screening + follow-up.
Add branching logic so the pregnancy question only shows when sex = female.
Lint this data_dictionary.csv before I import it.
Map my CRF variables to CDISC SDTM domains and CDASH fields.
Which SDTM domain and controlled-terminology codelist does "adverse event" go in?

→ 起草或读取数据字典，运行 scripts/lint_data_dictionary.py 以发现结构错误，然后（对于 CDISC）生成变量 → CDASH → SDTM 映射表。务必说明哪些内容属于设计惯例，哪些因实例而异。

---

何时使用此技能

当请求涉及构建工具或使其符合标准时，请使用此技能：

• “构建 / 设计一个 REDCap 项目、表单或数据字典。”
• “为这些变量编写可导入的 REDCap CSV。”
• “设置分支逻辑 / 显示字段逻辑 / 字段验证 / 必填字段。”
• “配置纵向事件 / 组 / 重复工具 / 调查。”
• “在导入前检查 / 验证 / 调试我的数据字典。”
• “将我的研究映射到 CDISC — 应使用哪个 SDTM 域 / CDASH 字段 / 代码列表？”
• “使我的 CRF 满足提交要求（SDTM/CDASH/CDISC CT）。”

不适用 — 转交给相应的同类技能

请求实际涉及……	转交给
将 ELN 接入 REDCap；通过其 REST API 读取 / 写入 LabArchives 笔记本条目或附件	alterlab-labarchive
心理测量学 — 李克特量表构建、响应偏差缓解、抽样策略、试点测试、信度 / 效度（Cronbach's α、因子分析）	alterlab-survey-design
选择或执行统计检验、检验假设、功效 / 样本量、APA 结果	alterlab-statistical-analysis
KVKK / 土耳其数据保护计划、匿名化、VERBIS、açık rıza	alterlab-kvkk-dmp
IRB / 伦理申请、知情同意、GDPR/HIPAA、涉及人体受试者的方案	alterlab-research-ethics（土耳其 etik kurul 则使用 alterlab-tr-research-ethics）
在 ClinicalTrials.gov 上按疾病 / NCT ID 查找已注册试验	alterlab-clinicaltrials
ISO 13485 医疗器械 QMS 文档	alterlab-iso13485

路由经验法则：survey-design 负责问题及其测量属性；此技能负责采集这些问题答案的数据库及其标准映射。 如果用户两者都需要（例如“设计一个经验证的抑郁量表，并为其制作 REDCap 表单”），则在 alterlab-survey-design 下完成量表工作，在此处完成数据字典 / 映射工作。

---

REDCap 数据字典（可导入的 CSV）

REDCap 项目由数据字典定义——一个包含 18 列且顺序固定的 CSV。编写或修复此 CSV 是核心交付内容。

#	列标题	用途
1	Variable / Field Name	小写的机器可读名称（用于导出/分析）。
2	Form Name	此字段所属的问卷。
3	Section Header	显示在字段上方的分节标题。
4	Field Type	以下列出的某个值。
5	Field Label	表单上显示的易读提示词。
6	Choices, Calculations, OR Slider Labels	对于选项字段，填写 1, Yes | 0, No；对于 calc，填写计算公式。
7	Field Note	显示在字段下方的辅助文本。
8	Text Validation Type OR Show Slider Number	text 字段的验证类型；滑块显示设置。
9	Text Validation Min	下限（整数/数值/日期）。
10	Text Validation Max	上限。
11	Identifier?	y 表示 PII/PHI（决定去标识化导出）。
12	Branching Logic (Show field only if...)	显示字段的条件。
13	Required Field?	y / 留空。
14	Custom Alignment	布局。
15	Question Number (surveys only)	问卷编号。
16	Matrix Group Name	将矩阵字段分组。
17	Matrix Ranking?	矩阵排序标记。
18	Field Annotation	操作标签/注释（例如 @HIDDEN）。

Field Type 的取值： text、notes、dropdown、radio、checkbox、 calc、sql、descriptive、slider、yesno、truefalse、file。

Text Validation Type 的取值（内置）： 日期类型 date_ymd / date_mdy / date_dmy，对应的 datetime_* 和 datetime_seconds_* 格式，time、 time_hh_mm_ss、time_mm_ss、integer、number 和 number_1dp…number_4dp （以及对应的 *_comma_decimal 变体）、email、phone、zipcode、alpha_only，以及 一些区域/ID 格式（完整列表见参考文档）。autocomplete 用于 dropdown 字段， signature 用于 file 字段。管理员可以针对每个实例禁用某些类型，因此请通过测试导入确认。

更深入的逐字段规则、选项字符串语法、分支逻辑运算符、纵向/重复问卷设计，以及一个完整示例数据字典，见 references/redcap_design.md。

导入前进行 lint 检查

uv run python skills/faculty-life/alterlab-redcap-cdisc/scripts/lint_data_dictionary.py \
    path/to/data_dictionary.csv

此 lint 工具仅使用标准库（无需网络或 REDCap 账号）。它会检查 18 列的表头、字段名称语法、字段类型/验证类型是否合法、选项字段是否包含选项字符串、calc/分支字段引用的变量是否存在（允许使用 [visit_1_arm_1][weight_kg] 这类事件前缀）、变量名称是否重复，以及 PII 字段是否未标记为 Identifier?。发现问题时，它会以非零状态码退出并生成 JSON 报告。这是一个结构性 lint 工具——它不会对照在线 REDCap 服务进行验证，因此即使 lint 检查无误，也务必告知用户仍需进行测试导入。

---

CDISC 对齐（CDASH → SDTM → 受控术语）

CDISC 在整个数据生命周期中定义了相互补充的标准。按照研究方案进行映射，使收集的数据可用于监管申报和重复利用。

标准	角色	产出内容
CDASH	数据收集 — CRF 上用于收集数据的标准字段；可追溯到 SDTM。	按照 CDASH 规范命名的 CRF/REDCap 字段。
SDTM	制表 — 将提交的数据整理到各个域中。	变量 → 域的映射。
受控术语	有效值代码列表（NCI-EVS）。	与正确代码列表关联的编码值。

SDTM 观察类别： 干预、事件、发现和发现补充，以及 DM 人口统计等特殊用途域。常见域及其两字母代码：AE 不良事件、VS 生命体征、LB 实验室、EX 暴露、CM 合并用药、MH 病史。

受控术语由 NCI 的企业词汇服务（NCI-EVS）维护，每季度更新；不要自行编造代码列表值——注明代码列表，并告知用户获取当前季度版本。

版本确实会更新——此技能记录了其于 cdisc.org 上最后一次核实的最新版本（2026-09-23）：SDTMIG v3.4（2021-11-29），基于 SDTM v2.0；SDTM v2.1（2024-06-10）是最新的模型版本，并随烟草实施指南发布；CDASHIG v2.3（2023-09-28，CDASH Model v1.3）；当前季度受控术语版本为 2026-03-27。新的 SDTMIG 域正在公开征求意见（意见提交截止日期为 2026 年 10 月 2 日）。在交付内容中声明版本前，请与用户、cdisc.org 以及监管机构的数据标准目录确认当前版本，因为这些版本会重新发布。映射方法、CDASH↔SDTM 可追溯性理念以及 AE/VS 示例见 references/cdisc_mapping.md。

---

工作流

1. 收集需求。 研究设计（横断面／纵向／分组）、变量、值集、PII 字段，以及是否为问卷。如果问题的测量属性很重要，请先将问卷设计交由 alterlab-survey-design 处理。
2. 起草数据字典。 构建包含 18 列的 CSV：机器名称、字段类型、选项、验证规则、每个 PII 字段对应的 Identifier?、分支逻辑，以及单独制定的（纵向研究）事件／分组计划。
3. 运行 lint 检查。 运行 scripts/lint_data_dictionary.py；在用户导入前修复所有错误。
4. （如需提交／标准）映射到 CDISC。 生成变量 → CDASH → SDTM 表，标记需要受控术语的值集，并注明代码列表名称——绝不编造代码列表成员。
5. 如实报告。 说明哪些选项属于惯例、哪些属于实例配置；指出 lint 检查仅验证结构（仍需进行测试导入）；并说明必须根据当前版本确认 CDISC 版本。

---

报告前自查

• 数据字典是否按顺序包含且仅包含 18 列？每个字段类型是否合法？
• 每个 PII 字段是否都标记为 Identifier? = y？
• 所有分支逻辑和 calc 表达式是否都引用了数据字典中实际存在的变量？
• 是否运行并通过了 linter？是否告知用户，即使 lint 检查通过，仍需进行真实测试导入？
• 对于 CDISC：是否注明代码列表／版本而非编造代码列表值，并指出必须根据当前版本进行确认？
• 是否将心理测量学工作转交给 alterlab-survey-design，并将 ELN 桥接工作转交给 alterlab-labarchive，而非在此处处理？

---

参考资料

• references/redcap_design.md — 完整的 18 列字段参考、选项字符串语法、分支逻辑运算符、验证类型、纵向/重复测量工具设计，以及一份示例数据字典。
• references/cdisc_mapping.md — CDASH→SDTM→CT 流程、SDTM 观察类别和领域、受控术语来源，以及 AE/VS/DM 映射示例，并附有已验证的版本和来源。

属于 AlterLab Academic Skills 套件。