fMRI（3-1）报告（个体化报告）生成器说明

fMRI 分析报告生成器说明

文件：generate_report.m

版本：v1.0

依赖：run_full_pipeline.m + run_post_analysis.m 的完整输出

---

目录

1. 功能概述
2. 依赖环境
3. 目录结构要求
4. 输入参数
5. 输出文件
6. 调用方式
7. 报告页面详解
8. 辅助函数说明
9. 常见问题与排错

---

1. 功能概述

generate_report.m 是 fMRI 静息态分析流程的单被试级可视化报告生成器 ，负责将 run_full_pipeline.m 和 run_post_analysis.m 的计算结果汇总为一份多页 PDF 报告。

报告面向单被试数据审查，每个被试独立占用若干页，依次呈现：

• 质量控制（FD + 头动参数）
• 体素级指标脑图（ALFF、fALFF、ReHo、VMHC、DC）
• 种子点功能连接图（6 个 ROI）
• Atlas FC 矩阵热图（AAL3，165 区）
• 动态 FC 状态序列及聚类中心
• 图论指标（BCT，雷达图 + 节点分布）

最后附图论指标汇总表和组水平 GLM T 图（全部被试）。

与 generate_stats_report.m 的区别
generate_report.m 侧重单被试逐页展示 ，不做组间统计检验。
generate_stats_report.m 侧重两组对比，含 t-test / FDR / Cohen's d。

---

2. 依赖环境

依赖项	版本要求	用途
MATLAB	R2020b 及以上（推荐 R2022b+）	主运行环境
SPM	SPM25（spm_25_01_02）	NIfTI 文件读取（spm_vol、spm_read_vols）
Statistics and Machine Learning Toolbox	可选	无强制依赖
exportgraphics 函数	MATLAB R2020a+ 内置	PDF 页面输出（低版本自动回退到 print）

SPM 路径（硬编码在脚本开头，需按实际路径修改）：

spm_path = 'D:\0share\0matelab_scripts\spm_25_01_02';

---

3. 目录结构要求

脚本依赖以下目录/文件结构（以 root_dir = 'F:\test' 为例）：

F:\test\
├── data.csv                          ← 被试分组信息（可选，有则生成分组表页）
├── test-01\
│   ├── rp_*.txt                      ← 头动参数文件（SPM 格式，6 列）
│   └── results\
│       ├── framewise_displacement.mat  ← FD 时间序列（变量名 fd）
│       ├── ALFF.nii                   ← ALFF 图
│       ├── fALFF.nii                  ← fALFF 图
│       ├── sReHo.nii                  ← 平滑后 ReHo 图
│       ├── sVMHC.nii                  ← 平滑后 VMHC 图
│       ├── DC_WeightedSum.nii         ← 度中心性（加权和）图
│       ├── SeedFC\
│       │   ├── FC_PCC.nii
│       │   ├── FC_mPFC.nii
│       │   ├── FC_L_DLPFC.nii
│       │   ├── FC_R_DLPFC.nii
│       │   ├── FC_L_Amygdala.nii
│       │   └── FC_R_Amygdala.nii
│       ├── FC_matrix.mat              ← 变量：FC_z（N×N）, roi_ids（N×1）
│       ├── dFC\
│       │   └── dFC_states.mat         ← 变量：dfc_labels, dfc_centers, win_size, dfc_step
│       └── GraphTheory.mat            ← 变量：CC, lambda, Eglob, Q, sigma, gamma,
│                                          lam_n, deg, str, BC, W_norm
├── test-02\
│   └── ...
└── group_analysis\
    ├── GraphTheory_summary.csv         ← 图论汇总表（含列：subj_id, CC_mean, lambda, ...）
    ├── GroupComp_ALFF\
    │   ├── spmT_0001.nii               ← A>B 对比 T 图
    │   └── spmT_0002.nii               ← B>A 对比 T 图
    ├── GroupComp_fALFF\
    ├── GroupComp_sReHo\
    ├── GroupComp_sVMHC\
    └── GroupComp_DC_WeightedSum\

注意 ：以上文件均为可选------某文件不存在时，脚本跳过对应页面，不报错中断。

