SFCN real-gen / gen-real 年龄段分类实验

这个目录用于训练两个 PyTorch 版 SFCN 年龄段分类模型，比较真实 MRI 与 generated MRI 的跨域泛化能力。

如果你第一次接触这个项目，可以先把它理解成：

• 用两类 MRI 数据做年龄段分类
• 一类是 real MRI，也就是真实采集的数据
• 一类是 generated MRI，也就是生成出来的数据
• 我们想比较：用一种数据训练后，换到另一种数据上测试，模型表现会怎样

这个项目的重点不是做一个通用训练框架，而是把这两个跨域实验稳定跑通，并把结果保存下来，方便比较。

这个项目主要回答两个问题：

1. 用真实 MRI 训练出来的年龄段分类模型，放到 generated MRI 上测试时效果如何。
2. 用 generated MRI 训练出来的年龄段分类模型，放到真实 MRI 上测试时效果如何。

因此，这个仓库更偏向“实验执行与结果比较”，而不是一个通用医学影像训练平台。

当前方案不是旧的 preliminary 方案。旧方案是 real train -> generated validation/test，现在废弃。当前只保留两个正式实验：

• real-gen: real 做 train/validation，generated 做 test
• gen-real: generated 做 train/validation，real 做 test

可以把这两个名字这样记：

• real-gen = 用真实数据学，再去看生成数据上的泛化
• gen-real = 用生成数据学，再去看真实数据上的泛化

更具体一点：

• real-gen 关注“真实数据训练的模型，跨到生成数据时还能不能工作”
• gen-real 关注“生成数据训练的模型，回到真实数据时还能不能工作”

如果你只想快速理解目录作用，可以先看这几类内容：

• build_manifests.py：先整理数据清单，决定哪些样本进入 train / validation / test
• train.py：训练模型
• infer.py：用训练好的模型做推理
• evaluate_plot.py：整理结果并画图
• run_all.sh：把上面几步按顺序串起来
• outputs/：所有实验输出都会放在这里
• docs/：补充需求文档和背景说明

第一次看代码时，建议不要先钻进模型实现，先把“数据怎么整理、实验怎么跑、结果怎么输出”这条主线看明白。

这个仓库可以粗略分成四层：

• build_manifests.py：整理数据、决定实验输入
• train.py / infer.py / evaluate_plot.py：执行训练、推理和评估
• data/ / models/ / common.py：底层数据读取、模型定义和公共工具
• docs/ / README.md / Quickstart.md：项目说明和需求背景

如果你准备公开展示这个仓库，最值得先让别人看到的是：

1. README.md
2. Quickstart.md
3. run_all.sh
4. build_manifests.py

如果你对这个项目还不熟悉，建议按下面顺序理解：

1. 先准备 real MRI 和 generated MRI 数据。
2. 运行 build_manifests.py，生成本次实验要用的数据名单。
3. 运行 train.py，训练模型。
4. 运行 infer.py，让模型对 validation / test 数据出预测结果。
5. 运行 evaluate_plot.py，把结果汇总成表格和图。

run_all.sh 做的就是把这几步连起来一次跑完。

如果你想先看文档，再看代码，推荐顺序是：

1. README.md
2. Quickstart.md
3. run_all.sh
4. build_manifests.py
5. train.py
6. infer.py
7. evaluate_plot.py

只运行：

./run_all.sh

这适合已经准备好数据路径和运行环境的情况。如果你是第一次接手项目，建议先通读下面的“运行前准备”“输出目录”和 Quickstart.md。

该脚本会依次完成：

1. 构建平衡后的 manifests
2. 训练 real-gen
3. 推理 real-gen 的 validation 和 test
4. 评估并画 real-gen 图
5. 训练 gen-real
6. 推理 gen-real 的 validation 和 test
7. 评估并画 gen-real 图

在运行前，你至少需要知道下面几件事：

1. 这是一个 PyTorch 项目，需要本机有可用的 Python 环境。
2. 默认训练设备写的是 mps，更适合 Apple Silicon Mac。
3. 项目假定你已经有真实 MRI 和生成 MRI 数据，并且数据路径可访问。
4. 项目里会读取固定位置的数据目录，所以路径不对时脚本会失败。

第一次运行前，最重要的是先确认三件事：

• 数据在不在
• 数据路径对不对
• Python 环境能不能正常运行 PyTorch

