Factorial Anova

Skill: factorial-anova

多因子變異數分析（Factorial ANOVA / ANCOVA）與 Word 報告匯出。

Metadata

• Description: 對兩個以上因子的獨立樣本設計執行 Type II / Type III ANOVA，含交互作用檢驗、事後兩兩比較（Tukey/Sidak）、簡單主效應剖析、共變量 (ANCOVA)、效應量 (η²/ω²/偏 η²)、交互作用圖。
• Version: 1.0.0
• Entrypoint: orchestrator.py（CLI: --source {local,sql,hadoop} + --y <col> + --factors <cols> + --covariates <cols> + --ss-type {2,3}）
• Related:
  • 單因子 ANOVA / t-test / 相關性：advanced-data-analytics
  • 迴歸建模：regression-analytics
  • EFA / CFA：factor-analysis

Analysis Modes

只有 一種 主要模式（factorial），依 --factors 個數與 --covariates 決定分析形態：

決策流程

1. 輸入契約校驗（data_fetcher.py）

   • y 為連續數值，factors 為類別（自動 to factor），covariates 為連續數值
   • listwise deletion，記錄丟棄筆數
   • 若某因子只有 1 個 level → 錯誤攔下
   • 若 cell 數量 <2 → 警告（無法估計交互）

2. 前置檢驗

   • 每個 cell 的樣本量（不平衡設計會影響 SS type 選擇）
   • Levene's Test 方差齊性（car::leveneTest）
   • 殘差 Shapiro-Wilk（正態性）

3. 主分析

   • Type II SS（預設，適用平衡+無交互假設；正交因子）
   • Type III SS（--ss-type 3，適用不平衡設計+有交互；預設 contr.sum）
   • car::Anova(fit, type=...)

4. 效應量（effectsize 套件）

   • 每個效應項的 偏 η² (partial eta²) + 95% CI
   • ω² (omega²) 無偏估計
   • Cohen's f（給 power 分析用）

5. 事後檢驗（自動觸發，可由 --no-posthoc 關）

   • 主效應顯著 → Tukey HSD（emmeans::pairs, adjust="tukey"）
   • 交互作用顯著 → 簡單主效應（simple main effects）：固定一個因子，比較另一個因子在該 level 上的差異，Sidak 校正
   • 兩兩比較都給出 estimate + SE + t + p_adj + 顯著標記

6. 可視化

   • 交互作用圖（Interaction Plot）：每個因子組合的估計邊際均值 + CI
   • 主效應圖（每個因子單獨）
   • 殘差 vs Fitted、Q-Q（假設檢驗診斷）

Output Location

預設輸出目錄：./outcome-temp/

• fetched_data.csv：資料快照
• FactorialANOVA_Report.docx：Word 報告
• interaction_plot.png / main_effects_plot.png / diagnostics.png

Workflow (SOP)

1. fetch: schema + variance 校驗（因子至少 2 levels、y/cov 為數值）
2. execute: car::Anova(aov(...), type=II/III) + 每個效應項 partial η² + Levene + Shapiro
3. posthoc: 主效應 Tukey / 交互作用 simple effects
4. render: 依實際觸發項目動態組裝章節

Constraints

• 數值保留 4 位小數
• Type III 需要 contr.sum 對比編碼 → skill 自動設定，執行完自動還原
• 交互作用不顯著（p ≥ 0.05）時，事後只跑主效應；顯著時只跑 simple effects（避免 double-dipping）
• 樣式集中於 templates/word_styles.json

Dependencies

• Python 3.10+: pandas sqlalchemy python-docx openpyxl pyhive thrift thrift-sasl pure-sasl
• R 4.x:
  • 必要: ggplot2 jsonlite car emmeans effectsize
  • 可選: showtext sysfonts（CJK 字型）