---

4. 输入参数

参数	类型	默认值	说明
root_dir	char / string	'F:\test'	数据根目录，包含所有 test-* 被试子目录

被试目录自动扫描：脚本以 dir(fullfile(root_dir, 'test-*')) 扫描所有 test-* 子目录，按文件系统顺序处理。

---

5. 输出文件

文件名	路径	说明
fMRI_Analysis_Report.pdf	<root_dir>/fMRI_Analysis_Report.pdf	多页矢量 PDF（11×8.5 英寸横向）

• 若文件已存在，先删除再重建 （exportgraphics Append 模式需要从空文件开始）。
• 页数随被试数量和可用数据动态变化（封面 + 约 7--9 页/被试 + 汇总页 + GLM 页）。

---

6. 调用方式

% 方式一：使用默认路径
generate_report('F:\test')

% 方式二：指定其他路径
generate_report('D:\fMRI_data\study01')

命令窗口输出示例：

生成报告: 12 个被试
  输出: F:\test\fMRI_Analysis_Report.pdf

━━━ [被试 1/12] test-01 ━━━
[页面  3] test-01 --- 质量控制 (FD + 头动)...
[页面  4] test-01 --- ALFF / fALFF...
[页面  5] test-01 --- ReHo / VMHC / DC...
...
  ✅ 被试 test-01 完成 (耗时 4.2 秒)
...
=======================================================
✅ 报告生成完成!
   输出文件: F:\test\fMRI_Analysis_Report.pdf
   文件大小: 3842.1 KB / 共 98 页
   总耗时  : 51.3 秒

---

7. 报告页面详解

第 1 页：封面

内容：报告标题、生成时间、数据根目录、被试数量、预处理参数摘要、分析模块列表。

元素	详情
标题	fMRI 静息态分析报告
预处理参数	TR=3s, 3×3×3mm, 4mm 平滑, 带通 0.01--0.08 Hz, 36参数噪声模型
分析模块	ALFF/fALFF、ReHo、VMHC、DC、种子点FC、Atlas FC、dFC、图论

---

第 2 页：被试分组信息表（可选）

触发条件 ：<root_dir>/data.csv 存在。

内容 ：读取 data.csv，显示原始表格（所有列）。

CSV 格式示例：

SubjectID,Group,Age
sub-01,1,25
sub-02,2,28

---

第 3 页起：被试级分析（每被试约 7--9 页）

每个 test-* 被试按顺序生成以下页面（文件不存在则跳过）：

① 质量控制（FD + 头动）

区域	内容
上半图	FD 时间序列折线图，红色虚线标注 0.25 mm 阈值，标题含均值/最大值/超阈值比例
下半图	6 参数头动时间序列（Tx/Ty/Tz mm，Rx/Ry/Rz °）

数据来源 ：results/framewise_displacement.mat（变量 fd）、rp_*.txt（头动参数）。

---

② ALFF / fALFF 切片蒙太奇

区域	内容
上半	ALFF 轴位切片蒙太奇（8 层，colormap: hot，自动 2%--98% 对比度）
下半	fALFF 轴位切片蒙太奇（colormap: parula）

数据来源 ：results/ALFF.nii、results/fALFF.nii。

---

③ ReHo / VMHC / DC 切片蒙太奇

每个存在的指标占用一行（最多 3 行）：

指标	Colormap
sReHo（平滑 ReHo）	autumn
sVMHC（平滑 VMHC）	cool
DC_WeightedSum（度中心性）	jet

数据来源 ：results/sReHo.nii、results/sVMHC.nii、results/DC_WeightedSum.nii。

---

④ 种子点功能连接（6 ROI）

六个种子点以 2×3 网格排列，每格为一个种子点的全脑 FC 图（Fisher-z）。

种子点	文件名
PCC（后扣带回）	FC_PCC.nii
mPFC（内侧前额叶）	FC_mPFC.nii
L/R DLPFC（双侧背外侧前额叶）	FC_L_DLPFC.nii、FC_R_DLPFC.nii
L/R 杏仁核	FC_L_Amygdala.nii、FC_R_Amygdala.nii

