make-figures

Make-Figures Skill

数据隐私检查

读取任何数据文件前，请检查其中是否可能包含受保护健康信息（PHI）：

1. 如果工作目录中存在 *_deidentified.* 文件，请优先使用这些文件。
2. 如果只有原始 CSV/Excel 文件（没有对应的 *_deidentified.* 文件），请用用户的语言询问数据是否包含患者身份标识信息（姓名、国民身份证号 / RRN、联系方式等）；如果包含，请先使用 /deidentify skill 对其进行去标识化处理。
3. 如果用户确认数据已去标识化或不包含 PHI，则继续操作。

参考文件

• 图表规范：${CLAUDE_SKILL_DIR}/references/figure_specs.md — 生成任何图表前都要阅读（期刊尺寸、DPI、文件格式、调色板、字号、面板布局、图注格式）。
• 图表样式：${CLAUDE_SKILL_DIR}/../analyze-stats/references/style/figure_style.mplstyle

---

期刊 AI 图像政策（重要 — 生成前检查）

期刊系列	对 AI 生成图像的政策	是否需要披露
JACC 系列（包括 JACC: Asia、JACC Imaging、JACC EP、JACC BTS）	未经主编事先许可，禁止使用（JACC 流程，PMC10167500）	投稿前通过附信咨询 + ICMJE 风格声明
NEJM	禁止 AI 图像生成	不适用
Radiology / Radiology AI	允许，但须披露	手稿披露部分
Springer Nature（Nature Portfolio、BMC、Springer 期刊）	仅当视觉内容源自可独立验证的数据、源材料、方法或代码时才允许；没有可验证输入的 AI 视觉内容属于“不透明”内容，不予允许。基于数据集生成的图表，以及经作者审核、由代码生成的图表，是政策明确允许的示例（手稿准备中的 AI 使用）	声明模型及用途；在图注中披露非生成式图像编辑
Elsevier 期刊（出版商政策）	允许使用说明性图像（流程图、示意图）。数据可视化仅在通过可复现方法直接基于底层数据生成时才允许。**不得使用 AI 创建或修改原始研究图像，包括放射学扫描图和患者图像。**作为研究方法一部分生成的 AI 图像允许使用。图形摘要：使用专门的插图工具，而非通用生成式 AI（期刊生成式 AI 政策）	图注 + AI 披露声明（说明性图像）；方法部分（数据可视化、研究方法用途）
Lancet 系列	必须披露；不鼓励生成	手稿披露
默认（目标期刊未知）	在确认之前视为禁止	不适用

出版商页面设定的是最低标准；期刊自身的指南可能更严格（JACC 是 Elsevier 旗下期刊）。请同时查阅目标期刊指南及其出版商的政策。

硬性规则：对于 JACC、NEJM 或任何“目标期刊未知”的情况，绝不要使用 Gemini / DALL-E / Midjourney / Stable Diffusion / Nano Banana 创建将出现在图表、中央插图或图形摘要中的图像。对手稿正文进行 AI 文本编辑仍可接受，但须遵守常规披露要求。

不允许使用 AI 图像时的默认工作流

1. SMART Servier Medical Art — https://smart.servier.com/，CC BY 4.0，免费，提供 3,000 多个医学矢量图标（解剖结构、器官、特定族裔的人物、药物、设备）。允许用于商业用途和期刊发表。必须注明出处（在图注或方法部分中注明 1 行）：

   解剖图标修改自 SMART Servier Medical Art（CC BY 4.0）。

2. NIAID BioArt（https://bioart.niaid.nih.gov）— 公有领域（美国政府），专注于微生物学、免疫学和实验室技术。
3. BioRender（https://www.biorender.com）— 通常需要机构许可证；使用导出的“Publication-ready” PNG/TIFF，并按照 BioRender 的发表政策引用。
4. 对于无法直接获取的“患病”变体（例如，从健康血管制作钙化血管）：重复使用健康素材，并通过 matplotlib scatter / Circle / PathPatch 叠加疾病标记。这样整个流程无需 AI，且可复现。

即使允许使用 AI 图像，经验丰富的审稿人也能识别出 AI 生成的插图（没有提供信息的小型装饰图标、过于统一的布局、通用剪贴画风格）。对于高影响力投稿，优先选择 Servier / BioArt / BioRender，再用 matplotlib 叠加，而不是使用 AI。

素材目录约定

