Regression Analytics

Skill: regression-analytics

迴歸建模與 Word 報告匯出（線性迴歸 / Logistic 迴歸 + 完整診斷）。

Metadata

• Description: 對數據執行迴歸分析，自動診斷模型假設（正態性、方差齊性、多重共線性、離群值/影響點），輸出係數表、模型指標、診斷圖，交付 Word 報告。
• Version: 1.0.0
• Entrypoint: orchestrator.py（CLI: --source {local,sql,hadoop} + --analysis {linear,logistic} + --y <column> + --x <cols> + --output-dir）
• Related: 假設檢驗（t-test/ANOVA/相關性）請用 advanced-data-analytics skill。

Analysis Modes

1. linear — 線性迴歸 (OLS)

• 輸入: 一個 y 欄位（連續數值）+ 一個或多個 predictor 欄位
• 模型: y ~ x1 + x2 + ...
• 主要輸出:
  • 係數表: β 估計、標準誤、t 值、p 值、95% CI（每個 predictor）
  • 模型指標: R²、Adjusted R²、F 統計量、殘差標準誤、AIC、BIC
• 診斷（自動全跑）:
  • 殘差正態性: Shapiro-Wilk on 殘差
  • 異方差: Breusch-Pagan Test（lmtest）
  • 獨立性: Durbin-Watson Test（car）
  • 多重共線性: VIF（car）—— predictor ≥2 時觸發；VIF > 10 標記警告
  • 離群值/影響點: Cook's Distance（標記 D > 4/n 的觀測）
• 可視化:
  • Q-Q plot（殘差正態性）
  • Residuals vs Fitted（線性 + 異方差）
  • Scale-Location（同方差性）
  • Cook's Distance 條狀圖

2. logistic — 二元 Logistic 迴歸

• 輸入: 一個 y 欄位（0/1 或兩類別）+ 一個或多個 predictor 欄位
• 模型: logit(P(y=1)) ~ x1 + x2 + ... (family = binomial)
• 主要輸出:
  • 係數表: β 估計、Std Err、z 值、p 值、Odds Ratio（e^β）+ 95% CI
  • 模型指標: Null/Residual Deviance、AIC、Nagelkerke R²、混淆矩陣、Accuracy、AUC
• 診斷:
  • 配適度: Hosmer-Lemeshow Test（如 ResourceSelection 可用；否則跳過並註記）
  • 多重共線性: VIF（同 linear）
  • 影響點: dfbeta / Cook's Distance
• 可視化:
  • ROC 曲線 + AUC
  • Predicted probability distribution by class
  • Coefficient forest plot（Odds Ratio + CI）

Output Location

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

• fetched_data.csv：原始資料快照
• Regression_Report.docx：Word 報告
• （中間圖表由 R 產生於 tmp_data/，最終嵌入 docx）

可用 --output-dir <path> 覆寫；建議每次不同分析指定子目錄避免覆蓋。

Workflow (SOP)

1. 數據獲取: data_fetcher.py 拉取 → fetched_data.csv，校驗 y 與所有 --x 指定欄位存在。
2. 迴歸執行: r_executor.py 呼叫 lm() 或 glm(family=binomial)，跑完診斷 + 繪 4 張圖 → 匯出 JSON。
3. Word 生成: word_generator.py 動態組裝章節：
   • 模型摘要（公式、n、模型指標表）
   • 係數表（含顯著性標記）
   • 診斷結果表 + 各檢驗判定（PASS/警告）
   • 4 張診斷圖（linear）或 ROC + forest plot（logistic）
   • 結論與建議（自動根據診斷結果生成，例如「殘差不正態，建議考慮 log 轉換或 GLM」）
4. 交付: .docx 落地在 output-dir。

Constraints

• 所有數值結果保留 4 位小數（templates/word_styles.json 的 numeric_precision 控制）。
• Word 報告有清晰層級 + 圖表編號 + 標題；樣式集中於 templates。
• Predictor 欄位若為類別型（字串），R 自動處理成 factor + dummy 編碼；報告中會標出「參考類別」。
• 缺失值：任一列缺 y 或任一 --x 值 → listwise deletion（並在報告中記錄丟棄筆數）。

Dependencies

• Python 3.10+: pandas sqlalchemy python-docx openpyxl pyhive thrift thrift-sasl pure-sasl
• R 4.x（Rscript 需在 PATH）:
  • 必要: ggplot2 jsonlite car lmtest broom
  • 可選: pROC（logistic ROC/AUC）、ResourceSelection（Hosmer-Lemeshow）、showtext sysfonts（中文字型）
  • 可選套件缺失時對應功能靜默降級並在報告中註記。