# Factor Analysis

> Skill: factor-analysis

- Skill: `kaito41418-ux/factor-analysis` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add kaito41418-ux/factor-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kaito41418-ux/factor-analysis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kaito41418-ux (https://skillmd.com/u/kaito41418-ux)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kaito41418-ux/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)