manuscript/figures/_assets_servier/      # CC BY 4.0 source PNGs
manuscript/figures/_assets_servier/CITATION.md   # source URL + download date per asset
manuscript/figures/_assets_data/         # data-driven raster (R / matplotlib heat maps, KM, etc.)
manuscript/figures/_legacy/              # archived prior versions

构图脚本只能从 _assets_servier/ 和 _assets_data/ 加载素材。如果脚本从 _assets_ai/ 导入素材，则对于 JACC/NEJM/未知投稿目标，应视为违反政策。

AI 图像生成（可选）

AI 插图是补充选项：无需 API 密钥即可完成所有图和视觉摘要。如果设置了 GEMINI_API_KEY，generate_image.py 可以生成插图（程序化示意图、解剖插图），但须遵守政策表和上述硬性规定：

python ${CLAUDE_SKILL_DIR}/scripts/generate_image.py \
  "Clean medical illustration of a CT-guided lung biopsy procedure, \
   flat vector style, white background, no text" \
  --output output.png --aspect 16:9

如果未设置 GEMINI_API_KEY，请使用 ${CLAUDE_SKILL_DIR}/references/medical_illustration_sources.md。

---

视觉摘要 / 图形摘要

European Radiology 从 2025 年 1 月起，要求所有原创文章从首次修订阶段开始提交图形摘要；其他期刊则鼓励或接受此类摘要（状态列表见 template_guide.md）。开始前，请查看目标期刊的资料（write-paper/references/journal_profiles/），了解其视觉摘要要求。

工作流

1. 检查期刊模板。 查看 ${CLAUDE_SKILL_DIR}/references/visual_abstract_templates/{journal}.pptx 中是否有官方 PPTX 模板。 如果没有期刊专用模板，请使用 medsci_default.pptx。
2. 从手稿中提取内容：
   • 标题： 文章完整标题
   • 假设/问题： 根据要点 1 或研究目标提炼（最多 1 句话）
   • 方法： 简要流程图或不超过 3 个项目符号，每项少于 6 个词
   • 视觉元素： 研究自身的图（ROC 曲线、流程图、代表性图像）
   • 徽标： 患者队列（N=...）| 成像方式/器官 | 单中心/多中心
   • 主要发现： 根据要点 3 提炼（少于 20 个词）
   • 引用： 期刊（年份）作者；DOI
3. 选择视觉元素（按优先级排列）：
   1. 研究自身的图（ROC、流程图、代表性图像）— 始终优先
   2. 来自 Servier Medical Art 或 NIAID BioArt 的免费插图 （参见 ${CLAUDE_SKILL_DIR}/references/medical_illustration_sources.md）
   3. 在 PPT/Keynote/Figma 中手动绘制
   4. 通过 generate_image.py --style medical 使用 AI 生成（仅当设置了 GEMINI_API_KEY 时）
4. 使用脚本生成：

   python ${CLAUDE_SKILL_DIR}/scripts/generate_visual_abstract.py \
     --template medsci_default \
     --title "Article Title" \
     --hypothesis "Research question" \
     --methods "Method 1|Method 2|Method 3" \
     --finding "Main finding statement" \
     --citation "Eur Radiol (2026) Author A et al; DOI:..." \
     --visual figures/fig1_roc_curve.png \
     --badges "N=450|CT chest|Multi-center" \
     --output figures/visual_abstract.pptx
   

5. 与用户一起审阅。 打开 PPTX，检查布局和内容。反复修改。
6. 导出。 PPTX 是主要交付文件。要导出 PNG：在 PowerPoint/Keynote 中打开并导出，或使用 LibreOffice CLI（soffice --headless --convert-to png）。

设计：单页，横向（16:9）或遵循期刊模板；分为三个部分（研究问题 → 关键方法 → 主要结果）；使用研究的实际图，而非通用图形；文字精简；不使用装饰性剪贴画。

可用模板

模板	文件	使用场景
MedSci 默认模板	medsci_default.pptx	适用于没有官方模板的期刊
JACC 中央插图	jacc_central_illustration.pptx	适用于 JACC 系列期刊（使用 --type central-illustration）

使用期刊自己的模板。 我们不再分发期刊模板（例如 European Radiology 的 EURA-GA-Jan2025.pptx）：请下载模板并传入其绝对路径：

