Factor Analysis

Skill: factor-analysis

因素分析（EFA / CFA）與 Word 報告匯出。

Metadata

• Description: 對問卷/量表資料執行探索性 (EFA) 或驗證性 (CFA) 因素分析，含完整前置適當性檢驗、因子數決定、旋轉、配適度指標、信度分析、路徑圖。
• Version: 1.0.0
• Entrypoint: orchestrator.py（CLI: --source {local,sql,hadoop} + --analysis {efa,cfa,both} + --items <cols> + 對應模式參數）
• Related:
  • 假設檢驗（t-test/ANOVA/相關性）：advanced-data-analytics
  • 迴歸建模：regression-analytics

Analysis Modes

1. efa — 探索性因素分析

• 輸入: 多個 item 欄位（--items Q1 Q2 ... Qn；至少 3 個，建議 ≥6）
• 決策流程:
  1. 適當性檢驗（自動全跑）:
     • KMO (Kaiser-Meyer-Olkin)：整體 + 每項；>0.6 可接受，>0.8 佳
     • Bartlett's Test of Sphericity：p<0.05 表示相關矩陣顯著非單位陣（適合做 FA）
  2. 因子數決定（自動全跑，--n-factors 可覆寫）:
     • Kaiser 準則：特徵值 >1 的因子數
     • Scree Plot：碎石圖 + 平行分析（Horn's Parallel Analysis）
     • MAP (Minimum Average Partial)
  3. 因子萃取 + 旋轉（--fm + --rotation）:
     • fm: pa (主軸法，預設) / ml (最大概似) / minres
     • rotation: oblimin (斜交，預設) / varimax (正交) / promax / none
  4. 輸出:
     • 因子負荷矩陣（含 pattern & structure，斜交旋轉時）
     • 每題共同性 (h²) 與獨特性 (u²)
     • 因子相關矩陣（斜交旋轉時）
     • 解釋變異量表

2. cfa — 驗證性因素分析

• 輸入:
  • --items <cols>（同 EFA）
  • --model <spec>：lavaan 語法字串，例如 "F1 =~ Q1+Q2+Q3; F2 =~ Q4+Q5+Q6"
• 決策流程:
  1. 估計方法 (--estimator): ML (預設) / MLR (穩健) / WLSMV（順序型變量）
  2. 配適度指標:
     • 絕對配適: χ² 及其 df / p、SRMR
     • 相對配適: CFI、TLI、NFI
     • 簡約配適: RMSEA + 90% CI + p(RMSEA<0.05)、AIC、BIC
  3. 參數估計:
  • 標準化因子負荷 (λ) + p 值
  • 潛變量相關/共變數（多因子時）
  • 殘差變異
  4. 信度:
     • Cronbach's α（各因子 + 整體）
     • McDonald's ω（若 semTools 可用）
  5. 修正指數 (MI)：Top-10 建議修正的參數
  6. 路徑圖（semPlot 若可用，否則以自製 ggplot 網絡圖代替）

3. both — 半分交叉驗證

• 資料隨機 split 50:50
  • 前半跑 EFA → 依 Kaiser + Parallel Analysis 建議因子數自動生成 CFA 模型
  • 後半跑 CFA 驗證前半 EFA 得到的結構
• 適合探索 + 驗證同一份資料的完整流程

Output Location

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

• fetched_data.csv：原始資料快照
• FactorAnalysis_Report.docx：Word 報告
• scree_plot.png / factor_loadings_heatmap.png / path_diagram.png：中間圖表

Workflow (SOP)

1. 數據獲取: data_fetcher.py 驗證所有 --items 存在且為數值型；listwise 刪除含缺失值的列（並記錄丟棄筆數）。
2. 統計執行: r_executor.py 依 mode 分派到對應 R body（psych::fa 或 lavaan::cfa）。
3. Word 生成: word_generator.py 動態組裝章節：
   • efa: 適當性檢驗 → 因子數決定 → 碎石圖 → 因子負荷表 → 共同性表 → 因子相關矩陣 → 結論
   • cfa: 模型設定 → 配適度指標 → 參數估計表 → 信度分析 → 修正指數 → 路徑圖 → 結論
   • both: EFA 章節 + CFA 章節 + 交叉驗證結論
4. 交付: .docx 落地在 output-dir。

Constraints

• 所有數值結果保留 3 位小數（因子負荷慣例；由 templates/word_styles.json 的 numeric_precision 控制）。
• 因子負荷 |λ|<0.3 在報告表格中以灰色顯示（低於慣例閾值）
• CFA 配適度指標自動判定：CFI/TLI ≥0.95 (優) / ≥0.90 (可)；RMSEA ≤0.06 (優) / ≤0.08 (可)；SRMR ≤0.08 (可)
• 樣式集中於 templates/word_styles.json
• Listwise deletion 記入報告

Dependencies

• Python 3.10+: pandas sqlalchemy python-docx openpyxl pyhive thrift thrift-sasl pure-sasl
• R 4.x:
  • 必要: ggplot2 jsonlite psych lavaan GPArotation
  • 可選: semTools (McDonald's ω, 額外配適度), semPlot (路徑圖), showtext sysfonts (CJK)