Colormap：RdBu_r（红蓝对称，中心为白色，范围自动 2%--98%）。

数据来源 ：results/SeedFC/FC_*.nii。

---

⑤ Atlas FC 矩阵热图

内容：AAL3 165×165（或实际 ROI 数）Fisher-z 功能连接矩阵热图。

• Colormap：RdBu（红=正相关，蓝=负相关），范围 [-1, 1]
• 标题显示矩阵均值和最大值

数据来源 ：results/FC_matrix.mat（变量 FC_z, roi_ids）。

---

⑥ 动态 FC 状态图【可选，默认关闭】

触发条件 ：脚本顶部 do_dfc = true（默认 false，即默认不生成此页）。

内容：

• 上半：dFC 状态标签时间序列（伪彩图，每行=1个窗口，色彩=状态编号 1--k）
• 下半：k 个聚类中心的 FC 向量条形图（每图一个状态，横轴=FC 边，纵轴=Fisher-z）

数据来源 ：results/dFC/dFC_states.mat（变量 dfc_labels, dfc_centers, win_size, dfc_step）。

参数 （来自 run_post_analysis.m）：

• 滑动窗口大小：60 s（20 帧，TR=3s）
• 滑动步长：1 帧
• 聚类数 k = 5

---

⑦ 图论分析（BCT）

内容：

• 左上文本框：7 个全局指标数值（σ、γ、λ、L、Eglob、Q、CC 均值）
• 右上雷达图：5 个指标归一化后的极坐标蜘蛛图（σ/3、γ、λ/2、Eglob、Q）
• 下方 3 图：节点度分布直方图 / 节点强度分布 / 介数中心性分布

数据来源 ：results/GraphTheory.mat（变量 CC, lambda, Eglob, Q, sigma, gamma, lam_n, deg, str, BC, W_norm）。

指标	含义
σ（sigma）	小世界系数，σ > 1 表示小世界网络
γ（gamma）	归一化聚类系数（= CC_real / CC_rand）
λ（lam_n）	归一化路径长度（= L_real / L_rand）
L（lambda）	特征路径长度
Eglob	全局效率
Q	模块度
CC	平均聚类系数

---

图论汇总表页（仅当 GraphTheory_summary.csv 存在）

内容 ：读取 group_analysis/GraphTheory_summary.csv，显示 subj_id, CC_mean, lambda, Eglob, Q, sigma 等关键列的汇总表格。

---

组水平 GLM T 图页（每指标一页，共最多 5 页）

针对 5 个指标（sReHo、ALFF、fALFF、sVMHC、DC_WeightedSum），各生成一页：

区域	内容
上半	A > B 对比 T 图（spmT_0001.nii），colormap: jet，范围 [-5, +5]
下半	B > A 对比 T 图（spmT_0002.nii）
底部注释	N 观测数、设计类型（两样本 t-test）、阈值说明

数据来源 ：group_analysis/GroupComp_<metric>/spmT_000*.nii、SPM.mat。

---

8. 辅助函数说明

new_fig()

fig = new_fig()

创建一个 11×8.5 英寸（横向 A4/Letter）、白色背景、不可见（Visible='off'）的图形窗口。用于离屏渲染，避免渲染过程中弹出窗口。

---

save_page(fig, pdf_out)

save_page(fig, pdf_out)

将 fig 追加保存到 PDF 文件 pdf_out，然后关闭图形。

• MATLAB R2020a+：使用 exportgraphics(fig, pdf_out, 'ContentType','vector', 'Append',true) 生成矢量 PDF。
• 旧版 MATLAB：回退到 print(fig, '-dpdf', '-fillpage', pdf_out)（不支持追加，每次生成单页覆盖）。

---

section_title(fig, txt)

section_title(fig, '标题文字')

在页面顶部（归一化坐标 [0, 0.93, 1.0, 0.07]）绘制蓝色粗体标题文本框，背景浅蓝色，无边框线。

---

draw_table(fig, tdata, pos, fontsize)

draw_table(fig, tdata, pos, fontsize)

在 fig 的归一化坐标 pos = [x, y, width, height] 处绘制一个 cell 数组 tdata 的表格。