python ${CLAUDE_SKILL_DIR}/scripts/generate_visual_abstract.py \
  --template /absolute/path/to/EURA-GA-Jan2025.pptx  ...

--template 接受任意 .pptx 文件的绝对路径。脚本根据文本内容而非形状名称定位字段，因此期刊自己的模板无需修改即可使用。如果路径不存在，则回退到 medsci_default.pptx。

添加新期刊模板：请参阅 ${CLAUDE_SKILL_DIR}/references/visual_abstract_templates/template_guide.md。

---

中央插图与视觉摘要

JACC 系列期刊（JACC、JACC: Asia、JACC: Cardiovascular Imaging、JACC: Heart Failure、JACC: CardioOncology、JACC: Clinical Electrophysiology、JACC: Basic to Translational Science）的每篇原创文章都必须附带中央插图（CI）。CI 不是视觉摘要：它传达一个关键发现，且不包含方法。在制作前，请阅读 ${CLAUDE_SKILL_DIR}/references/jacc_central_illustration_principles.md（CI 与 VA 对照表、Fuster-Mann 五项规则、布局和验证阈值）。

CI 模式调用

python ${CLAUDE_SKILL_DIR}/scripts/generate_visual_abstract.py \
  --type central-illustration \
  --visual figures/central_illustration_v2.png \
  --citation "FirstAuthor Last et al. Journal Name 2026; vol(issue):pages." \
  --output submission/jacc_asia/central_illustration.pptx \
  --ci-zones 3 --ci-label-words 22 --ci-numerical-points 2 \
  --ci-raw-text "warranty drops to 3 years in age 45+ with cardiometabolic burden; MASLD HR 1.77"

CI 模式会在渲染前进行验证；出现以下任一情况时会拒绝执行（退出码 2）：区域数 > 3、标签词数 > 30、数值点 > 4，或 --ci-raw-text 中出现方法学术语（队列流程 / 纳入标准 / 排除标准 / 研究设计 / 入组 / 随机化 / 样本量 / CONSORT / PRISMA / STARD）。只有在理由充分时，才使用 --ci-allow {zones|words|numerical|methods} 覆盖单项规则。仅提交内容图和引文：JACC 编辑部会在稿件接收后添加红色边框和蓝色的“CENTRAL ILLUSTRATION:”标题。

---

工作流

图注、图例或插图中的任何引文都必须通过 /search-lit 确认 DOI 或 PMID；无法确认的，请标记为 [UNVERIFIED - NEEDS MANUAL CHECK]。未经确认的临床定义、标准或指南声明请标记为 [VERIFY] 并提出询问——提交门槛会拦截这两类情况。

步骤 1：指定

在指定图类型之前，请先阅读 ${CLAUDE_SKILL_DIR}/references/design_principles.md — 确定（1）一句话概括的核心信息，（2）受众和阅读时间预算，以及 （3）图是否合适（而非小型表格或行内文本）。仅当报告指南强制要求使用该图时才可跳过（例如 PRISMA / CONSORT 流程图）；即便如此，也要应用认知负荷检查清单。

对于报告指南要求的图表，还要加载 ${CLAUDE_SKILL_DIR}/references/reporting_guideline_figure_map.md — 了解哪些指南强制要求哪些 图表，以及此技能提供的是官方模板（✅）、通用流程图（⚠️），还是需要手动制作（❌）。这对 AI 扩展指南（CONSORT-AI、STARD-AI、TRIPOD+AI、 CLAIM 2024、DECIDE-AI）尤为重要。

对于医疗 AI / 工程流程图（DICOM 工作流、标注流程、联邦学习拓扑、模型架构），还要加载 ${CLAUDE_SKILL_DIR}/references/pipeline_concepts_medical_ai.md — 其中包含各类型的标准布局、必需标注和工具选择。

可选标志：

• --study-type <type>：可选值：diagnostic-accuracy、ai-validation、meta-analysis、dta-meta-analysis、observational-cohort、rct、case-report。设置后，无需询问单个图类型，即可根据下方的研究类型图表集表格自动生成完整图表集。
• --data-dir <path>：包含分析输出（CSV、_analysis_outputs.md）的目录。默认值：当前工作目录。

请向用户询问以下信息（根据上下文推断已有信息，并在继续前确认）：

