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
- ANOVA 預設 Tukey HSD(family-wise 校正);亦可
- 效應量: Cohen's d / rank-biserial r / η² / ε²
2. paired — 配對/重複測量
- 輸入(擇一):
- A) wide format:
value_pre+value_post - B) long format:
subject_id+condition+value
- A) wide format:
- 決策樹(對「差值」跑 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)
- A) tidy:
- 變體(
--chi2-variant):auto(預設):任一格期望值 <5 → 自動降級為 Fisher's Exact Test,否則 Chi-squaremcnemar:強制 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)
- 數據獲取:
data_fetcher.py拉取數據 →fetched_data.csv,依 analysis_type 校驗欄位契約與方差。 - 統計執行:
r_executor.py依 analysis_type 分派到對應 R body 模板,執行前置檢驗 + 主檢驗 + 效應量 + 繪圖。 - Word 生成:
word_generator.py依 analysis_type 動態組裝章節:auto兩組: 前置 → 核心 → 圖 → 結論auto多組: 前置 → 核心 → 事後 → 圖 → 結論paired: 前置 → 核心 → 配對差值診斷 → 圖 → 結論chi2: 核心 → 列聯表+診斷 → 圖 → 結論(跳過正態檢驗)correlation: 前置 → 核心 → 相關性診斷(CI/r²/Kendall τ)→ 圖 → 結論
- 交付:
.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 sysfontsoutliers(Grubbs)、pwr(power)、showtext/sysfonts(中文字型) 皆可選;缺失時對應診斷/字型會自動略過或降級