# Survival Analysis

> Skill: survival-analysis

- Skill: `kaito41418-ux/survival-analysis` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add kaito41418-ux/survival-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kaito41418-ux/survival-analysis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kaito41418-ux (https://skillmd.com/u/kaito41418-ux)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kaito41418-ux/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`

## 資料規格

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

| 欄位 | 型別 | 說明 |
|---|---|---|
| `--time` | 數值 | 觀測時間（距離起始的時間單位，例如天/週/月） |
| `--event` | 0/1 | 事件狀態：**1 = 事件發生**（死亡/流失/失效），**0 = 審查** (censored) |
| `--groups`（可選） | 類別 | 分組變量（例如治療組別、性別）；用於 KM 曲線分組與 Log-rank |
| `--covariates`（可選） | 數值或類別 | Cox 迴歸的共變量（年齡、劑量、其他 predictor） |

**審查 (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 字型)