1. 图类型 — 设置 --study-type 时跳过
2. 数据来源（文件路径、DataFrame 或手动输入的值）
3. 目标期刊（用于确定尺寸和字体要求）
4. 面板布局（单面板、多面板，或由你决定）
5. 特殊要求（标注、突出显示、参考线）
6. 研究类型（若未通过 --study-type 传入）：决定所需的图表集

步骤 2：配置

1. 加载图表样式文件（骨架如下）。
2. 在 ${CLAUDE_SKILL_DIR}/references/figure_specs.md 中查询期刊专属尺寸。
3. 设置色盲友好调色板（默认使用 Wong 调色板）。
4. 根据 figure_specs.md，按元素类型设置字号（标题、坐标轴标签、刻度标签、图例、标注）。

步骤 3：生成

使用 Python（matplotlib/seaborn，并按需使用专用库）。根据 ${CLAUDE_SKILL_DIR}/references/exemplar_plots/ 中的数据图解剖模型制作每张图 （索引见其中的 README.md）；箱线图/小提琴图、柱状图和热图应遵循 figure_specs.md 中各类型的规范。流程图绝不使用 matplotlib — 请参阅工具选择指南。

脚本结构：

"""
Figure: {description}
Date: {YYYY-MM-DD}
Target: {journal}
Dimensions: {width} x {height} inches @ {DPI} DPI
"""
import numpy as np
import matplotlib.pyplot as plt
import os

style_path = os.path.join(os.environ.get('CLAUDE_SKILL_DIR', '.'), '../analyze-stats/references/style/figure_style.mplstyle')
if os.path.exists(style_path):
    plt.style.use(style_path)

# Wong colorblind-safe palette
WONG = ['#000000', '#E69F00', '#56B4E9', '#009E73',
        '#F0E442', '#0072B2', '#D55E00', '#CC79A7']

np.random.seed(42)

绝不捏造数据点。如果模板演示需要示例数据，请标注为“示例数据”。 如果由数据驱动的 .py/.R 脚本生成图表（ROC、森林图、KM、校准图、 热图），在最终确定前，使用 /analyze-stats 代码质量门禁检查该脚本 （check_generated_code.py {script} --strict）：它会检查是否缺少自助法 CI 区间带所需的绘图随机种子、是否使用了硬编码的绝对数据路径，以及是否手动输入了本应从分析 CSV 读取的数据字面量。

步骤 4：审阅

向用户展示图表（布局、标签和标注、颜色/尺寸/强调方式），并反复调整， 直到用户批准。

步骤 4b：评审循环（最终导出前进行自我评审）

在步骤 5 导出之前，分两个阶段进行检查——先做确定性的定量检查，再进行定性评审——以决定是否重新渲染或交由用户处理。

阶段 1：定量检查（critic_figure.py）

python ${CLAUDE_SKILL_DIR}/scripts/critic_figure.py \
    figures/fig1_stard.png \
    --type stard \
    --spec-min-dpi 600 \
    --spec-width-in 7.0 \
    --source-text figures/fig1_stard.txt \
    --out figures/fig1_stard.critique.json

--source-text 是可选项（用于检查 OCR 覆盖率的预期字符串）。JSON 报告涵盖 DPI 和相对于期刊规范的实际宽度、主导颜色分布及不符合 Wong 调色板的比例，以及 OCR 字数、最小文字高度和源文本词语覆盖率。如果图像不含 DPI 元数据，DPI 检查会使用规范宽度下的分辨率（width_px / --spec-width-in）。无法运行的检查（缺少 DPI 元数据时的实际宽度检查、缺少 pytesseract 时的 OCR 检查）会列在 not_run 下，摘要显示 INCOMPLETE，绝不会显示 PASS；--strict 遇到 INCOMPLETE 时会以代码 3 退出。

阶段 2：定性评审

1. 使用 Read 工具加载生成的 PNG。
2. 阅读对应的评审标准文件（每个文件包含 A–G 部分）：
   • 流程图：${CLAUDE_SKILL_DIR}/references/critic_rubrics/flow_diagram.md
   • 数据图：${CLAUDE_SKILL_DIR}/references/critic_rubrics/data_plot.md
   • 对于 PRISMA / CONSORT / STARD / STROBE，还要阅读 ${CLAUDE_SKILL_DIR}/references/flow_diagram_lessons.md（官方模板的忠实度、通过 VML 回退导出 PDF、docx XML 转义、占位符顺序映射、与手稿同步冻结版本）。
   • 对于 AI 扩展指南或流水线图，还要对照步骤 1 中加载的 reporting_guideline_figure_map.md 对应行 / pipeline_concepts_medical_ai.md 进行检查。
