多组学癌症预后预测分析系统

基于 Flask 的 Web 应用，用于上传 TCGA 风格合并表、做特征与标签概览、Cox 预后风险评分与生存相关可视化。模型在本地训练后以 pkl 形式加载，不提供旧版演示数据或假模型兜底。

---

功能模块说明

1. 首页（index.html）

• 展示系统简介与流程入口（上传、示例下载、演示流程）。
• 展示训练阶段摘要：模型是否就绪、训练/测试 C-index、训练样本规模、入模特征数、风险阈值等（数据来自 artifacts/tcga_brca_training_metrics.json 与当前加载的模型包）。
• 说明数据格式要求（TCGA merged v2、ensg 基因列 + 生存标签）。

2. 数据上传（upload.html）

• 接收 CSV / TSV / TXT 上传，单次分析对应 uploads/<run_id>/ 目录。
• 服务端校验：
  • 拒绝旧版 GENE_001 等演示列名格式；
  • 要求 bundle_version=2 与 tcga_merged_v2 数据格式；
  • 要求包含模型所需的全部入模特征列及 time / event（或由临床字段推导）。
• 校验通过后生成特征分析页所需数据并写入 analysis.json。

3. 特征分析（analysis.html）

• 样本概览：样本数、字段数、数值特征数、模型入模特征数。
• 缺失率 / 方差 Top 10：基于本次上传表统计（ECharts 柱状图）。
• 样本预览：前若干行原始字段展示。
• 标签信息：是否检测到 time/event、事件率、随访时间中位数（仅描述本次上传队列）。
• 模型相关特征：展示已训练 Cox 模型的系数与 HR（非按本次上传重新拟合）。
• 开始预测：入模列齐全时可进入结果页；缺列时按钮禁用并提示。

4. 预测结果（results.html）

• 指标卡片（基于当前上传数据实时计算）：
  • C-index（当前上传）；
  • log-rank p（高低风险组，样本不足时可为 N/A）；
  • 高风险样本数；
  • 风险阈值（训练集上得到的中位数，用于 High/Low 划分）。
• 风险分数直方图：本次 risk_score 分布。
• 高低风险 KM 曲线：按 risk_group（与训练阈值一致）分组的 Kaplan-Meier 曲线。
• 代表样本 Cox 生存曲线：风险分最高样本，由 Cox 基线累积风险与个体线性预测器推导。
• 模型系数图：当前模型入模特征系数。
• 预测明细表：页面展示前 20 行；完整结果见下载 CSV。
• 分期观察性统计（可选）：上传表含 stage 时，展示各分期观察性死亡率等，非模型预测分期。

5. 示例与演示

能力	说明
下载示例数据	从真实训练合并表导出，列与当前模型对齐（artifacts/demo_brca_dataset.csv）
查看示例流程	自动抽样训练表、跑通分析 + 预测并跳转分析页
下载预测结果	uploads/<run_id>/predictions.csv
下载预处理数据	入模特征列按训练中位数填补缺失后的 CSV

6. 后端核心逻辑（survival_app/）

模块	职责
app_factory.py	Flask 路由、会话 run_id、分析/预测载荷组装、分期观察性统计、模型热加载
data.py	表读取、列名规范化、生存标签推导、特征列识别、缺失/方差报告
data_schema.py	上传格式兼容校验（v2 / 拒绝 legacy GENE）
modeling.py	Cox 拟合（statsmodels PHReg）、Breslow 基线、预测、CoxModelBundle 序列化
analysis.py	KM 曲线、C-index、log-rank 检验
demo_data.py	从训练表导出演示/示例 CSV
config.py	路径、版本号、BUNDLE_VERSION / DATA_FORMAT_ID
utils.py	目录创建、JSON 读写、ProgressReporter 终端进度条（供 CLI 脚本复用）
gdc.py / tcga_full.py	TCGA 数据下载与全量管线（CLI/脚本侧，非 Web 主流程必需）

7. 离线脚本（scripts/）

scripts/ 目录共 9 个文件，按用途分为：环境准备、模型训练、Web 启动、测试数据生成、TCGA 数据管线五类。以下列出全部脚本，无省略。

---

7.1 环境准备

脚本	平台	功能说明	主要产出
setup_venv.sh	macOS / Linux	在项目根目录创建 venv/；优先使用 python3.12，否则回退 python3；升级 pip 并安装 requirements.txt	根目录 venv/
setup_venv.bat	Windows	同上；优先 py -3.12 -m venv，失败则用 python -m venv	根目录 venv/

