# Advanced Data Analytics

> Skill: advanced-data-analytics

- Skill: `kaito41418-ux/advanced-data-analytics` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add kaito41418-ux/advanced-data-analytics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kaito41418-ux/advanced-data-analytics/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: kaito41418-ux (https://skillmd.com/u/kaito41418-ux)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kaito41418-ux/advanced-data-analytics

---


# Skill: advanced-data-analytics

高級數據分析與 Word 報告匯出。

## Metadata
- **Description**: 當用戶需要從多源頭（Hadoop/SQL/本地）獲取數據，進行嚴謹的統計檢驗（含前置驗證、多重矯正、配對/類別/相關性分析），並要求最終交付 Word 格式（.docx）的分析報告時觸發。
- **Version**: 1.6.1
- **Entrypoint**: `orchestrator.py`（CLI: `--source {local,sql,hadoop}` + `--analysis {auto,paired,chi2,correlation}` + 對應模式參數 + `--bootstrap-iter` / `--no-grubbs` / `--no-power` + `--output-dir`）

## Analysis Modes

Skill 依 `--analysis` 分派四種分析路徑；`data_fetcher.py` 會依模式校驗輸入欄位契約。

### 1. `auto` — 獨立樣本比較（預設）
- **輸入**: `group` (類別) + `value` (數值)
- **決策樹**（Shapiro-Wilk 每組獨立、取最保守 p；Levene 手工 F-test on |x−median|）：
  - 兩組：Student t / Welch t / Wilcoxon Rank Sum
  - 多組：One-way ANOVA / Kruskal-Wallis + 事後檢驗
- **事後檢驗**（≥3 組）：
  - ANOVA 預設 **Tukey HSD**（family-wise 校正）；亦可 `pairwise_t`
  - Kruskal-Wallis 預設 **Dunn's Test**；亦可 `pairwise_wilcox`
  - 校正方法可選：`bonferroni` / `BH (FDR，預設)` / `holm` / `none`
- **效應量**: Cohen's d / rank-biserial r / η² / ε²

### 2. `paired` — 配對／重複測量
- **輸入**（擇一）:
  - A) wide format: `value_pre` + `value_post`
  - B) long format: `subject_id` + `condition` + `value`
- **決策樹**（對「差值」跑 Shapiro-Wilk）:
  - 正態：**Paired t-test** → Cohen's dz
  - 非正態：**Wilcoxon Signed-Rank** → matched-pairs rank-biserial r

### 3. `chi2` — 類別型結果
- **輸入**（擇一）:
  - A) tidy: `cat_a` + `cat_b` [+ `count`]
  - B) pre-aggregated 列聯表（第一欄為 row label，其餘為 count）
- **變體**（`--chi2-variant`）:
  - `auto`（預設）：任一格期望值 <5 → 自動降級為 **Fisher's Exact Test**，否則 **Chi-square**
  - `mcnemar`：強制 **McNemar's Test**（配對二元 2×2）
- **效應量**: Cramér's V / phi (2×2) / Odds Ratio + 95% CI (Fisher 2×2) / Discordance Ratio (McNemar)

### 4. `correlation` — 連續變量相關性
- **輸入**: `x` + `y`（兩個數值欄位）
- **主方法**（`--correlation-method`，預設 auto）:
  - auto：兩者正態 → **Pearson r**；否則 → **Spearman ρ**
  - 亦可強制指定 `kendall`
- **穩健校核**: 主方法非 Kendall 時，額外計算 Kendall τ 作為對比
- **附加輸出**: 效應量 95% CI、r² 解釋方差

## Diagnostics (P1)

除主檢驗外，`auto` / `paired` / `correlation` 三種數值模式會自動附上：

- **效應量補強**（`--no-power` 可關閉 power）：
  - **Hedges' g**（僅雙組 t 分支）：Cohen's d 的小樣本校正因子 (Hedges, 1981)
  - **ω² (omega squared)**（僅 ANOVA）：η² 的無偏估計，小樣本更合理
  - **95% Bootstrap CI** for 效應量：預設 1000 次重抽樣，`--bootstrap-iter 0` 可關
  - **Post-hoc power** (`pwr` 套件)：α=0.05 下的檢驗力；報告會標註「充足 (≥0.8) / 邊界 (0.5-0.8) / 不足 (<0.5)」
- **Grubbs 離群值檢定**（`--no-grubbs` 可關閉）：
  - `auto`: 對每組獨立跑
  - `paired`: 對差值跑
  - `correlation`: 對 x、y 各跑
  - 每組 n<7 或 `outliers` 套件缺失時跳過該項；表格內明確標示疑似離群值與判定結果

`chi2` 模式因輸入為類別型，不觸發上述診斷。

## Output Location

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

- `fetched_data.csv`：`data_fetcher.py` 落地的原始資料快照
- `Analysis_Report.docx`：最終 Word 分析報告

可用 `--output-dir <path>` 覆寫；orchestrator 會自動建立不存在的目錄。同一目錄下每次 run 會覆蓋前一次的產物，若要保留歷史請自行改路徑或先移走檔案。批次分析多個 outcome 時建議每次指定不同子目錄（例如 `outcome-temp/count_close/`）。

## Workflow (SOP)
1. **數據獲取**: `data_fetcher.py` 拉取數據 → `fetched_data.csv`，依 analysis_type 校驗欄位契約與方差。
2. **統計執行**: `r_executor.py` 依 analysis_type 分派到對應 R body 模板，執行前置檢驗 + 主檢驗 + 效應量 + 繪圖。
3. **Word 生成**: `word_generator.py` 依 analysis_type 動態組裝章節：
   - `auto` 兩組: 前置 → 核心 → 圖 → 結論
   - `auto` 多組: 前置 → 核心 → 事後 → 圖 → 結論
   - `paired`: 前置 → 核心 → 配對差值診斷 → 圖 → 結論
   - `chi2`: 核心 → 列聯表+診斷 → 圖 → 結論（跳過正態檢驗）
   - `correlation`: 前置 → 核心 → 相關性診斷（CI/r²/Kendall τ）→ 圖 → 結論
4. **交付**: `.docx` 檔案位於 output-dir（預設 `./outcome-temp/Analysis_Report.docx`）。

## Constraints
- 所有數值結果（p 值、統計量、效應量、矯正後 p、CI）寫入 Word 時保留 4 位小數（由 `templates/word_styles.json` 的 `numeric_precision` 控制）。
- Word 報告必須包含清晰的層級結構，圖片下方必須有圖表編號與標題。
- 樣式（字體、色彩、表格 style、圖片寬度）集中定義於 `templates/word_styles.json`，禁止在程式碼中硬編碼。

## Dependencies
- Python 3.10+：`pandas sqlalchemy python-docx openpyxl pyhive thrift thrift-sasl pure-sasl`
- R 4.x（Rscript 需在 PATH），套件：`ggplot2 jsonlite dunn.test outliers pwr showtext sysfonts`
  - `outliers` (Grubbs)、`pwr` (power)、`showtext`/`sysfonts` (中文字型) 皆可選；缺失時對應診斷/字型會自動略過或降級