3. 阅读 ${CLAUDE_SKILL_DIR}/references/exemplar_diagrams/{type}/ 中的 _why.md 设计说明——层级、留白、排版、强调方式、颜色。**这些是评审基准。**如果其中包含渲染后的示例文件（template_output*.png），也用 Read 阅读其中 1–2 个。不会提供从已发表论文中裁剪的图表（参见该目录的 README）；可以改用用户自己的本地示例。对于非流程图的数据图，请阅读 ${CLAUDE_SKILL_DIR}/references/exemplar_plots/ 中对应的结构模型（例如 forest_plot.md）。
4. 按照评审标准文件末尾的格式，为每个评审项打 PASS / PARTIAL / FAIL，并附上一行说明。
5. 输出 “下次渲染前的必要修改” 列表，列出具体的源代码修改（节点／标签重命名、计数修正、matplotlib 参数调整）。

优化循环

• 如果所有项目均为 PASS → 使用 critic_pass: yes 继续执行步骤 5 导出。
• 如果有任何项目为 FAIL → 对源文件（流程图配置／R 脚本或 matplotlib 脚本）应用必要修改，重新渲染，并重新运行阶段 1 + 阶段 2。默认最多 T=2 轮；用户可要求最多 T=3 轮。
• 如果达到最大轮数后仍有项目为 PARTIAL，则使用 critic_pass: partial 继续，并将剩余项目记录在清单的 critic_notes 字段中。

在 _figure_manifest.md 中记录最终状态（参见 Study-Type Figure Sets），以便后续步骤（/write-paper 第 2 阶段嵌入和第 7 阶段 DOCX 构建）以及未来的评审循环查看历史记录。

步骤 5：导出

