# Demo_R_Project — Pima 二分类预测模型全流程技术 Demo

## 目的

本项目是教材 **Book 3（代码库）的配套技术 Demo**，用 `MASS::Pima.tr2` 演示完整的
二分类临床预测模型开发流程（数据画像 → Table 1 → 划分 → LASSO → Logistic/Nomogram
→ 内部验证 → 机器学习比较 → 模型锁定 → Holdout Test → Python 迁移契约）。
**它不是正式教学 Case**，仅用于验证教材所述统计契约可被代码严格执行。

## 数据来源

- `MASS::Pima.tr2`，直接从 R package 加载（`data(Pima.tr2, package = "MASS")`），
  不下载任何文件。
- 首次运行将加载后 + `row_id` 的快照写入 `data/raw/demo_raw.csv`；此后该文件**只读**，
  重复运行仅校验一致性，不覆盖。

## 如何运行

```bash
# 从本目录（Demo_R_Project）执行；R 4.5+，依赖包见 R/00_setup.R
Rscript run_all.R
```

- 每个 R 脚本也可单独从项目根运行，例如 `Rscript R/04_internal_validation.R`
  （依赖前序脚本已落盘的产物）。
- `python/01_contract_migration_demo.py` 在 R 全流程完成后可独立运行
  （`python python/01_contract_migration_demo.py`）。

## 目录结构

```
Demo_R_Project/
├─ README.md
├─ run_all.R                  # 唯一总入口
├─ config/config.R            # 单一配置源（SSOT）：seed/fold/结局编码/阈值规则/网格
├─ R/
│  ├─ 00_setup.R              # 项目根定位、目录、依赖检查、日志、共享工具函数
│  ├─ 01_prepare_data.R       # 加载、row_id、数据画像、缺失概览
│  ├─ 02_clean_table1_split.R # 清理日志、Table 1、分层划分与 fold 成员
│  ├─ 03_lasso_logistic_nomogram.R  # 主线：LASSO → Logistic → Nomogram（仅训练集）
│  ├─ 04_internal_validation.R      # 折内独立重学的完整内部验证（防泄漏核心）
│  ├─ 05_ml_compare_final_test.R    # 4 模型比较、锁定、Holdout Test、SHAP
│  └─ 06_export_python_bridge.R     # Python 迁移契约导出
├─ python/01_contract_migration_demo.py
├─ data/raw/  data/derived/
└─ results/
   ├─ tables/  figures/  models/  book_fragments/  logs/
   ├─ artifact_manifest.csv      # 全部产物清单（run_all 末尾生成并逐行核验）
   └─ run_summary.md
```

## 契约要点（统计纪律）

1. **测试集冻结**：Holdout Test 在模型锁定前不参与任何学习（插补、编码、筛选、
   调参、阈值），锁定后仅评价一次，评价后不返回重选。
2. **折内重学**：内部验证与 ML 比较的每个 outer fold 内，独立重新学习插补值、
   因子编码/参照、标准化参数、LASSO 变量集合与 Logistic/ML 模型；
   严禁全训练集先筛变量再做 CV。
3. **先锁后测**：`model_selection_record.csv`、`locked_model_config.csv`、
   `locked_model.rds` 三个锁定产物先于任何测试集访问落盘（日志可见顺序）。
4. **Python 读 manifest**：Python 端禁止 `train_test_split` / 重建 fold / 重设 seed
   抽样；成员严格来自 `split_manifest.csv` / `fold_manifest.csv`，预处理与模型
   类型来自 `python_feature_contract.csv` 与 `locked_model_config.csv`。
5. **单一配置源**：seed、fold 数、结局与正类编码、阈值规则、调参网格只存在于
   `config/config.R`；任何脚本不另存第二份。

## 派生变量声明

`bmi_cat`（由 `bmi` 按固定切点 `<25 / [25,30) / >=30` 生成）是**技术演示派生变量**，
规则固定，用于演示因子变量在 LASSO/编码/契约中的处理，**不解释为临床阈值**。