当前 README 主要描述实验流程，本仓库里没有在这里额外展开完整依赖安装说明。实际运行前，建议至少确认：

• Python 已安装
• PyTorch 已安装
• 代码运行所需的基础科学计算库已安装
• 当前机器可以访问 README 中写到的数据目录

项目当前提供了一个基础的 requirements.txt，最简单的安装方式是：

pip install -r requirements.txt

如果后续你准备把项目交给别人直接接手，仍然建议进一步补完整环境说明，或者增加 environment.yml。

默认训练参数沿用之前代码，不因为当前重构而改变：

• device = mps
• num_workers = 4
• batch_size = 4
• max_epochs = 50
• lr = 2e-4
• weight_decay = 1e-4
• patience = 3
• seed = 42

这些参数的意思可以简单理解为：

• batch_size：一次喂给模型多少个样本
• max_epochs：最多训练多少轮
• lr：学习率，控制每一步更新幅度
• patience：如果验证集效果长期不提升，就提前停止
• seed：固定随机种子，尽量保证每次结果可复现

这些不是给新手“必须调”的参数。除非你已经明确知道为什么要改，否则先保持默认值更稳妥。

构建 manifest 时必须满足：

• real 和 generated selected 数量一致
• 按 age_bin × sex 平衡抽样
• 每个组合内使用 seed = 42 随机抽样
• 不复制样本
• 不使用 mock 样本
• 不静默忽略不平衡问题，summary 必须记录每个组合数量

这里的重点是：这个实验不是简单把所有数据直接喂进模型，而是先尽量让 real 和 generated 两边在 age_bin × sex 上保持可比较。

train/validation 切分必须满足：

• 只切当前训练域
• 按 age_bin × sex 分层
• 每个组合按 4:1 切 train/validation
• validation 和 train 都要尽量保留每个组合

outputs/
├── real-gen/
│   ├── manifests/
│   ├── checkpoints/
│   ├── logs/
│   ├── predictions/
│   └── figures/
└── gen-real/
    ├── manifests/
    ├── checkpoints/
    ├── logs/
    ├── predictions/
    └── figures/

这些目录可以这样理解：

• manifests/：本次实验实际用了哪些样本
• checkpoints/：训练保存的模型权重
• logs/：训练过程中的日志
• predictions/：模型推理后的原始结果
• figures/：最终画出来的图表

如果你只是想看“实验有没有跑成功”，通常先看：

• logs/ 有没有正常输出
• checkpoints/ 有没有生成模型
• predictions/ 有没有推理结果
• figures/ 有没有最终图表

如果你想快速定位问题，也可以这样判断：

• 没有 manifests/：通常说明数据整理阶段没跑通
• 没有 checkpoints/：通常说明训练阶段没跑通
• 没有 predictions/：通常说明推理阶段没跑通
• 没有 figures/：通常说明评估或画图阶段没跑通

• build_manifests.py: 构建 real/generated 平衡数据与两个实验的 train/val/test manifests
• train.py: 按 --experiment real-gen|gen-real 训练模型
• infer.py: 对指定实验和 split 做推理
• evaluate_plot.py: 聚合预测结果并画图
• run_all.sh: 总入口

如果你只是想尽快建立整体认知，先看 run_all.sh 最直接，因为它把整个实验顺序串起来了。

Real MRI:

• 根目录：/Volumes/LuZhang16T/IU_Datasets
• 标签文件：/Volumes/LuZhang16T/IU_Datasets/mapping_table.csv

Generated MRI:

• 根目录：/Volumes/LuZhang16T/generated_mri

generated 文件名解析支持：

• age1.00_sexM_s131.nii.gz
• 0004_age0.00_sexF_s4.nii.gz

generated 的 NIfTI header 不可信，训练和评估只按数组张量处理。

这句话很重要，意思是：

• 不要依赖 generated MRI 文件头里的空间信息
• 这个项目更关注输入张量本身，而不是医学影像 header 元数据
• 如果你后面扩展流程，最好不要把 generated header 当作可靠标签来源

如果你的目标是“先跑通，再细看代码”，建议直接看 Quickstart.md。

如果你的目标是“先看代码结构，再决定是否接手”，建议先看 run_all.sh 和 build_manifests.py。

详细流程见：

• PRD_balanced_real_generated_cross_domain.md

如果你只是想先跑起来，不一定要先读完 PRD；如果你想改实验规则、改抽样逻辑、改评估方式，再去看这个文档会更合适。