radiomics-ml

放射组学 / 经典机器学习技能

用途

放射组学 + 树集成研究（特征 → 随机森林 / XGBoost → 临床结局）是最常见的可由个人完成的临床机器学习工作流——无需 GPU 或工程师——也是最容易过度乐观的工作流：数十名患者对应数百至数千个特征，在同一组交叉验证折上调优超参数并报告性能，在整个数据集上选择特征，从不筛除不稳定特征，只报告区分度（AUC）而不评估校准。本技能可正确构建流水线并审查现有流水线，使临床结果经得起审查（Lambin 2017；CLEAR；TRIPOD+AI；PROBAST-AI）。

它与影像深度学习路径并列：/model-scaffold 构建深度网络，而 radiomics-ml 涵盖基于特征的经典机器学习路径。它会集成 scikit-learn / xgboost / pyradiomics（在生成的代码中引用）；不会重新实现这些工具，也绝不会在真实患者数据上运行模型。

适用场景

• 你有放射组学或临床 / 表格特征数据，想构建能够通过统计审查的随机森林 / XGBoost 临床预测模型。
• 你想审查现有放射组学 / 机器学习流水线，检查下列失效模式。

不适用场景

• 深度学习影像模型 → /model-selection → /model-scaffold → /model-assessment。
• 经典推断统计 / 以回归模型为估计目标 → /analyze-stats。
• 已训练网络的可解释性 → /model-assessment。
• 重新实现 scikit-learn / xgboost / pyradiomics → 不在适用范围内（本技能会接入并审查这些工具）。

失效模式（门控检查所强制执行的要求）

1. 没有嵌套交叉验证。 在同一组交叉验证折上调优并报告会夸大性能。请使用嵌套交叉验证或留出的测试集。
2. 高维度、低事件数。 候选特征数 ≥ 事件数会导致过拟合——这是经典的放射组学陷阱。声明 dimensionality_reduction 并不能消除此问题：n_features 统计的是经过结局盲法降维后剩余的特征数。门控检查中的 p ≥ events 规则（events = 少数类）只是用于发现最严重情况的底线，并非样本量标准：请使用 /calc-sample-size 的 Test 12（Riley 标准，pmsampsize）计算研究样本量，统计每个进入结局驱动型特征选择或模型拟合的候选特征。在 C = 0.75、患病率为 35% 时，每个候选参数约需 48 名患者：100 个候选参数需要 N = 4,755（1,665 个事件），而门控检查在 105 个事件时仍会放行 100 个特征。应先在不使用结局信息的情况下减少候选特征（稳定性、冗余度、临床先验）；LASSO 或其他惩罚方法不能替代样本量要求，因为它估计的收缩量在 n 较小时本身也不稳定（Riley et al., J Clin Epidemiol 2021；Van Calster et al., Stat Methods Med Res 2020）。
3. 在交叉验证折之外进行特征选择。 在整个数据集上拟合特征选择器会造成留出折泄漏。应将特征选择嵌套在每个训练折中。
4. 没有特征稳定性评估。 放射组学特征在采集 / 分割过程中可能不稳定——应筛选出可重复的特征（ICC / 重测）。
5. 没有校准评估。 临床预测模型需要评估校准（斜率 / 截距 + 灵活曲线），不能只评估区分度。
6. 没有外部验证。 基于单一队列的模型若要支持临床结论，需要外部 / 时间验证。

门控检查无法从清单中验证，因此未纳入其中的事项：同一患者的记录出现在拆分的两侧。 按行划分交叉验证折的病灶级表格会让模型识别出患者；在零效应合成数据上，这使嵌套交叉验证 AUROC 从 0.48 升至 0.99。请按患者划分数据并检查交叉验证折表格（阶段 2）。

工作流

阶段 1 — 提取特征（集成，而非重新实现）

对于影像组学，使用 pyradiomics，并采用可复现且符合 IBSI 的设置（固定分箱宽度、重采样、归一化）进行特征提取——记录这些设置。对于临床／表格数据，构建包含患者／受试者 ID 和结局的特征表。每个病灶或 ROI 占一行即可；折叠划分依据的是 ID。请参阅 references/radiomics_ml_guide.md。

阶段 2 — 正确构建工作流