---

7.2 模型训练（Web 使用的标准训练入口）

脚本	功能说明	依赖数据	主要产出
train_model.py	从 TCGA 合并表训练 Cox PH 模型（fit_cox_bundle）；按 8:2 划分训练/测试集；计算训练/测试 C-index、测试集 log-rank；无假模型兜底	默认 data/tcga_brca/raw/tcga-brca_merged_dataset.csv；可用 --dataset 指定；若默认路径不存在则尝试 uploads/*/tcga-brca_merged_dataset.csv 并复制到默认路径	artifacts/cox_tcga_brca_bundle.pkl、artifacts/tcga_brca_training_metrics.json、artifacts/model_manifest.json、artifacts/demo_brca_dataset.csv（80 行示例）

train_model.py 常用参数（供查阅）：

参数	含义
--dataset	指定合并训练 CSV 路径
--test-size	测试集比例（默认 0.2）
--max-candidates	单因素筛选候选特征上限（默认 40）
--max-features	Cox 入模特征上限（默认 12，实际受事件数约束）
--random-state	划分随机种子（默认 42）

---

7.3 Web 应用启动（等价于根目录 mac_run.sh / window_run.bat）

脚本	平台	功能说明	前提
run_app.sh	macOS / Linux	使用 venv/bin/python 执行根目录 app.py，监听 127.0.0.1:5001；支持环境变量 TCGA_APP_DEBUG	已存在 venv/
run_app.cmd	Windows	使用 venv\Scripts\python.exe 执行 app.py	已存在 venv/

说明：根目录 mac_run.sh、window_run.bat 在缺少 venv 时会先调用 setup_venv.*，再启动应用；run_app.* 仅负责启动，不创建虚拟环境。

---

7.4 测试 CSV 与验收报告生成

脚本	功能说明	主要产出（默认写在项目根目录）
build_root_test_csvs.py	生成 2 类测试表并做自动化校验：① 从训练表抽 10 例（5 删失 + 5 死亡）→ 兼容表；② 合成 5 例 GENE_001 旧格式 → 应被拒绝；对兼容表跑 Cox 预测并写入验收 JSON	test_data_compatible.csv、test_data_legacy_incompatible.csv、test_predictions_compatible.csv、test_verification_report.json
build_variant_test_csvs.py	从训练表按规则生成 7 份格式兼容、标签统计不同的测试 CSV；每份生成对应 *_predictions.csv；汇总预期「事件率 / 中位时间」	test_data_compatible.csv、test_data_variant_low_event.csv、test_data_variant_high_event.csv、test_data_variant_short_followup.csv、test_data_variant_long_followup.csv、test_data_variant_small_n.csv、test_data_variant_many_n.csv、各 *_predictions.csv、test_predictions_compatible.csv（基准预测别名）、test_datasets_manifest.json

build_variant_test_csvs.py 生成的 7 个变体（分析页标签对照用）：

文件名	设计意图（事件率 / 中位时间随变体变化）
test_data_compatible.csv	基准：约 50% 事件率，中位时间约 695
test_data_variant_low_event.csv	低事件率（约 14%）
test_data_variant_high_event.csv	高事件率（约 70%）
test_data_variant_short_followup.csv	短随访（中位时间偏低）
test_data_variant_long_followup.csv	长随访（中位时间偏高）
test_data_variant_small_n.csv	小样本（6 例）
test_data_variant_many_n.csv	较大样本（20 例）

说明：test_data_legacy_incompatible.csv 仅由 build_root_test_csvs.py 生成；变体脚本不负责 legacy 负例。

---

7.5 TCGA 数据下载与全量管线（扩展能力，非 Web 必需）

脚本	功能说明	主要产出 / 子命令
download_tcga_brca.py	通过 GDC API 下载 清单（manifest） 与 临床表；大文件表达量需配合 GDC Data Transfer Tool	默认 downloads/ 下 manifest + tcga-brca_clinical.csv
tcga_brca_full_pipeline.py	封装 survival_app.tcga_full 的完整命令行：下载 → 合并 → 训练 → 预测	见下表子命令

tcga_brca_full_pipeline.py 子命令一览：

子命令	作用	典型输出路径
download	从 GDC 下载原始表达与临床数据到 data/tcga_brca/raw/	原始目录、metadata CSV、clinical CSV
build	由已下载原始数据构建 merged 合并表	data/tcga_brca/raw/tcga-brca_merged_dataset.csv（及缓存矩阵）
train	在指定 merged CSV 上训练 Cox，写出 bundle 与指标	默认 artifacts/cox_tcga_brca_bundle.pkl、artifacts/tcga_brca_training_metrics.json、artifacts/tcga_brca_train_test_predictions.csv
predict	用已训练 bundle 对任意输入 CSV 批预测	默认 artifacts/tcga_brca_predictions.csv（--input-csv 必填）
all	串联 download + build + train 一步完成	同上各路径

说明：日常仅维护网页模型时，通常只需 train_model.py + 已有 data/tcga_brca/raw/tcga-brca_merged_dataset.csv；tcga_brca_full_pipeline.py 用于从 GDC 重新拉数、扩样本、重建合并表等重型流程。

---

7.6 脚本与核心模块对应关系

train_model.py              →  survival_app.modeling.fit_cox_bundle
build_root_test_csvs.py     →  data_schema.validate_upload_compatible + predict_with_bundle
build_variant_test_csvs.py  →  同上（批量变体）
download_tcga_brca.py       →  survival_app.gdc
tcga_brca_full_pipeline.py  →  survival_app.tcga_full
run_app.sh / run_app.cmd    →  根目录 app.py → survival_app.app_factory.create_app
setup_venv.sh / .bat        →  requirements.txt（无 Python 业务逻辑）

8. 前端图表（static/js/charts.js）

• 仅渲染后端传入的 JSON，不生成随机或占位曲线。
• 支持：横向柱状图（缺失/方差/系数）、风险直方图、KM/单样本生存折线、分期死亡率柱状图。

---

数据与模型约定

• 入模特征：以 artifacts/model_manifest.json 与 CoxModelBundle.feature_names 为准（当前为 6 列：ensg 基因 + age_at_diagnosis 等，随训练结果变化）。
• 风险分组：risk_score >= risk_threshold → High，否则 Low；阈值为训练集 risk_score 中位数。为避免浮点精度导致边界样本分组不一致（如 risk_score 与 threshold 仅差 ~1e-17），比较时引入 _EPS = 1e-12 容差：risk_score >= threshold - _EPS 即归为 High。
• 预测插补：上传表入模列存在缺失时，用训练阶段记录的特征中位数填补后再标准化评分（非替换为假基因表）。
• 版本：bundle_version=2，data_format=tcga_merged_v2；旧 pkl 与 GENE_xxx CSV 不兼容。
• 数据编码：上传 CSV 使用 utf-8-sig 编码写出（含 BOM），读取时自动处理 BOM 头，避免 \ufeff 残留在 sample_id 等首列列名中。
• Pickle 安全：CoxModelBundle.from_pickle 使用自定义 _SafeUnpickler，限制可反序列化的类（仅允许 builtins、numpy、pandas 等白名单模块），防止恶意 pkl 注入。

---

目录结构说明

duozuxue/
├── app.py                      # Flask 应用入口
├── mac_run.sh                  # macOS 启动脚本
├── window_run.bat              # Windows 启动脚本
├── requirements.txt            # Python 依赖
├── README.md                   # 安装与使用说明（含各平台步骤）
├── 项目说明.md                  # 本文件：功能与结构说明
│
├── survival_app/               # 后端业务包
│   ├── app_factory.py          # Web 应用工厂与路由
│   ├── config.py               # 全局配置与路径
│   ├── data.py                 # 上传表解析与特征检测
│   ├── data_schema.py          # 格式兼容校验
│   ├── modeling.py             # Cox 训练/预测与模型包
│   ├── analysis.py             # 生存分析统计与 KM
│   ├── demo_data.py            # 示例数据导出
│   ├── utils.py                # 通用工具（含 ProgressReporter 进度条）
│   ├── gdc.py                  # GDC API 下载辅助
│   └── tcga_full.py            # 全量 TCGA 构建与训练管线
│
├── templates/                  # Jinja2 页面模板
│   ├── base.html               # 导航与布局
│   ├── index.html              # 首页
│   ├── upload.html             # 上传页
│   ├── analysis.html           # 特征分析页
│   └── results.html            # 预测结果页
│
├── static/
│   ├── css/style.css           # 样式
│   └── js/charts.js            # ECharts 图表封装
│
├── scripts/                    # 离线脚本（共 9 个，详见上文「7. 离线脚本」）
│   ├── setup_venv.sh           # macOS/Linux：创建 venv、安装依赖
│   ├── setup_venv.bat          # Windows：创建 venv、安装依赖
│   ├── train_model.py          # 训练 Cox 模型，写出 artifacts/*.pkl
│   ├── run_app.sh              # macOS/Linux：启动 Flask（需已有 venv）
│   ├── run_app.cmd             # Windows：启动 Flask（需已有 venv）
│   ├── build_root_test_csvs.py # 基准 + legacy 测试 CSV 与验收 JSON
│   ├── build_variant_test_csvs.py  # 7 份变体测试 CSV 与 manifest
│   ├── download_tcga_brca.py   # GDC manifest + 临床表下载
│   └── tcga_brca_full_pipeline.py  # download/build/train/predict/all 全管线
│
├── data/                       # 训练用原始/合并数据（本地）
│   └── tcga_brca/raw/
│       └── tcga-brca_merged_dataset.csv
│
├── artifacts/                  # 模型与训练产出（本地生成）
│   ├── cox_tcga_brca_bundle.pkl
│   ├── tcga_brca_training_metrics.json
│   ├── model_manifest.json
│   └── demo_brca_dataset.csv
│
├── uploads/                    # 每次上传的运行目录（运行时生成）
│   └── <run_id>/
│       ├── *.csv               # 用户上传文件
│       ├── analysis.json       # 分析页缓存
│       ├── predictions.json    # 预测结果 JSON
│       └── predictions.csv     # 预测结果表
│
├── ------测试样本csv文件/       # 手工/脚本生成的测试 CSV 与对照清单
│   ├── test_data_compatible.csv
│   ├── test_data_variant_*.csv
│   ├── *_predictions.csv
│   ├── test_datasets_manifest.json
│   └── test_verification_report.json
│
└── venv/                       # Python 虚拟环境（本地，一般不提交仓库）

---

页面与数据流关系

首页 ──► 上传 ──► 特征分析 ──► 开始预测 ──► 结果页
              │         │              │
              │         │              └── predict_with_bundle + KM / 指标
              │         └── _summarize_analysis → analysis.json
              └── validate_upload_compatible

示例下载 / 演示流程 ──► 同样进入 分析 → 结果 链路

每次上传分配独立 run_id；结果页访问时会按当前磁盘模型重新计算预测与图表数据，并回写 predictions.csv / predictions.json。

预测结果缓存策略：/results 路由优先读取已缓存的 predictions.json，仅当缓存不存在或内容为空时才触发完整预测计算，避免每次刷新页面重复执行 predict_with_bundle。

---

测试与验收相关文件

文件	用途
test_data_compatible.csv	格式正确、可与脚本预测对照的基准上传样例
test_data_variant_*.csv	不同事件率/随访/样本量，用于验证分析页「标签信息」变化
test_data_legacy_incompatible.csv	旧格式负例，上传应被拒绝
*_predictions.csv	对应输入的脚本标准预测答案
test_datasets_manifest.json	各变体预期标签统计说明
test_verification_report.json	兼容/拒绝逻辑的自动化验收记录

---

技术栈概要

• Web：Flask、Jinja2、Bootstrap 5、ECharts 5
• 计算：pandas、numpy、scipy、statsmodels（Cox PHReg）、scikit-learn（训练划分等脚本侧）

---

说明边界

• 本系统为研究/演示向预后风险分层工具，页面指标依赖上传样本量与标签质量；小样本时 C-index、log-rank 可能为 N/A。
• 首页训练 C-index 与结果页「当前上传 C-index」含义不同，不可直接混为一谈。
• 分期统计为观察性描述（各分期实际死亡率），非模型预测的分期；分期标准化使用正则匹配（支持罗马数字亚型如 IIIA/IIIB/IIIC、阿拉伯数字自动转罗马、Stage 前缀自动去除），无法识别的分期归为 Unknown。
• 详细安装、启动、训练命令见根目录 README.md。

---

更新日志

v2.1（2026-05）

• 修复：predict 路由重复调用 predict_with_bundle，_build_prediction_payload 现同时返回 predicted DataFrame，消除冗余计算。
• 修复：normalize_stage 从 30+ 行 startswith 链式匹配改为正则表达式，更易维护且自动保证匹配优先级（长串先于短串）。
• 修复：results.html 中 predicted_stage 为 None 时显示 "None期"，现正确显示 "N/A"。
• 重构：_ProgressReporter 从 gdc.py / tcga_full.py 提取到 utils.py（公开类名 ProgressReporter），两个模块通过别名 _ProgressReporter = ProgressReporter 保持内部兼容。