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 (中文字型) 皆可選；缺失時對應診斷/字型會自動略過或降級