将最终输出保存到 analysis/figures/（analysis/figures/*.pdf、analysis/figures/*.png）：

• PDF（矢量格式，期刊投稿首选）
• PNG（300 DPI 光栅图，用于审阅和演示）
• TIFF（如果期刊要求，使用 300 DPI LZW 压缩）——使用 export_portal_tiff.py 生成，不要使用原始的 magick ... output.tiff：这样可以保留 alpha 通道 （透明区域在许多制作流水线中会打印成黑色），并避免未压缩文件过大（600-dpi RGBA TIFF 会超过投稿门户的 25 MB 上限）。该脚本会将 RGBA 白底合成为 RGB、使用 LZW 压缩，并验证结果与合成后的图像逐像素一致。在门户仅接受 .tiff/.jpeg/.eps（Springer Nature SNAPP）或限制图像大小（JACC: Asia）时使用：

  python3 ${CLAUDE_SKILL_DIR}/scripts/export_portal_tiff.py --in figure.png --out figure.tiff --max-mb 25
  # exit 1 if still over the cap
  

使用描述性文件名：fig1_roc_curve.pdf、fig2_consort_flow.pdf 等。

对于 PPTX 输出（视觉摘要、中心插图或任何将包含该图的演示文稿）：交付前运行 Mac 兼容性验证器。PowerPoint Mac 会静默丢弃 TIFF，将 <a:sp3d> 3-D 斜面渲染为 PDF 导出中看不到的红色轮廓，并且在 app.xml 中的幻灯片计数与实际幻灯片 XML 文件不一致时拒绝打开文件。

python ${CLAUDE_SKILL_DIR}/scripts/validate_pptx_mac_compat.py \
    figures/visual_abstract.pptx \
    --json figures/visual_abstract.mac_compat.json \
    --strict

退出代码 1 表示至少有一项 FAIL——根据 JSON 报告中的 fix: 字段修复，并在交付前重新渲染 PPTX。退出代码 0 且带有 WARN 可以接受。如果插图仅为 PNG/PDF（没有 PPTX），则跳过此步骤。

步骤 6：设计质量检查清单

交付最终插图前，确认以下所有项目：

• 字体：无衬线字体（Arial/Helvetica），最小字号 7 pt，坐标轴标签 ≥ 9 pt
• 颜色：使用 Wong/Okabe-Ito 色盲友好调色板
• 色盲测试：适用于绿色盲（不只依赖红绿色差异）
• 灰度测试：以黑白打印时信息仍完整保留
• 对齐：所有元素遵循统一网格；各面板对齐
• 矢量输出：已保存 PDF/SVG（不能只有 PNG）
• 分辨率：光栅元素 ≥ 300 DPI，线稿 ≥ 600 DPI
• 期刊规范：尺寸、字体和格式符合目标期刊要求（如果插图超出限制，请调整尺寸并报告调整情况）
• 无图表装饰：没有 3D 效果、不必要的网格线、渐变填充或装饰元素
• 图注：根据 figure_specs.md（图注撰写指南）起草，包含关键发现、缩写、统计细节和样本量

---

研究类型对应的图集

已知研究类型（来自 /write-paper 第 0 阶段或用户指定）时，应生成所需的完整图集，无需逐一询问是否生成每张图。

研究类型（指南）	必需图表
诊断准确性（STARD）	STARD 流程图、ROC 曲线、混淆矩阵、校准图
AI 验证（TRIPOD+AI / CLAIM）	流程图、ROC 曲线、混淆矩阵、校准图、特征重要性或 SHAP、Grad-CAM（如涉及成像）
荟萃分析（PRISMA）	PRISMA 流程图、森林图、漏斗图
DTA 荟萃分析（PRISMA-DTA）	PRISMA 流程图、配对森林图（Se + Sp）、SROC 曲线、Deeks 漏斗图
观察性队列研究（STROBE）	流程图、Kaplan-Meier 曲线（如终点为生存结局）
RCT（CONSORT）	CONSORT 流程图、主要终点图
病例报告 / 病例系列（CARE）	临床时间线图（exemplar_plots/clinical_timeline.md）；在视觉呈现对论证至关重要时，提供带注释的多模态成像面板（exemplar_plots/imaging_panel.md）；病例系列还需提供全病例汇总表
肿瘤治疗研究（CONSORT RCT 或单臂 II 期；生物标志物子集采用 REMARK）	CONSORT 或队列流程图、带风险人数表的 Kaplan-Meier PFS/OS 曲线（exemplar_plots/km_curve.md）、最佳疗效瀑布图（exemplar_plots/waterfall_plot.md）、疗效持续时间泳道图（exemplar_plots/swimmer_plot.md）、疗效动态重要时采用蛛网图（exemplar_plots/spider_plot.md）、存在竞争风险时采用累积发生率而非 1 - KM（exemplar_plots/cumulative_incidence.md）

必须提供清单。 生成所有图表后，编写 analysis/figures/_figure_manifest.md——每张图占一行（Figure | Path | Type | Tool | Critic | Rounds | Description），并添加 ## Critic notes 部分，记录任何剩余的 PARTIAL 项及接受这些项的原因。/write-paper 第 2 阶段（嵌入图表）和第 7 阶段（构建 DOCX）会使用此文件；完成前请确认文件存在且非空。编写时请阅读 ${CLAUDE_SKILL_DIR}/references/figure_manifest.md（了解格式和字段定义）。

工具选择指南

Data plots:    matplotlib/seaborn → PDF + PNG (this skill)
Flow diagrams: generate_flow_diagram.R (DiagrammeR + rsvg) → PDF + 300/600 dpi PNG
Final assembly: pandoc or python-docx (auto-embedded in DOCX)

流程图 → 专用工具（不要使用 matplotlib）

STARD / CONSORT / PRISMA / STROBE 流程图必须使用标准化的 R 流水线 scripts/generate_flow_diagram.R（DiagrammeR + Graphviz dot + rsvg）——这是四种流程图唯一的规范工具。 不要使用 matplotlib FancyBboxPatch（手动设定坐标会在文本变更时出错，而且嵌入 DOCX 时图形块会变形）。不要使用 D2 绘制新的流程图（字体控制较弱，重叠问题需要手动后处理）；仅当 R 不可用时，才将 D2 用作旧版备用方案。

类型	推荐工具	原因
STROBE（队列 / 横断面）	scripts/generate_flow_diagram.R --type strobe	唯一规范工具；自动布局；矢量 PDF + 300/600 dpi PNG
CONSORT（RCT）	scripts/generate_flow_diagram.R --type consort	同一流水线；默认使用单色 Arial
PRISMA 2020（SR/MA）	scripts/generate_flow_diagram.R --type prisma	忠实实现 PRISMA 2020 结构；避免 PRISMA2020 R 包基于 webshot 的栅格 PDF 问题
STARD（DTA）	scripts/generate_flow_diagram.R --type stard	同一流水线；支持 2x2 参考标准拆分
流水线图	D2（旧版）	在 R 脚本加入流水线图支持之前使用

YAML 配置 → Rscript ${CLAUDE_SKILL_DIR}/scripts/generate_flow_diagram.R --type <t> --config <yaml> --out <prefix> → PDF + 300/600 dpi PNG。模板位于 references/exemplar_diagrams/{strobe,consort,prisma,stard}/template_input.yaml。 生成流程图时，请阅读 ${CLAUDE_SKILL_DIR}/references/flow_diagram_recipe.md（YAML 架构、固定样式、每个项目的 create_figure1.R 模式、D2 备用方案）；ROC 曲线或森林图不需要这些内容。

每个方框标签都包含其计数（例如，"Assessed for eligibility\n(n = 450)"）。标签中的数字必须从 CSV 派生——使用读取上游数据的 R/Python 脚本编写 YAML——或者仅当数值存在于纳入版本控制的提交数据工件中时才可手动填写（在注释中注明源文件）。

图注 ↔ 流程图 SSOT 对账（第 5 步“导出”之前）。 流程图配置是参与者计数的唯一事实来源；当队列重新锁定但图注未更新时，手写的图 1 图注会与其不一致（“图注写着分析样本 n = 1,284，流程图方框写着 n = 998”）。请根据流程图配置重新推导图注中的计数并进行对账：

python3 ${CLAUDE_SKILL_DIR}/scripts/derive_figure_legend_counts.py \
  --flow-config figures/figure1_strobe_graphviz.yaml \
  --manuscript manuscript/index.qmd \
  --out qc/figure_legend_counts.json --strict

图注中任何不属于流程图配置方框计数的 n = N 都属于 MISMATCH（图注过时）——请根据配置更新图注，绝不可反过来修改配置。该对账工具仅使用标准库，并将配置解析为文本，因此无论使用哪种流程图工具都能正常工作。找不到图 1 图注，或图注中没有 n = N 时，判定结果为 NOT_CHECKED（使用 --strict 时退出码为 2），而非 OK。

已知限制：只读取 n = N 格式（不会识别单独写成“1,150 patients”的情况），且一致性按集合成员关系判断，因此无法检测计数被移到错误方框的情况（排除与分析的计数对调）；请对照流程图目视检查此类问题。

官方报告规范模板 → templates/official/

如果期刊要求使用规范制定机构发布的标准模板（而非自动排版的 R 版本），请使用随附的官方文件，路径为 templates/official/{prisma2020,consort2010,stard2015,spirit2013}/。

规范	随附内容	使用时机
PRISMA 2020	本地构建的 .pptx（4 种变体）+ fill_prisma_template.py	审稿人要求使用官方 PRISMA 2020 布局，或者你希望使用可编辑的 PowerPoint，而非由 R 渲染的 PDF。
STROBE（队列研究）	参数化 .pptx 构建器 build_strobe_template.py（YAML 配置）	队列研究／病例对照研究的 Figure 1，且合著者希望获得可手动编辑的 PowerPoint。可选的左侧阶段列：省略 stages: 可采用标准 STROBE 规范；包含该项则使用 PRISMA 风格的识别／筛选／纳入／分析列。搭配 generate_flow_diagram.R --type strobe 生成用于投稿的矢量 PDF/TIFF 文件。
CONSORT 2025	官方 .docx 流程图 + 核对清单	向要求使用 consort-spirit.org 模板的期刊投稿 RCT。
STARD 2015	官方 .pdf 流程图 + .docx 核对清单	诊断准确性研究；流程图为固定 PDF，核对清单可编辑。
SPIRIT 2025	官方 .docx 参与者时间线 + 核对清单	试验方案。

刷新／填充工作流：

# Refresh from canonical sources (CC-BY 4.0 / public-statement licenses)
bash ${CLAUDE_SKILL_DIR}/scripts/fetch_official_templates.sh

# Build PRISMA 2020 .pptx (one-time; site blocks programmatic .docx fetch)
python3 ${CLAUDE_SKILL_DIR}/scripts/build_prisma2020_template.py \
    --variant new \
    --out ${CLAUDE_SKILL_DIR}/templates/official/prisma2020/PRISMA_2020_flow_new_v1.pptx

# Fill counts — positional 10-tuple matching most SR/MA workflows:
#   n_db, n_dup, n_screened, n_screen_excluded,
#   n_sought, n_assessed, n_excl_r1, n_excl_r2, n_excl_r3, n_studies
python3 ${CLAUDE_SKILL_DIR}/scripts/fill_prisma_template.py \
    --template ${CLAUDE_SKILL_DIR}/templates/official/prisma2020/PRISMA_2020_flow_new_v1.pptx \
    --counts "315,122,186,7,111,204,102,84,3,15" \
    --out fig1_prisma_filled.pptx

# Or use full JSON mapping for studies with non-standard PRISMA splits
python3 ${CLAUDE_SKILL_DIR}/scripts/fill_prisma_template.py \
    --template ${CLAUDE_SKILL_DIR}/templates/official/prisma2020/PRISMA_2020_flow_new_v1.pptx \
    --counts-file my_counts.json \
    --out fig1_prisma_filled.pptx

# STROBE — parametric single-script builder (cohort study; spine structure varies per study).
# YAML schema: stages, spine (id/stage/text), exclusions (after/text). Consecutive same-stage
# rows share one phase label automatically.
python3 ${CLAUDE_SKILL_DIR}/scripts/build_strobe_template.py \
    --config figures/figure1_strobe.yaml \
    --out    figures/figure1_strobe.pptx

STROBE 构建器会检查排除人数的递减链是否闭合：对于每条声明了排除人数的连接，主干框中的人数减去其后的排除人数总和，必须等于下一个主干框的人数（A - Σ(exclusions after A) == B）。如果人数不平衡，它会发出醒目警告；使用 --strict-cascade 时则会拒绝构建——从而捕捉图表人数计算偏差（例如漏掉一项排除，导致图表人数少于分析 N），这是文本和正文检查无法发现的。运行 python3 ${CLAUDE_SKILL_DIR}/scripts/_strobe_cascade.py --config figure1_strobe.yaml --strict 可在不重新构建图表的情况下检查配置。若配置不符合任何一种模式，则退出码为 2；在 --strict 模式下，如果主干配置中没有可检查的排除连接，也会以退出码 2 结束，而非报告 OK。

已知限制：系统可识别 generate_flow_diagram.R 的节点／边模式，但不会进行评估；辅助脚本会输出 NOT_ASSESSED，并以退出码 0 结束。此前曾尝试判断虚线排除项是从哪个框中扣除的，但这会将正确的图表误标为错误（排除项位于暴露／未暴露或指标阳性／阴性分组之前的框旁，且前一步本身也有排除项），因此暂不处理此问题。请逐一目视检查每个虚线排除项与其相邻框是否对应。

对于 STROBE，KJR/Radiology/BMJ 的标准投稿流程如下：

1. 通过自动适配的 Graphviz 路径渲染用于投稿的矢量文件： Rscript ${CLAUDE_SKILL_DIR}/scripts/generate_flow_diagram.R --type strobe --config figures/figure1_strobe_graphviz.yaml --out figures/figure1
2. 通过 build_strobe_template.py 构建可编辑的 PowerPoint 配套文件，以便合著者和资深审稿人在签字确认前调整文字／位置。
3. 仅在整合合著者的修改后，再将最终 PPTX 导出为 PDF/TIFF。

许可证、署名和刷新说明请参见 templates/official/NOTES.md。

---

样式规则

配色、字体大小、面板布局和图注格式见 figure_specs.md。此外：

• 所有图中文字（标签、图例、注释）均使用英文；医学术语始终使用英文。
• 不能仅用红色和绿色来区分。折线图除颜色外，还要使用线型（实线、虚线、点线）；散点图除颜色外，还要使用标记形状。
• 面板标签：大写粗体字母（12 pt），置于每个面板的左上角。
• 绘图本身不添加图标题（标题放在图注中）。
• 多面板图应按网格对齐；可比较面板的坐标轴范围应保持一致。
• 显著性星号（* p<0.05、** p<0.01、*** p<0.001）置于比较括号上方；具体 p 值应报告在图例或图注中，而不是绘图中。
• 对于 AUC、相关性或一致性指标：在图例中显示，并附上 95% CI。

技能交互

何时	调用	用途
需要绘图统计值时	/analyze-stats	获取计算值（AUC、CI、p 值）
需要论文流程图时	/write-paper Phase 2	与表格和图表计划协调
需要审阅图注时	/write-paper Phase 7	进行最终润色