ace

# Ace — 数据分析王牌 > 一站式覆盖实证分析全套、统计检验、问卷分析、论文格式、学术绘图。 --- ## 0.0 工作区整洁规则 - 在用户项目目录内执行 `ace` 任务时，**所有新建分析脚本、清洗脚本、绘图脚本、临时验证脚本，默认统一放入项目内的 `scripts/` 文件夹**，不要直接散落在主目录。 - 若任务较大或包含多个子任务，允许在 `scripts/` 下继续分支，例如： - `scripts/eda/` - `scripts/regression/` - `scripts/2026-04-16_rice_quality/` - 若项目本身已经存在集中管理脚本的目录，则优先复用该目录并继续分层；若没有，则主动创建 `scripts/`。 - 主目录应尽量只保留数据、文稿、最终交付物和必要配置文件，避免被一次性脚本、临时调试文件污染。 - 本 Skill 自带的模板脚本仍位于 Skill 包内的 `scripts/`，而**针对当前用户任务新生成的脚本**应放在用户项目自己的集中脚本目录中。 ## 0. 附带代码模板 - `scripts/precheck.py`：环境、文件、依赖与输入前置检查 - `scripts/check_assumptions.py`：正态性、方差齐性、VIF 等前置检验 - `scripts/questionnaire_pipeline.py`：问卷全套流水线（清洗、描述、信度、KMO/Bartlett、EFA） - `scripts/anova_pipeline.py`：方差分析、LSD、多重比较、结果输出 - `scripts/generate_spss_syntax.py`：SPSS 语法生成 - `scripts/three_line_table.py`：三线表输出 - `scripts/merge_report.py`：结果合并与报告装配 - `scripts/verify_report.py`：报告一致性核查 - `code_library/descriptive.py` / `correlation.py` / `ttest.py` / `anova.py`：基础统计函数 - `code_library/regression.py` / `did.py` / `mediation.py`：实证分析核心函数 - `code_library/survey.py`：问卷信效度、EFA、AVE/CR - `code_library/ml_pipeline.py`：机器学习基线与调参代码库 - `code_library/plot_bindent.py`：学术绘图初始化、字体、配色与图模板 - `code_library/report_builder.py` / `word_utils.py`：Word 报告写作与格式辅助 使用原则： - `scripts/` 优先用于可直接运行的流水线与检查脚本 - `code_library/` 优先用于按需 import 的函数与片段库 - 优先复用这些入口并按任务改参数，不要每次从零重写 ## 0.1 模板引擎与报告模板预设 - `_ace_templates/engine.py`：模板装配入口，用于按预设生成结构化交付 - `_ace_templates/text_library/blocks.py`：标准分析文字块库，适合问卷、信效度、相关、回归、中介等段落复用 - `_ace_templates/text_library/word_engine.py`：Word 段落与格式写入辅助 - `_ace_templates/format_presets/`：报告格式预设 - `report_delivery.json`：客户交付报告 - `spss_mimic.json`：SPSS 风格输出 - `thesis_songti.json`：论文宋体风格 - `thesis_strict.json`：更严格的论文格式 - `compact_mini.json`：轻量简版 - `_ace_templates/templates/`：场景化流水线模板 - `A1_questionnaire` - `A2_questionnaire_mediation` - `B1_cross_section` - `C1_anova` - `D1_medical` - 使用原则： - 若任务需要“脚本 + Word 报告 + 固定格式预设”一体化交付，优先考虑 `_ace_templates` - 若只是常规单次统计分析，优先复用 `scripts/` 与 `code_library/`，避免过度模板化 ## 0.1.1 Word 默认格式规范 - 对中文论文、分析报告、提纲、三线表配套说明等 Word 输出，默认优先使用 `_ace_templates/format_presets/thesis_strict.json`。 - 若用户明确要求更常见的毕业论文宋体版式，可退回 `thesis_songti.json`。 - 若输出内容需要**直接插入现有论文的某一章/某一节**，默认进入“论文章节嵌入模式”： - 标题层级优先继承目标论文原有编号，例如 `4.5`、`4.5.1`、`4.5.2` - 不保留独立报告味较重的总标题与小节标题，如 `问卷数据分析报告`、`补充分析`、`开放题结果归纳` - 小节名称优先改写为能直接放入论文正文的口径，如 `受访者基本情况与包裹感认知`、`核心情感量表检验`、`情感需求总结` - 默认规范如下： - 中文标题与各级标题：`黑体`、黑色、加粗 - 正文中文：`宋体` - 正文英文与数字：`Times New Roman` - 任何位置的英文和数字都必须使用 `Times New Roman`，包括标题中的英文、表头英文、图例、年份角标、括号中的英文单位、处理缩写（CK、GA、BR、MeJA、6-BA）和显著性字母。 - 正文：首行缩进 `2` 字符，`1.5` 倍行距，段前段后 `0` - 表题：黑体；表内文字：宋体 + Times New Roman - 禁止依赖 Word 主题字体或系统默认东亚字体，避免出现 `MS Gothic`、彩色标题或模板化样式污染正式文稿。 - 若用户提供学校模板、期刊模板或既有格式文件，则以用户模板优先覆盖此默认规范。 ## 0.1.2 图表与三线表默认规范 - 正式论文图片文件本体默认不放图题，图题统一写在 Word 正文中。 - 坐标轴名称必须完整；有单位的指标必须显式写单位。 - 单指标主图默认优先使用原始均值 ± 误差；效应总览图可用相对 CK 变化百分比；综合评价图可用标准化指数。 - 中文科研图中英混排字体的稳定做法（2026-04-22 侯芳芳项目验证）： - 目标是中文用宋体，英文、数字、单位、图例、刻度、显著性标记、公式变量用 Times New Roman 正体；不要默认斜体。 - Matplotlib 直接输出 PNG 时，中英混排标签容易被单一字体吞掉；更稳流程是先输出 SVG，并设置 `svg.fonttype='none'`，再用 `svg_font_splitter.py` 将中文与英文/数字拆成不同字体，最后再从修正后的 SVG 渲染 PNG。 - 若用 Chrome/Edge headless 渲染 SVG 为 PNG，必须按 SVG 原始尺寸设置截图窗口，并通过很小的 `right_extra`、`bottom_extra` 控制保留范围；不要一次性大幅扩边，也不要让截图裁掉边框、图例或坐标轴。 - 对 `K_L`、`K_N`、`K_N/K_L` 这类光氮分布参数，优先保证 Times New Roman 正体和大写下标 `L/N`；避免 mathtext 默认字体导致 DejaVu 或斜体。若使用 mathtext，必须显式设置 custom Times New Roman；若仍不稳，改用普通文本/分段绘制。 - 售后微调图件时只改用户点名的问题；若需要连带改导出方式、布局、字体方案或其它元素，必须先说明并等用户确认。 - 图例默认放在不遮挡数据的位置，优先右上角或左上角；必要时应主动调大 Y 轴范围。 - 柱状图若存在多处理比较，默认优先使用字母显著性分组，不只保留误差线。 - Word 中正式表格默认使用三线表，不使用 `Table Grid` 式网格表。 - 需要 Word 输出时，优先复用 `scripts/three_line_table.py` 或等价三线表逻辑，不要临时生成普通网格表。 - 若未被用户明确要求增加分隔线，三线表默认只保留顶线、表头下横线和底线，不额外添加中间横线、虚线或分块线。 - Word 中表格默认整体居中；若表后需要说明，表注必须紧跟对应表格下方，不得挪到正文末尾或下一张表之后。 - 对描述统计表、样本特征表、单因素比较表等分组表，默认将“变量”和“类别/组别”拆成不同列，不把变量名与类别值混在同一列；变量名默认只在该变量首行出现，后续类别行留空或按用户提供模板排版。 - 若交付的是“单一核心因变量”的单因素分析表，默认优先采用 `变量 | 组别 | 例数 | 因变量均值±标准差 | t/F | P` 的纵向分组样式；统计量与 P 值仅在该变量首行显示，后续组别行留空，默认对齐参考常见医学论文表格格式。 - Word 表格的“默认居中”不仅指表格对象整体居中，也指表头与单元格文字默认居中；除非用户明确要求左对齐，不要只把表框居中而把表内文字保留左对齐。 - 客户版 Word 报告中，表格、表注、结果分析之间默认顺序为：表格 → 表注 → 空一行 → 结果分析。 - 若用户明确说明“该内容要直接放到论文正文/某一章某一节”，或用户提供的论文原稿本身采用“先文后表”结构，则默认顺序应切换为：结果分析 → 表题 → 表格 → 表注。 - 论文章节嵌入模式下，表题默认采用论文口径，优先使用： - `表4.1 ……分析表` - `表4.2 ……检验表` - `表4.3 ……比较分析表` - 避免使用工作底稿或独立报告味较重的命名，例如 `描述统计与载荷结果`、`补充分析结果`、`开放题结果归纳` - 图表中英混排时必须逐元素指定字体：中文用 `宋体/黑体`，英文和数字用 `Times New Roman`；不得依赖系统自动回退或主题字体。 - 若交付对象是客户或外部收件人，Word/PDF 正文默认禁止出现“给内部看的元说明”，例如“本次参考截图/文献”“变量按当前字段重建”“以下为说明”“本轮修正了”等过程性文字。 - 客户版分析交付正文默认只保留：标题、表格/图、表注、结果分析、必要统计口径与直接结论；方法来源、截图参考、核查说明、版本差异等内容应写入核查日志、脚本注释或项目记录，不进入客户正文。 ## 0.1.3 客户版交付成品自动核查清单 适用于 `兼职/` 下所有需要交付 Word 报告、论文式分析说明、正式统计表或客户可见结果文档的任务。只要用户没有明确要求保留过程说明，交付前必须回看最终成品文件，而不是只检查生成脚本。 - 客户可见正文、表题、表注、文件名中默认不得出现过程化/内部化措辞，包括但不限于：`客户`、`本轮`、`当前设定`、`本报告`、`过程说明`、`交付`、`模拟`、`内部看的`、`用于本科论文`、`论文写作而言`、`按客户要求`、`结果整理`。确需说明数据版本或模拟属性时，应放入核查日志、项目记录或单独说明文件，不混入正式正文。 - 客户可见标题、文件名、SPS/SPV/SAV/Excel/Word 成品名默认不得带内部单号、接单号、文件夹编号或我们自己的项目追踪号，例如 `050201-120`、`042102-240`、`157_`、`XX_` 这类前缀。内部编号只允许出现在项目文件夹、progress、核查日志或内部文件清单中，不进入客户可见成品。 - 标题、文件名和表格说明默认使用研究主题或指标名称，不使用 `本科论文`、`最终版`、`模拟调整版`、`核查版`、内部单号等标签作为客户可见主标题。推荐命名如 `统计分析报告.docx`、`问卷数据分析报告.docx`、`SPSS分析结果.spv`、`结果提取表.xlsx`；若需区分主题，可写 `生涯适应力影响机制分析报告.docx`。 - 当客户要求“过程文件/过程结果”打包时，默认按客户可见最小集处理，不把整个项目文件夹打包。Stata/实证类任务默认包含：最终稿件、Stata 输出结果表（通常为脚本整理导出的 Excel，如 `第四章实证结果.xlsx`）、Stata 数据文件（整理后面板 `.dta` 与各表对应 `.dta`）。若需放脚本，只放纯数据整理、统计分析、诊断模型脚本；不得放生成 Word/PDF 报告的脚本、日志、核查日志、说明草稿、后台复现包、临时文件或含个人绝对路径的信息，除非用户明确要求。 - 样本量、频数、题项数、自由度等计数型数值默认显示为整数；百分比通常保留 2 位小数；系数、均值、标准差、Cronbach's α、KMO、CR、AVE、载荷、VIF 通常保留 3 位小数；`p` 值使用 `<0.001` 或 3 位小数，星号必须与 `p` 值一致。 - 分组表、样本特征表、描述统计分块表中，重复的变量名默认只显示第一行，后续行留空；不得把同一变量名在每个类别行机械重复。 - Word 成品必须核查 A4 页面、页边距、标题黑色、正文黑色、表格整体居中、表内文字居中、单元格段前段后为 0、首行/左右缩进为 0；三线表默认只保留顶线、表头下横线和底线。 - 问卷/量表结果需核查信效度指标是否相互协调：Cronbach's α 与 CR 不应明显背离，AVE、因子载荷、KMO、Bartlett、CR 之间不能出现数学或统计逻辑矛盾；不能只把某个指标调到达标而破坏其他指标。 - 回归、中介、调节等模型结果需核查 `N`、变量方向、显著性、置信区间、VIF 与正文结论一致；不得出现表格支持、正文不支持或星号与 `p` 值不一致。 - 导出后必须用 `python-docx`、`openpyxl`、XML 检查或人工打开成品之一核对最终 `.docx`/`.xlsx`。如果目标文件被 Word 锁定，另存为清晰命名的修订文件，并在回复中说明实际成品路径。 ## 0.2 多 Agent 分析编排 - 默认策略：条件式多 Agent，不是所有任务一开始都并行；优先遵循当前项目或全局 AGENTS.md 的多 Agent 规则。 - 触发条件：存在 2 个及以上彼此独立的子任务；或数据分析任务预计同时产出脚本、表格、报告、核查记录等多个成果；或用户明确要求多 Agent / 三省六部模式。 - 暂不并行：单文件小改、一次性问答、简单润色、几分钟可完成的小修复、强串行依赖任务，以及根因尚未定位的疑难 bug。 - 执行原则：主 Agent 先做最小必要理解和任务拆分；子 Agent 只接收边界清晰、可独立交付的检索、审查、测试或局部实现任务；多个 Worker 的写入范围必须互不重叠；派发后主 Agent 继续推进关键路径，仅在被结果卡住时等待。 ## 一、何时触发 - 统计/实证：方差分析、ANOVA、回归、DID、中介效应、前后测 - 检验/诊断：正态性、方差齐性、相关分析、非参数检验 - 问卷/调研：Likert、SERVQUAL、信度、效度、因子分析 - **机器学习**：随机森林、XGBoost、SVM、调参、特征重要性、SHAP - 格式/输出：论文格式、三线表、页眉页码、Word报告 - 绘图：matplotlib、配色、DID系数图、误差棒、热力图、混淆矩阵、学习曲线 --- ## 二、前置检验模块（任何分析前必做） ### 2.1 正态性检验 ```python from scipy import stats # Shapiro-Wilk（n<5000，首选） stat, p = stats.shapiro(data) # Kolmogorov-Smirnov（大样本） stat, p = stats.kstest(data, 'norm', args=(data.mean(), data.std())) # 判断：p>0.05 → 正态，否则用非参数检验 ``` ### 2.2 方差齐性检验 ```python # Levene 检验（稳健，首选） stat, p = stats.levene(group1, group2) # Bartlett 检验（严格正态假设下） stat, p = stats.bartlett(group1, group2) ``` ### 2.3 多重共线性诊断（回归前） ```python from statsmodels.stats.outliers_influence import variance_inflation_factor vif = pd.DataFrame({ 'Variable': X.columns, 'VIF': [variance_inflation_factor(X.values, i) for i in range(X.shape[1])] }) # VIF>10 → 严重共线性，需剔除或合并 ``` ### 5.6.1 AMOS 原生图自动输出（本机已验证） - 适用场景： - 客户明确要求 **AMOS 原生风格** 的测量模型图 / 路径图 - 不能接受 Python / matplotlib / draw.io 仿图 - 允许使用本机已安装的 `IBM SPSS Amos 29` - 重要边界： - **分析结果本身不是默认“顺手自动出 AMOS 图”**。如果主分析最初不是在 AMOS 里跑的，而是 Python / SPSS / 其他流程跑的，则需要**单独重建一份 AMOS 模型文件**再导出图。 - 这条链路的核心是：**先有 `.amw`，再让 `AMOS CLI` 自动计算与导出**，而不是指望普通统计脚本自动附带一张 AMOS 图。 - 本机已确认可用组件： - `C:\Program Files\IBM\SPSS\Amos\29\AmosGraphicsCLI.exe` - `C:\Program Files\IBM\SPSS\Amos\29\AmosFileManagerCLI.exe` - `C:\Program Files\IBM\SPSS\Amos\29\R\Amos.R` - `C:\Program Files\IBM\SPSS\Amos\29\Documentation\Programming Reference.pdf` - 官方 `R\Amos.R` 已明确暴露命令行参数思路： - `-model <path-to-amw>` - `-plugin CalculateEstimatesAndExit.vb` - 本机实测结论： - 直接让 `CLI` 跑自定义 `.vb/.dll` 插件并不稳定，不应作为默认主路线。 - **更稳的默认路线** 是： 1. 先程序化生成 `.amw` 2. 再调用 `AmosGraphicsCLI.exe -model <amw> -plugin CalculateEstimatesAndExit.vb` 3. 等待 `AMOS` 自动生成输出文件 4. 若路径图已进入剪贴板，再由 PowerShell 把剪贴板中的图像落盘为 `.png` ### 5.6.2 AMOS 原生图无人工输出推荐流程 #### A. 准备数据文件 - 优先使用 **ASCII 路径**，避免中文路径导致 `AMOS` / Office 组件兼容问题。 - 这台机器上更稳的做法是先把数据复制到临时目录，例如： - `C:\Users\16342\AppData\Local\Temp\amos_<project>\` - 数据格式优先级： 1. `.sav` 2. `.xls` 3. `.xlsx` - 如果只有 `.xlsx`，而 `.amw` 对 Excel 读取不稳定，可先转成 `.xls`： ```powershell $src='C:\path\input.xlsx' $dst='C:\path\input.xls' $excel=New-Object -ComObject Excel.Application $excel.DisplayAlerts=$false $wb=$excel.Workbooks.Open($src) $xlExcel8=56 $wb.SaveAs($dst,$xlExcel8) $wb.Close($false) $excel.Quit() ``` #### B. 生成 `.amw` 模型文件 - 若客户只要图而不是重新在 `AMOS` 中建模，默认可直接程序化生成 `.amw`。 - 实操要点： - `.amw` 是**可编辑文本文件**，本机实测编码为 `UTF-16` - 可以从 `C:\Program Files\IBM\SPSS\Amos\29\Examples\English\*.amw` 选一个结构接近的模板 - 重点需要改的段包括： - `!@!ob`：对象块（矩形、椭圆、单箭头、双箭头、标题） - `!@!dbname` - `!@!dbtype` - `!@!dbconnect` - `!@!dbtable` - 常见数据连接写法（本机样例已见官方示例）： - `SPSS`：`dbtype=2`，`dbconnect=SPSS` - `Excel 8.0`：`dbtype=1`，`dbconnect=Excel 8.0` - `Text`：`dbtype=1`，`dbconnect=Text` #### C. 用 CLI 自动计算 - 默认命令： ```powershell & 'C:\Program Files\IBM\SPSS\Amos\29\AmosGraphicsCLI.exe' ` '-model' 'C:\path\model.amw' ` '-plugin' 'CalculateEstimatesAndExit.vb' ``` - 这条链路本机已实测会自动生成这些原生结果文件（命名因项目而异）： - `*.AmosOutput` - `*.amp` - `*_output.amw` - `*.AmosHistory` #### D. 导出 AMOS 原生路径图 - 若 CLI 运行后路径图已进入剪贴板，可直接用 PowerShell 抓图并保存： ```powershell Add-Type -AssemblyName System.Windows.Forms Add-Type -AssemblyName System.Drawing $img=[Windows.Forms.Clipboard]::GetImage() if($img -ne $null){ $out='C:\path\AMOS_native.png' $img.Save($out,[System.Drawing.Imaging.ImageFormat]::Png) } ``` - 这一步拿到的就是**AMOS 原生图**，不是仿图。 #### E. 默认决策 - 用户明确说“必须是 AMOS 画 / AMOS 原生输出”： - **优先走 `.amw + CLI + 原生导图`** - 不要再拿 matplotlib 仿图替代 - 用户只要“风格像 AMOS”： - 可退回仿图路线 - 如果 `AMOS CLI` 跑通了结果文件，但剪贴板未携带图像： - 先保留 `.amw / .amp / .AmosOutput` - 再判断是否需要补一层 GUI 自动化或人工导图 - 如果用户要求“完全无人工”： - 先明确：**只有在 `.amw` 生成 + CLI 自动计算 + 剪贴板导图都跑通时，才能宣称彻底无人工** - 任一环未打通，都必须如实说明卡点 ### 5.6.3 本机已验证事实（2026-04-20） - `AmosGraphicsCLI.exe` 能稳定吃到 `-model` 和 `-plugin` 参数 - `CalculateEstimatesAndExit.vb` 这条官方插件名在本机可触发自动计算 - 本机已成功产出： - `.AmosOutput` - `.amp` - `*_output.amw` - 本机已成功从系统剪贴板导出一张 `AMOS` 原生路径图为 `.png` - 因此：**这台机器上，AMOS 原生图的“无人工自动导出”是可行的，但前提是先准备好可用的 `.amw` 模型文件** --- ## 三、统计分析模块 ### 3.1 描述性统计 ```python desc = df.describe().T desc['median'] = df.median() desc['skewness'] = df.skew() desc['kurtosis'] = df.kurtosis() # 分类变量：频率表 + 百分比 ``` ### 3.2 相关分析 ```python # Pearson（连续+正态） r, p = stats.pearsonr(x, y) # Spearman（有序/非正态） rho, p = stats.spearmanr(x, y) # 相关矩阵热力图 corr_matrix = df[num_cols].corr() ``` **绘图**：相关矩阵热力图，用 `plt.imshow()` 或 `sns.heatmap()`，标注相关系数和显著性星号。 ### 3.3 双因素方差分析（ANOVA） **工作流**： 1. 读取数据 → 分配受试者 ID 2. `statsmodels.formula.api.ols` + `anova_lm(typ=2)` 3. LSD 多重比较 → 紧凑字母显示（CLD） 4. 三线表 Word 输出 + 结果分析段落 **字母标记规则**： - **小写字母** = 同组内不同时间 LSD（P<0.05） - **大写字母** = 不同因素水平 LSD（P<0.05） ### 3.4 单因素方差分析 ```python # 参数检验（正态+方差齐） F, p = stats.f_oneway(g1, g2, g3) # 事后比较 from statsmodels.stats.multicomp import pairwise_tukeyhsd tukey = pairwise_tukeyhsd(df['value'], df['group']) # 非参数替代：Kruskal-Wallis H, p = stats.kruskal(g1, g2, g3) # 事后：Dunn 检验 + Bonferroni 校正 ``` ### 3.5 t 检验全家桶 ```python # 独立样本 t 检验 t, p = stats.ttest_ind(g1, g2, equal_var=True) # 方差齐 t, p = stats.ttest_ind(g1, g2, equal_var=False) # Welch's t # 配对样本 t 检验 t, p = stats.ttest_rel(pre, post) # 单样本 t 检验