参数	说明
tdata	{n_rows × n_cols} cell 数组，第 1 行为表头
pos	[左下角x, 左下角y, 宽度, 高度]（归一化 0--1 坐标）
fontsize	字体大小，默认 11

样式规则：

• 表头行（第 1 行）：浅蓝背景 [0.85, 0.90, 1.0]
• 数据行：白色背景
• 单元格间用灰色边框 [0.7, 0.7, 0.7] 绘制矩形

注意 ：底层使用 annotation 实现，不依赖 MATLAB uitable，兼容性更好，但列宽固定均分。

---

slice_montage(nii_file, label, cmap_name, pos, clim_in)

slice_montage('path/to/file.nii', 'ALFF', 'hot', [0.05 0.45 0.9 0.45])
slice_montage('path/to/file.nii', 'ALFF', 'hot', [0.05 0.45 0.9 0.45], [-6 6])

读取 NIfTI 文件并在当前图形的 pos 位置显示轴位切片蒙太奇（8 个代表性切层横向拼接）。

参数	说明
nii_file	NIfTI 文件路径（.nii）
label	图标题文字
cmap_name	Colormap 名称（'hot'、'cool'、'jet'、'parula'、'autumn'、'rdbu_r'）
pos	[x, y, w, h] 归一化坐标
clim_in	颜色轴范围 [min, max]（可选，默认取 2%--98% 百分位数）

切层选择策略：找到 z 轴上有非零值的范围，在 15%--85% 之间均匀取 8 层，避开空白顶底。

---

get_colormap(name)

内部函数，根据字符串名称返回 256 行 colormap 矩阵，支持：hot, cool, jet, parula, autumn, rdbu_r（回退默认 jet）。

---

rdbu_colormap()

生成 256 色红-白-蓝对称 colormap（专为 FC 矩阵设计）：

• 蓝端 [0.02, 0.19, 0.70] → 白色 [1, 1, 1]（前 128 色）
• 白色 → 红端 [0.70, 0.09, 0.09]（后 128 色）

---

9. 常见问题与排错

Q1：运行后 PDF 文件只有 1 页或页面空白

可能原因 ：MATLAB 版本低于 R2020a，exportgraphics 不支持 Append 模式。

解决方案 ：升级至 MATLAB R2020a 以上，或修改 save_page 函数，在 else 分支手动实现多页 PDF 合并（如使用 GhostScript）。

---

Q2：提示"spm_vol 未定义"或"spm not found"

可能原因：SPM 路径未正确添加。

解决方案 ：修改脚本开头的 spm_path 变量：

spm_path = '你的SPM安装路径';  % 例如 'C:\spm25'

---

Q3：某被试的某页面缺失

原因：对应数据文件不存在（如该被试没有运行图论分析）。

行为：脚本会跳过该页，不中断报告生成，在命令窗口无额外提示（正常行为）。

---

Q4：切片蒙太奇图像方向不对（如左右翻转）

原因 ：NIfTI 文件的仿射矩阵与预期不符，rot90 旋转可能不适用。

解决方案 ：检查 NIfTI 头信息（如 spm_vol 的 .mat 字段），必要时在 slice_montage 中调整 rot90 次数或翻转轴。

---

Q5：图论雷达图（极坐标）归一化值异常（超出 [0,1]）

原因：某指标（如 σ）值远大于 3（使用 σ/3 归一化），导致截断至 1。

说明 ：这是正常行为，max(0, min(1, rho_norm)) 会将值钳制在 [0,1]，不影响报告正确性，但雷达图比例可能不直观。

---

附录：颜色方案参考

颜色变量	RGB	用途
蓝色 [0.2, 0.5, 0.8]	蓝	节点度直方图
橙色 [0.8, 0.4, 0.2]	橙	节点强度直方图
绿色 [0.3, 0.7, 0.4]	绿	介数中心性直方图
蓝色深 [0.1, 0.2, 0.5]	深蓝	标题文字、section_title
背景 [0.92, 0.95, 1.0]	浅蓝	section_title 背景
背景 [0.85, 0.90, 1.0]	浅蓝	表头背景

---

文档对应脚本版本：generate_report.m v1.0
最后更新：2026-04