Survival Analysis

Skill: survival-analysis

生存分析 (Survival Analysis) 與 Word 報告匯出。

Metadata

• Description: 執行 Kaplan-Meier 非參數估計、Log-rank 組別比較、Cox 比例風險迴歸 (含 PH 假設檢驗)、Schoenfeld 殘差診斷；輸出生存曲線、風險比森林圖、累積事件圖。
• Version: 1.0.0
• Entrypoint: orchestrator.py（CLI: --source {local,sql,hadoop} + --time <col> + --event <col> + --groups <cols> + --covariates <cols> + --analysis {km,cox,both}）
• Related:
  • 假設檢驗：advanced-data-analytics
  • 迴歸建模（線性/Logistic）：regression-analytics
  • 多因子 ANOVA：factorial-anova

資料規格

生存分析的資料每一列代表一個觀測對象，需要以下欄位：

審查 (Censoring) 的直覺：觀察截止時該對象「還沒發生事件」的情況，例如研究結束時仍存活、失聯、退出研究。生存分析的核心就是要正確利用這些不完整的資料。

Analysis Modes

1. km — Kaplan-Meier 非參數估計

• 輸入: --time + --event（+ 可選 --groups）
• 輸出:
  • 生存函數 S(t) 表: 各時間點的估計生存率 + 95% CI
  • 中位生存時間 (median survival) + 95% CI
  • 限制平均生存時間 (RMST, Restricted Mean Survival Time)
  • 若有 --groups：Log-rank 檢驗 (survdiff) → χ² + p 值 + 各組別對比
  • Kaplan-Meier 曲線圖 + Risk Table (每時間點還在觀察的人數)

2. cox — Cox 比例風險迴歸

• 輸入: --time + --event + --covariates（可與 --groups 混用）
• 輸出:
  • 係數表: 每個 covariate 的 β 估計、SE、z、p、Hazard Ratio (HR) + 95% CI
  • 模型指標: Concordance (C-index)、Likelihood ratio test、Wald test、Score test
  • 比例風險假設檢驗 (cox.zph, Schoenfeld residuals) → 每個變量的檢驗 p 值 + Global test
  • 森林圖（HR + 95% CI）
  • Schoenfeld 殘差圖（診斷 PH 假設）

3. both — 依序執行 KM 與 Cox

• KM 部分：--groups 若存在則做組別比較
• Cox 部分：如果 --covariates 為空且有 --groups，將 --groups 當作 covariate 使用

Output Location

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

• fetched_data.csv：資料快照
• Survival_Report.docx：Word 報告
• km_curve.png：Kaplan-Meier 曲線
• cox_forest.png：Cox 森林圖
• schoenfeld.png：PH 假設殘差圖

Workflow (SOP)

1. fetch: schema 校驗（time > 0、event ∈ {0, 1}、groups 至少 2 levels 等）
2. execute: R 端 survfit (KM) / coxph (Cox) / cox.zph (PH check)
3. render: 依 analysis mode 動態組裝 Word 章節
4. 交付: .docx 落地在 output-dir

Constraints

• time 必須 > 0；不允許負值或 0
• event 僅接受 0/1（或 TRUE/FALSE）
• Cox 迴歸的類別 covariate 自動 to factor + dummy encoding
• Listwise deletion：任一必需欄位為 NA 的列丟棄，記入報告
• 中位生存時間若在觀察期內未達到（>50% 存活），顯示為 "not reached"
• 事件數 <10 時強烈警告（Cox 統計功效不足）

Dependencies

• Python 3.10+: pandas sqlalchemy python-docx openpyxl pyhive thrift thrift-sasl pure-sasl
• R 4.x:
  • 必要: ggplot2 jsonlite survival survminer broom
  • 可選: showtext sysfonts (CJK 字型)