• 特征稳定性 — 对于重测／多评估者数据，保留 ICC ≥ 0.75 的特征。
• 嵌套交叉验证 — 外层折叠用于估计性能，内层折叠用于调参；在每个训练折叠内进行特征选择和缩放（绝不可使用整个数据集）。交叉验证的单位是患者：两个循环都使用 StratifiedGroupKFold(groups=patient_id) 进行划分，确保同一患者的病灶不会分散到不同折叠中；写出折叠表（patient_id,split），并使用 /model-assessment 的 check_split_leakage.py --splits cv_folds.csv --seed <seed> --strict 验证（指南 §4 中提供了框架）。
• 维度 — 不依据结局缩小候选集（ICC 稳定性、|r| 冗余过滤、临床先验；PCA 在折叠内拟合），然后使用 /calc-sample-size Test 12（pmsampsize），根据剩余候选特征的数量确定研究规模。LASSO 会在折叠内进行选择，但无法让小样本变得足够大；若 N 低于 Riley 最低要求，请将样本量不足报告为局限性。
• 模型 — 根据任务从完整的经典模型系列中选择；除任何复杂学习器外，还必须提供简单的基线模型（惩罚逻辑回归）：
  • 惩罚回归 — LASSO / ridge / elastic-net logistic（也可作为基线）
  • 间隔／核方法 — 线性或 RBF SVM
  • 基于实例的方法 — k-NN
  • 概率／判别方法 — naive Bayes、LDA / QDA
  • 树与装袋法 — decision tree、random forest、extra-trees
  • 提升法 — XGBoost、LightGBM、CatBoost、HistGBM、AdaBoost
  • 浅层神经网络 — MLP
  • 元方法 — stacking / voting ensembles
  • 无监督（上游） — 使用 PCA / UMAP 降维，使用 k-means / hierarchical / GMM 进行表型分析 下方的门槛与学习器无关——它审核的是整个工作流（嵌套交叉验证、数据泄漏、维度、校准），因此同样适用于上述所有方法。完整的方法映射请参阅 docs/method_coverage_map.md。
• 报告 — 报告区分度和校准度（斜率／截距 + 灵活曲线，参阅 /analyze-stats 校准指南），以及临床效用（决策曲线）。使用 SHAP 进行解释。

阶段 3 — 输出管线清单

{
  "task": "classification",
  "n_features": 40, "n_samples": 300, "n_events": 110,
  "cv_scheme": "nested",
  "feature_selection_stage": "inside_cv",
  "dimensionality_reduction": true,
  "feature_stability": "icc",
  "calibration_reported": true,
  "external_validation": "temporal",
  "model": "xgboost"
}

• n_features — 经过不依赖结局的精简后，进入结局驱动的筛选或拟合的候选特征（此处为提取的 1,200 个 → ICC ≥ 0.75 → |r| < 0.9 → 40 个）。此示例通过了门槛，但 pmsampsize（C = 0.75，患病率 110/300）要求 N = 1,868，且 40 个候选参数需有 685 个事件：该门槛不会确定研究规模，Test 12 才会。n_features、n_samples 和 n_events 必须是非负整数（n_events ≤ n_samples）；其他任何值都属于输入错误（退出码 2）。dimensionality_reduction 仅供参考，不会清除任何问题。
• feature_selection_stage — inside_cv、outside_cv 或 none（无结局驱动的筛选）。缺失或无法识别的值将被视为未证明是在折内进行（SELECTION_OUTSIDE_CV）。
• feature_stability — icc / test_retest；external_validation — external / temporal / geographic。其他任何值（例如 planned、internal、bootstrap、random_split）都会被标记。值不区分大小写；- 和空格会被视为 _。
• cv_scheme — nested；如果超参数和模型选择仅在训练拆分上调优，且测试拆分仅使用过一次，则为 held_out_test / single_split。若拆分也用于调优、模型选择或确定阈值，则属于 flat（在空数据的测试拆分上从 12 个候选模型中选择，报告的 AUROC 为 0.63，而非 0.51）。在放射组学的样本量下，单次随机拆分会浪费数据且结果不稳定；建议使用（重复）嵌套 CV（Steyerberg，J Clin Epidemiol 2018）。

阶段 4 — 对管线进行门控（确定性）

python3 scripts/check_radiomics_ml.py --manifest pipeline_manifest.json --strict

判定结果：NO_NESTED_CV、HIGH_DIM_LOW_EVENTS、SELECTION_OUTSIDE_CV（主要）；NO_FEATURE_STABILITY、NO_CALIBRATION、NO_EXTERNAL_VALIDATION，以及在 n_features、n_samples 或 n_events 缺失时的 HIGH_DIM_NOT_ASSESSED（次要）。在管线规范层面补充了 self-review 的 check_cv_leakage（用于审查已完成稿件的正文）。

集成

• /analyze-stats — 提供校准和临床效用（决策曲线、NNT）报告指南。
• /check-reporting — CLEAR（放射组学）、TRIPOD+AI、PROBAST-AI 条目覆盖情况。
• /self-review 的 clinical_prediction_model 探针会审查已完成的稿件；此技能则生成其所寻找的严谨管线。

防止幻觉

• 绝不捏造特征、性能指标或样本／事件计数。 清单中的每个值和报告的每项指标都必须来自研究人员实际执行的代码，绝不能凭空编造。此技能用于设计和审查管线；不会在真实患者数据上运行模型。
• 绝不将 flat-CV 性能报告成嵌套或留出测试性能。 在所报告的折上进行调优正是此技能要防止的乐观偏差（NO_NESTED_CV）。
• 未运行 check_radiomics_ml.py，绝不报告放射组学／ML 审查“通过”。 严谨性判定必须以确定性方式重现，绝不能仅凭正文断言。
• 集成，而非重新实现。 参考 scikit-learn / xgboost / pyradiomics；不要编写新的特征提取器或学习器，也不要声称它们产生了任何结果。

可复现挑战

scripts/check_radiomics_ml_challenge/ 提供一组弱／强合成管线，并附带一个不需要网络的 verify.sh，已接入该技能的验证命令。