17  AI 自动化分析

17.1 概述

ivdtools-analysis 是面向体外诊断（IVD）评价数据的人工智能分析 Skill（当前版本 0.1.0）。它以 R 包 ivdtools 为统计引擎，从 CSV、TSV、Excel 或 RDS 数据出发，完成数据质量检查、统计分析， 并生成可复现的中文 HTML 报告、R 代码、结果表和图形。它适用于 Claude Code（/ivdtools-analysis） 与 OpenAI Codex（$ivdtools-analysis）等对话式代理环境。

边界声明： 本 Skill 用于统计分析和证据整理，不代表临床验证、产品放行或监管批准。涉及临床、 监管或放行决策时，应由合适的专业人员独立复核。

在对话中使用 Skill 的价值不是”替代统计判断”，而是把重复的技术步骤标准化：数据预检、参数确认、 统计计算、结果核验与中文报告生成按固定工作流执行，并把数据来源、参数、排除记录、警告、结果表、 图形与软件环境一起保存，降低遗漏和手工复制错误的风险。

17.2 适用的分析任务

Skill 覆盖 10 类分析任务，均以 ivdtools 的对应模块为统计引擎：

分析类别 典型任务
方法学比对 描述统计、相关、OLS/WLS/Deming/加权 Deming/Passing–Bablok、Bland–Altman、医学决定水平偏倚
ROC 分析 单/多指标 ROC、AUC、截断值、灵敏度/特异度、多变量 Logistic
定性一致性 2×2 表、灵敏度/特异度/预测值、总符合率、Kappa、McNemar
精密度 方差分量、SD/CV、置信区间、剖面结果
分析灵敏度 sadler拟合、空白限/检出限/定量限建立
参考区间 百分位法、参数法、稳健法及其置信区间
稳定性 条件趋势、试验/参考比较、稳定时间、MKT、Arrhenius、稳定性设计
质量控制 Levey–Jennings 图、Westgard 规则违反识别
方程拟合 方程检索、非线性/加权拟合、模型比较、残差诊断
数据检查 离群值候选、正态性检验、瓶间 ANOVA、Youden 图
样本量 Bland–Altman、比例检验、比例置信区间、稳定性设计样本量

17.3 标准工作流

Skill 的分析遵循固定流程，输出目录结构固定，便于核验与追溯。

17.3.1 创建独立输出目录

默认目录名为 <输入文件名>-ivdtools-analysis-YYYYMMDD-HHMMSS，位于 Skill 目录之外，且不覆盖 已有目录。原始数据始终保持只读，不作改写。

17.3.2 数据预检

用 inspect_data.R 生成数据检查 JSON：

Rscript scripts/inspect_data.R \
  --input /data/example.csv \
  --encoding UTF-8 \
  --output /output/data-inspection.json

预检报告行列数、重复行/列名、每列类型与缺失比例、唯一值数、候选二分类字段与候选 ID 字段、 类别水平与数值范围，帮助在分析前发现数据质量问题。

17.3.3 确定分析方案

根据研究目的选择分析类型，并确认不能从数据安全推导的参数。Skill 不会自行编造临床截断值、 允许偏倚、稳定性限值或接受标准；若这些参数影响结论且无法从数据或方案安全推导，会请求用户确认。

17.3.4 执行分析并渲染报告

Skill 把 assets/report-template.Rmd 复制到输出目录，创建带显式参数与 ivdtools:: 命名空间调用 的 analysis.R 完成分析，再渲染中文 HTML 报告。渲染过程保留警告与消息，不静默屏蔽。

17.3.5 核验结果

交付前核验输入总行数与各步排除行数能否对应、缺失/非数值/重复记录是否已报告、阳性类别与方向是否 正确、模型是否收敛、HTML 数值是否与 results/*.csv 一致、是否记录了 sessionInfo() 与实际包版本。

17.4 输出内容

标准交付目录包含：

analysis.R                    # 可复用的分析代码
report.Rmd                    # 报告源文件
report.html                   # 中文 HTML 报告
analysis-manifest.json        # 数据来源、参数和产物清单
session-info.txt              # R 环境和包版本
results/*.csv                 # 机器可读的结果表
figures/*.png                 # 分析图形

中文报告至少包含分析目的、数据来源、数据质量发现、方法和参数、结果表、图形、排除与警告、结果解释、 局限性和可复现性信息。

17.5 安装与使用

17.5.1 运行环境

R ≥ 4.1.0、对应版本的 ivdtools、Pandoc，以及 ggplot2、VCA、VFP、rmarkdown、knitr 等依赖包。先运行环境检查：

Rscript scripts/check_environment.R

输出 STATUS: READY 表示就绪；否则列出缺失项。安装/补齐依赖写入 R 库，只能在用户明确授权后执行 （Rscript scripts/install_ivdtools.R --yes）。

17.5.2 在 Claude Code 中使用

Skill 已注册为可调用技能，在对话中直接调用：

/ivdtools-analysis 分析 /data/method_comparison.xlsx 的 Results 工作表。
样本 ID 为 sample_id，候选方法为 candidate，参考方法为 reference。
按研究方案进行 Deming 回归（lambda=1）与差值型 Bland–Altman 分析，
置信水平 95%，输出可复现的中文 HTML 报告。

17.5.3 在 OpenAI Codex 中使用

在对话中点名 $ivdtools-analysis，并附上数据与分析要求：

请使用 $ivdtools-analysis 分析 /data/roc.csv。
sample_id 是样本 ID，truth 是二分类参考结果，其中 positive 为阳性；
marker1 和 marker2 是待评价指标。请输出 AUC、截断值、敏感度、
特异度、ROC 图和中文 HTML 报告。数据选出的截断值只作探索性结果。

17.5.4 提交任务时建议说明

  1. 数据文件路径（Excel 工作簿还应指定工作表）；
  2. 分析目的与研究设计；
  3. 样本 ID、候选/参考方法、结局、时间、批号等字段对应关系；
  4. 阳性类别、方向、配对/重复结构、精密度设计公式；
  5. 置信水平、效能、统计方法及方案规定的参数；
  6. 医学决定水平、允许偏倚、稳定性限值、QC 目标均值/SD 等接受标准。

17.6 数据处理原则

  • 保留原始列名，不自动调用 make.names() 改名；
  • 不默认填补缺失值、删除离群值、平均重复测量或反转结局方向；
  • 离群值检验只产生待复核的候选记录，不构成自动删除依据；
  • 对排除记录保留依据，并在适用时报告包含/不包含的敏感性分析；
  • 任何数据转换、排除、聚合与事后分析选择都说明操作与理由；
  • 统计显著不等于临床可接受，只能依据方案或用户提供的接受限得出可接受性结论。

17.7 常见问题

  • 版本不符：环境检查提示 ivdtools 版本不符时，不要直接覆盖已安装的新版；选择新的可写 R 库， 授权后将目标版本安装到该目录，并用 --library 检查。
  • Excel 无法预检：确认已安装 readxl；多工作表时用 --sheet 明确选择。
  • HTML 无法渲染：确认 rmarkdown、knitr 已安装且 rmarkdown::pandoc_available() 为 TRUE； 查看 report.Rmd 中记录的实际警告或错误，不静默忽略。
  • 二分类方向反了：检查阳性类别、因子水平、指标方向及试验/参考映射，在重新分析前记录更改方向 与理由。
  • 有离群值或重复测量：不自动删除或平均，先按原始记录、实验设计与预设规则确定处理方式。