fMRI 统计分析报告生成器说明文件generate_stats_report.m版本v1.0依赖run_full_pipeline.mrun_post_analysis.m的完整输出 被试分组 CSV目录功能概述依赖环境目录结构要求输入参数输出文件全局配置参数调用方式数据预加载流程报告页面详解统计方法说明辅助函数说明网络-ROI映射参考常见问题与排错1. 功能概述generate_stats_report.m是 fMRI 静息态分析流程的分组统计分析报告生成器面向两组被试的组间对比分析生成包含描述性统计和当样本量足够时的推断统计结果的多页 PDF 报告。核心特点预加载全部被试数据后再统一生成图表避免多次磁盘 I/O对所有关键指标执行独立样本 t-test计算Cohen’s d效应量并进行Benjamini-Hochberg FDR 校正以中英双语图表图注 表头呈现结果含开关变量控制耗时页面的生成与generate_report.m的区别generate_report.m单被试逐页展示无统计检验generate_stats_report.m两组汇总对比含 t-test / FDR / Cohen’s d页面数量固定最多 21 页2. 依赖环境依赖项版本要求用途MATLABR2020b 及以上推荐 R2022b主运行环境SPMSPM25spm_25_01_02NIfTI 文件读取spm_vol、spm_read_volsStatistics and Machine Learning Toolbox必须ttest2独立样本 t-testexportgraphics函数MATLAB R2020a 内置PDF 页面输出低版本自动回退printSPM 路径硬编码在脚本开头需按实际修改spm_pathD:\0share\0matelab_scripts\spm_25_01_02;3. 目录结构要求以root_dir F:\test为例F:\test\ ├── data.csv ← 必须被试分组信息 ├── test-01\ │ └── results\ │ ├── framewise_displacement.mat ← 变量fd向量 │ ├── brain_mask.nii ← 脑掩模用于提取体素均值 │ ├── ALFF.nii │ ├── fALFF.nii │ ├── sReHo.nii │ ├── sVMHC.nii │ ├── 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_zN×N, roi_idsN×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\ ├── GroupComp_ALFF\ │ ├── spmT_0001.nii ← AB 对比 T 图 │ └── spmT_0002.nii ← BA 对比 T 图 ├── GroupComp_fALFF\ ├── GroupComp_sReHo\ ├── GroupComp_sVMHC\ └── GroupComp_DC_WeightedSum\除data.csv外其余文件均为可选——缺失时对应页面跳过不报错。4. 输入参数参数类型默认值说明root_dircharF:\test数据根目录含test-*被试子目录及group_analysis/group_csvcharroot_dir/data.csv被试分组 CSV 文件路径data.csv格式列名类型必须说明SubjectID字符串✅被试 ID需与test-*目录名对应如sub-01对应test-01Group整数✅组别编号1 组A2 组BAge数值❌年龄有则显示在被试信息表中其他列任意❌读入但不使用示例SubjectID,Group,Age sub-01,1,24 sub-02,1,26 sub-03,2,23 sub-04,2,28被试目录匹配规则脚本按以下优先级将SubjectID映射到test-*目录精确匹配test-两位数字格式如sub-01→test-01名称完全匹配strcmpi按 CSV 行顺序与扫描到的test-*目录顺序对应5. 输出文件文件名路径说明fMRI_Stats_Report.pdfroot_dir/fMRI_Stats_Report.pdf多页矢量 PDF11×8.5 英寸横向最多 21 页若文件已存在先删除再重建。默认关闭 2 个可选页面见 §6 开关变量实际页数约为 19–21 页。6. 全局配置参数脚本顶部提供以下可调配置项无需修改函数签名6.1 报告生成开关do_dfc_pagefalse;% 第 15–16 页dFC 状态停留时间 中心矩阵可视化默认关闭do_hub_pagefalse;% 第 19 页Hub 节点分析耗时默认关闭开关默认控制页面说明do_dfc_pagefalse第 15 页dFC 状态停留时间 第 16 页聚类中心可视化两页同时开/关对 ROI 数量大时渲染较慢do_hub_pagefalse第 19 页Hub 节点分析显示 Top-10 Hub 节点汇总表及得分分布图将对应开关设为true即可启用该页面。6.2 颜色方案colorblind-safeCLR_A[0.000.450.70];% 组A蓝色CLR_B[0.850.330.10];% 组B橙色CLR_diff[0.470.670.19];% 差异绿色未使用CLR_NETlines(7);% 7 网络颜色颜色组合参考 Wong (2011) colorblind-safe palette同时考虑色觉缺陷人群的可读性。7. 调用方式% 方式一使用默认路径和默认 data.csvgenerate_stats_report(F:\test)% 方式二指定分组 CSVgenerate_stats_report(F:\test,F:\test\my_groups.csv)命令窗口输出示例 fMRI 统计分析报告 被试: 20 (组A10, 组B10) 输出: F:\test\fMRI_Stats_Report.pdf ── 预加载被试数据 ── ✓ sub-01 加载完成 ✓ sub-02 加载完成 ... [页面 1] 封面 [页面 2] 被试信息表 [页面 3] 质量控制 FD ... ═══════════════════════════════════════════════════════ ✅ 统计分析报告生成完成! 输出: F:\test\fMRI_Stats_Report.pdf 大小: 2541.3 KB / 共 19 页 ═══════════════════════════════════════════════════════8. 数据预加载流程脚本在生成任何报告页面之前先对所有被试循环一次预加载以下数据数据类型变量名维度来源文件FD 时间序列fd_all{n_subj × 1}cellframewise_displacement.matFD 统计量fd_mean,fd_max,fd_pct025n_subj × 1同上计算得到体素指标均值met_meann_subj × 5ALFF.nii等用brain_mask.nii掩模种子点FC均值seed_mean_fcn_subj × 6SeedFC/FC_*.nii全脑掩模均值Atlas FC 矩阵fc_mat_all{n_subj × 1}cellFC_matrix.mat网络内FCnet_withinn_subj × 7由FC_matrix.mat计算网络间FCnet_betweenn_subj × 7 × 7由FC_matrix.mat计算dFC 状态dfc_all{n_subj × 1}celldFC/dFC_states.mat图论全局指标gta_valsn_subj × 7GraphTheory.mat节点级指标node_deg,node_str,node_bc,node_cc{n_subj × 1}cellGraphTheory.mat体素指标提取方式读取brain_mask.nii0/1 体素掩模提取Y(mask3d)内的非零有限值计算其均值、标准差和中位数。网络内/间 FC 计算根据 §12 网络映射表将 AAL3 ROI 分配到 7 个网络提取对应 FC_z 子矩阵取上三角均值网络内或全矩阵均值网络间。9. 报告页面详解总览页码标题类型统计检验开关1封面文字——2被试基本信息表格——3质量控制 FD图 表——4全脑体素指标汇总表 柱状图——5ALFF 组间 T-map脑图——6fALFF 组间 T-map脑图——7ReHo 组间 T-map脑图——8VMHC 组间 T-map脑图——9DC 组间 T-map脑图——10种子点 FC 组间对比表 柱状图✅ t, p, p(FDR), d—11Atlas FC 矩阵差异热图热图——12网络内 FC 组间对比表 柱状图✅ t, p, p(FDR), d—13网络间 FC 矩阵热图——14网络×指标差异热图热图——15动态 FC 状态分析表 堆叠图—⚠️do_dfc_pagetrue16dFC 状态中心矩阵条形图—⚠️do_dfc_pagetrue17图论全局指标表 雷达图 柱状图✅ t, p, p(FDR), d—18节点级图论分布直方图——18节点级汇总表表格——19Hub 节点分析表 得分图—⚠️do_hub_pagetrue20综合结果摘要文字——21统计方法说明与局限性文字——第 1 页封面内容报告双语标题中文 英文生成时间、数据目录、被试总数组A / 组B全部分析指标列表样本量警告若每组 N1 时提示无法推断统计第 2 页被试基本信息表1内容列出每位被试的 ID、组别以及年龄如 CSV 含Age列。末尾附各组年龄均值 ± SD 汇总行。第 3 页质量控制 FD图1布局区域内容左上图0.56 宽所有被试 FD 时间序列组A蓝色组B橙色红虚线标注 0.25 mm 阈值右上图0.28 宽组均值柱状图含误差线SD下方表格每位被试FD均值(mm)、FD最大值(mm)、超阈值帧百分比(0.25mm)图注含组A/B的均值±SD数值描述。第 4 页全脑体素指标汇总图2/表2布局区域内容上方表格每位被试 × 5 指标的脑掩模内均值末尾附各组均值行下方柱状图5 指标组间均值对比分组并排柱状图误差线SD5 个体素级指标文件名报告缩写含义ALFF.niiALFF振幅低频波动fALFF.niifALFF分数振幅低频波动sReHo.niiReHo平滑局部一致性sVMHC.niiVMHC平滑体素镜像同伦连接DC_WeightedSum.niiDC度中心性加权和第 5–9 页组水平 T-map图3–7每个指标一页ALFF、fALFF、ReHo、VMHC、DC布局区域内容上半A B 对比 T 图spmT_0001.niicolormap: jet范围 [-6, 6]下半B A 对比 T 图spmT_0002.nii图注含全脑均值、差异方向、差异百分比。数据来源group_analysis/GroupComp_metric/spmT_000*.nii。若 T 图文件不存在显示红框提示Not found。第 10 页种子点 FC 组间对比图8/表3布局区域内容上方表格表36 个种子点 × 9 列ROI, G1均值, G2均值, Δ, t, p, p(FDR), d, 方向下方柱状图6 个种子点的组均值 FC 对比分组并排6 个种子点种子点坐标/定义PCC后扣带回mPFC内侧前额叶L_DLPFC左侧背外侧前额叶R_DLPFC右侧背外侧前额叶L_Amygdala左侧杏仁核R_Amygdala右侧杏仁核FC 值定义全脑掩模内 Fisher-z 均值非特定目标区域的连接。统计对每个种子点进行独立样本 t-testFDR 校正跨 6 个比较显著结果p 0.05以*标注。第 11 页Atlas FC 矩阵差异热图图9布局3 幅并排热图热图内容颜色范围左组A平均 FC 矩阵AAL3 N×N[-1, 1]中组B平均 FC 矩阵[-1, 1]右差异矩阵A-B[-0.5, 0.5]组平均计算对各组内被试 FC_z 矩阵取算术平均缺失被试不计入。ColormapRdBu红强/正蓝弱/负。第 12 页网络内 FC 组间对比图10/表4布局区域内容上方表格表47 个网络 × 10 列网络中文名, 缩写, G1均值, G2均值, Δ, t, p, p(FDR), d, 方向下方柱状图7 个网络内 FC 组均值对比7 个 Yeo 功能网络缩写中文名英文名DMN默认模式网络Default Mode NetworkFPN额顶控制网络Frontoparietal NetworkDAN背侧注意网络Dorsal Attention NetworkVAN腹侧注意网络Ventral Attention NetworkSMN感觉运动网络Sensorimotor NetworkVIS视觉网络Visual NetworkLIM边缘网络Limbic Network统计对每个网络进行独立样本 t-testFDR 校正跨 7 个比较。第 13 页网络间 FC 矩阵图11布局3 幅并排 7×7 热图热图颜色范围组A均值矩阵[0, 0.5]组B均值矩阵[0, 0.5]差异矩阵A-B[-0.3, 0.3]对角线填充对应网络的网络内 FC 均值而非 0。第 14 页网络×指标差异热图图12布局3 幅热图热图内容左上7×5组A各网络×各指标均值右上7×5组B各网络×各指标均值下方7×5差异热图A-B含数值标注注意此处体素指标均值为各指标的全被试组均值而非网络特异性提取所有网络行数值相同。这是当前实现的简化处理——如需网络特异性提取需对各网络的 ROI 单独计算指标均值。差异热图每格包含文字标注正值红色负值蓝色接近0灰色阈值 ±0.05。第 15–16 页动态 FC 状态分析【do_dfc_pagetrue才生成默认关闭】触发条件do_dfc_page true默认false。两页同时启用或关闭。第 15 页布局区域内容上方表格表5每位被试 × 5 个状态的停留时间占比末尾附各组均值行下方堆叠柱状图两组在 5 个 dFC 状态的平均时间分配比例停留时间dwell time fraction某状态出现的窗口数 / 总窗口数。聚类数固定dfc_k 5需与run_post_analysis.m中一致。第 16 页dFC 状态中心矩阵图14【同do_dfc_page开关】触发条件do_dfc_page true且至少有一个被试有 dFC 数据。内容选取有 dFC 数据的第一个被试显示 k 个聚类中心的 FC 边向量条形图每图一个状态横轴FC 上三角所有边纵轴Fisher-z 值。耗时原因ROI 数量较多165 区 → 13530 条边渲染条形图较慢。第 17 页图论全局指标图15/表6布局两个表格 两个图区域内容上方表格数据表每位被试 × 7 个图论指标末尾附各组均值行下方表格统计表7 个指标 × 9 列指标名, G1均值, G2均值, Δ, t, p, p(FDR), d, 方向左下雷达图5 个指标CC, Eglob, Q, σ, γ归一化后的极坐标图两组叠加右下柱状图7 个指标的原值分组对比含误差线7 个图论全局指标变量名英文标签含义CC_meanMean CC全图平均聚类系数lambdaChar Path (L)特征路径长度EglobGlobal Eff.全局效率QModularity (Q)模块度sigmaSmall-World (σ)小世界系数σ γ/λ_ngammaγ归一化聚类系数lam_nλ_n归一化路径长度统计对每个指标进行独立样本 t-testFDR 校正跨 7 个比较。第 18 页节点级图论分布图16布局4 幅分布直方图并排图指标颜色①节点度Degree组A蓝 / 组B橙②节点强度Strength同上③聚类系数CC同上④介数中心性BC同上直方图以概率归一化Normalizationprobability20 个 bin。随后独立一页显示节点级汇总表表7含 4 个指标的组A/B 均值 ± SD 及方向。第 19 页Hub 节点分析图17/表8【可选do_hub_pagetrue】Hub 得分定义Hub_score (norm.Degree norm.Strength norm.BC) / 3其中各指标分别对 [min, max] 做 min-max 归一化取三者均值作为综合 Hub 得分。内容表格表8每被试 Top-10 Hub 节点ROI 编号 得分折线图所有被试按 Hub 得分降序排列的节点曲线前 10 个节点用实心点高亮第 20 页综合结果摘要结构化文字摘要分 5 节质量控制各组 FD 均值和超阈值帧比例体素级指标5 个指标的组间方向和差异百分比功能连接全矩阵均值FCDMN 和 FPN 内FC图论指标7 个指标的组间具体数值对比统计说明样本量是否足够推断统计的提示第 21 页统计方法说明与局限性详细记录以下内容供报告引用数据预处理方法SPM/CAT12/DPABI 参数各分析指标的计算方法统计检验说明t-test、FDR、效应量局限性样本量、网络映射精度、GLM 阈值化等工具箱引用建议10. 统计方法说明10.1 独立样本 t-test由内部函数do_ttest2(x, y)实现调用 MATLAB 内置ttest2。触发条件每组有效被试数 N ≥ 2否则返回 NaN表格显示—。输出返回值说明pval双尾 p 值tstatt 统计量df自由度Welch 修正cohendCohen’s d 效应量Cohen’s d 计算sp sqrt(((n1-1)*var(x) (n2-1)*var(y)) / (n1n2-2)) d (mean(x) - mean(y)) / sp正值表示组A 组B负值表示组B 组A。通常 |d| 0.2 为小效应0.2–0.8 为中效应 0.8 为大效应。10.2 Benjamini-Hochberg FDR 校正由内部函数fdr_bh(p_raw)实现不依赖任何工具箱。校正范围每个独立统计表分别校正不跨页合并例如页10对 6 个种子点的 p 值校正页12对 7 个网络的 p 值校正页17对 7 个图论指标的 p 值校正算法标准 BH 步骤对 m 个 p 值从小到大排序得到秩 i调整后 p 值p_adj(i) p(i) × m / i单调化从大到小取累积最小值截断至 [0, 1]10.3 p 值显示规则由fmt_pval(p)函数格式化条件显示p NaN—样本量不足p 0.001.001*0.001 ≤ p 0.050.xxx*加星号p ≥ 0.050.xxx无星号11. 辅助函数说明do_ttest2(x, y)← 主要统计函数[pval,tstat,df,cohend]do_ttest2(x,y)独立样本 t-test 封装自动去除 NaN组 N 2 时返回全 NaN。fdr_bh(p_raw)p_fdrfdr_bh(p_raw)Benjamini-Hochberg FDR 校正输入 m×1 向量输出校正后 p 值向量NaN 值跳过。fmt_pval(p)sfmt_pval(0.032)% → 0.032*sfmt_pval(0.0002)% → .001*sfmt_pval(NaN)% → —sfmt_pval(0.12)% → 0.120格式化 p 值为显示字符串显著者加星号。fmt_num(v)sfmt_num(3.14159)% → 3.142sfmt_num(NaN)% → —格式化数值为 3 位小数字符串NaN 显示破折号。direction_symbol(valA, valB)sdirection_symbol(0.5,0.3)% → ↑ G1G2sdirection_symbol(0.3,0.5)% → ↓ G1G2sdirection_symbol(0.5,0.5)% → 相等返回组间方向文字描述用于表格方向列。ternary_color(val)cternary_color(0.1)% → [0.6 0.0 0.0]红cternary_color(-0.1)% → [0.0 0.0 0.6]蓝cternary_color(0.01)% → [0.3 0.3 0.3]灰根据正负值阈值 ±0.05返回文字颜色用于热图数值标注。共享辅助函数与generate_report.m相同函数签名功能new_figfig new_fig()创建离屏图形窗口11×8.5 英寸save_pagesave_page(fig, pdf_out)追加保存页面到 PDFsection_titlesection_title(fig, txt)绘制页面蓝色标题栏caption_textcaption_text(fig, txt)绘制页面底部图注文字draw_tabledraw_table(fig, tdata, pos, fs)绘制 cell 数组表格slice_montageslice_montage(nii, label, cmap, pos, clim)NIfTI 轴位切片蒙太奇rdbu_colormapcmap rdbu_colormap()生成红-白-蓝 256 色 colormapget_colormapcmap get_colormap(name)根据名称返回 colormapcaption_text是generate_stats_report.m相比generate_report.m新增的辅助函数用于统一格式的图注文字。12. 网络-ROI映射参考基于 AAL3165 区→ Yeo 7-network 的近似手动映射参考 Rolls ET (2020)NeuroImage和 AAL3 标准分区文档。网络缩写主要 AAL3 脑区ROI 编号1-indexed部分默认模式网络DMNmPFC, PCC/楔前叶, 角回, 颞中回, 顶下小叶25,26,67,68,55,56,65,66,61,62,83,84,87–90额顶控制网络FPNDLPFC, 顶下小叶, dACC, 尾状核3,4,7,8,9,10,59,60,11,12背侧注意网络DANFEF, IPS/顶上小叶57,58,69,70,1,2,19,20腹侧注意网络VANTPJ, 腹侧前额叶, 岛叶, 缘上回13,14,15,16,29,30,63,64感觉运动网络SMN中央前/后回, SMA, 旁中央小叶1,2,57,58,17,18,69,70,71,72视觉网络VIS距状裂, 楔叶, 舌回, 枕叶43–54边缘网络LIM杏仁核, 海马, 海马旁回, OFC, 颞极31,32,37,38,39,40,27,28,85,86,35,36注意SMN 与 DAN 之间存在 ROI 重叠如 ROI 1,2,57,58这是基于 Yeo 7-network 映射的近似在边界区域不可避免。网络内 FC 计算时每个被分配的 ROI 只计算一次重叠 ROI 会同时贡献两个网络的计算。13. 常见问题与排错Q1运行报错Undefined function ‘ttest2’原因未安装或未激活 Statistics and Machine Learning Toolbox。解决% 检查是否有该工具箱ver(stats)若无需安装该工具箱或使用自定义 t-test 实现替换do_ttest2中的ttest2调用。Q2统计列全部显示—无法计算 t 值原因每组有效被试数 N 2如每组只有 1 人或某指标数据缺失。说明这是正常行为。当 N 2/组时独立样本 t-test 无意义do_ttest2返回 NaN表格显示—。解决增加每组样本量至 N ≥ 2。Q3第 11 页 FC 矩阵热图是全零全蓝原因两组被试均无FC_matrix.mat文件fc_A、fc_B保持全零初始值。排查确认run_post_analysis.m的 Atlas FC 计算模块§C已正确运行并保存了FC_matrix.mat。Q4被试目录匹配失败某被试数据未加载症状命令窗口显示⚠ sub-XX: results/ 不存在。原因CSV 中SubjectID格式与test-*目录不匹配。解决确认目录命名规律例如sub-01对应test-01ID 提取规则取SubjectID第 2 字符以后的数字转换为两位数格式。若命名规则不同修改脚本中的目录匹配段落ifstrcmpi(subj_list(d).name,[test-sprintf(%02d,str2double(sid(2:end)))])Q5第 20 页综合摘要显示fc_A未定义错误原因若第 11 页Atlas FC 矩阵被跳过n_roi_fc 0变量fc_A、fc_B不会被计算导致第 20 页访问未定义变量。解决在脚本中找到第 20 页summary_lines部分将 FC 均值计算行用try-catch或exist判断保护% 如果 fc_A 不存在则使用 NaNifexist(fc_A,var)fc_A_meannanmean(nanmean(fc_A));fc_B_meannanmean(nanmean(fc_B));elsefc_A_meanNaN;fc_B_meanNaN;endQ6报告生成速度慢主要耗时环节预加载数据逐被试读取 NIfTI 文件第 16 页dFC 状态中心165 ROI → 13530 条边的条形图第 19 页Hub 节点分析所有节点得分计算优化建议确保do_dfc_page false、do_hub_page false默认值将数据目录放在 SSD 上加速 NIfTI 读取MATLAB 并行工具箱可对预加载循环使用parfor需修改代码附录页面坐标系说明所有绘图位置均使用 MATLAB 归一化坐标0–1以图形左下角为原点(0,1)────────────(1,1) | | | 页面内容区域 | | | (0,0)────────────(1,0)annotation、axes的Position参数格式[x_left, y_bottom, width, height]标题栏[0.0, 0.93, 1.0, 0.07]顶部 7% 高度图注区[0.04, 0.01, 0.92, 0.04]底部 4% 高度内容区[0.04, 0.06, 0.92, 0.86]中间 86%文档对应脚本版本generate_stats_report.mv1.0最后更新2026-04