scikit-survival

scikit-survival

适用范围

将此技能用于 scikit-survival 0.28.0 工作流，包括：

• 右删失结构化结局；
• Cox PH、Coxnet、IPC ridge、生存树、随机森林、梯度提升和 SVM；
• 区分度、预测误差、面向校准的检查和时变预测；
• 存在竞争风险时的非参数累积发生率；
• scikit-learn 管道、嵌套模型选择和可复现报告。

scikit-survival 主要用于对右删失结局建模。其内置的竞争风险支持仅提供非参数累积发生率；它不提供 Fine-Gray 回归。不要将模型输出表述为临床建议、因果证据或临床效用的证明。

当前版本和安装

已于 2026-07-23 验证：

• 最新稳定版：scikit-survival 0.28.0，于 2026-07-05 发布。
• Python：3.11 或更高版本；PyPI wheel 支持 Linux x86-64、macOS x86-64/ARM64 和 Windows x86-64 上的 CPython 3.11-3.14。
• 运行时版本要求：NumPy >=2.0.0、pandas >=2.2.0、SciPy >=1.13.0、scikit-learn >=1.9.0,<1.10、OSQP >=1.0.2、narwhals >=2.0.1。
• 0.28 通过 narwhals 增加了对 pandas/Polars 的估计器支持，并从 GradientBoostingSurvivalAnalysis 中移除了 criterion。

创建隔离环境并安装经过测试的快照：

uv venv --python 3.11
source .venv/bin/activate
uv pip install \
  "scikit-survival==0.28.0" \
  "scikit-learn==1.9.0" \
  "numpy==2.4.6" \
  "pandas==3.0.5" \
  "scipy==1.17.1" \
  "ecos==2.0.14" \
  "osqp==1.1.3" \
  "joblib==1.5.3" \
  "numexpr==2.14.2" \
  "narwhals==2.24.0"

建议优先使用二进制 wheel。从源代码构建需要 C/C++ 编译器；OSQP 也可能需要 CMake。此技能采用 MIT 许可证；上游 scikit-survival 包采用 GPL-3.0-or-later 许可证，因此重新分发前请检查上游许可证。

不可妥协的工作流

1. 定义估计目标和事件编码。 确定目标是全事件生存、特定原因风险，还是特定原因累积发生率。
2. 验证结局。 标准估计器需要一个包含两个字段的结构化数组：第一个字段为布尔型事件，第二个字段为观测时间。竞争风险 CIF 则需要单独的整数事件向量：0=删失，1..K=事件原因。
3. 在学习预处理前拆分数据。 在拆分前，绝不要使用所有行来拟合填补器、编码器、缩放器、特征选择器或 alpha 值。
4. 在管道内拟合预处理。 必须仅使用训练折中的状态处理未知类别和缺失值。
5. 调参时不要重复使用评估数据。 报告经过调参的交叉验证性能时，请使用嵌套 CV，或预留一个完全未使用的最终留出集。
6. 在训练数据上拟合删失分布。 IPCW 一致性、动态 AUC 和 Brier 指标接收 survival_train，绝不能接收合并后的训练集和测试集结局。
7. 限制评估时间。 使用严格递增的时间网格，确保其位于测试集随访范围内，并低于训练数据支持范围的末端，且估计的删失生存率保持为正。
8. 让预测与指标相匹配。 一致性和动态 AUC 使用数值越高风险越高的分数。Brier 指标使用形状为 (n_test, n_times) 的生存概率，而非风险分数或未经评估的阶梯函数。
9. 明确处理竞争事件原因。 标准生存概率和 CIF 回答的是不同问题。对竞争事件进行删失处理时，绝不要用 1 - Kaplan-Meier 估计特定事件的概率。
10. 报告局限性。 区分区分度、校准、预测误差和累积发生率。它们都不能单独证明决策效用或临床效用。

结局构造

from sksurv.util import Surv

y = Surv.from_arrays(event=event_bool, time=observed_time)
# Equivalent for pandas or Polars:
y = Surv.from_dataframe("event", "time", frame)

第一个字段为布尔型（True=发生事件，False=右删失）；第二个字段为浮点型时间。字段名可以不同，但字段顺序和含义不能变。加载自定义数据或竞争风险数据前，请使用 references/data-handling.md。

防止数据泄漏的管道

from sklearn.compose import ColumnTransformer
from sklearn.impute import SimpleImputer
from sklearn.model_selection import train_test_split
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import OneHotEncoder, StandardScaler
from sksurv.linear_model import CoxPHSurvivalAnalysis

X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.25, stratify=y["event"], random_state=20260723
)

preprocess = ColumnTransformer(
    [
        ("num", make_pipeline(SimpleImputer(strategy="median"), StandardScaler()), numeric),
        (
            "cat",
            make_pipeline(
                SimpleImputer(strategy="most_frequent"),
                OneHotEncoder(handle_unknown="ignore", drop="first", sparse_output=False),
            ),
            categorical,
        ),
    ],
    sparse_threshold=0.0,
)
model = make_pipeline(preprocess, CoxPHSurvivalAnalysis(alpha=0.1, ties="efron"))
model.fit(X_train, y_train)
risk = model.predict(X_test)

在每次需要学习的转换之前先拆分数据。对于重复记录或分组记录，请使用考虑分组的拆分方法；对于时序部署，请使用遵循时间顺序的拆分方法。

模型选择

• CoxPHSurvivalAnalysis：在比例风险假设下提供可解释的对数风险系数；alpha 表示岭收缩，ties 为 "breslow" 或 "efron"。
• CoxnetSurvivalAnalysis：适用于高维数据的 LASSO／弹性网路径。l1_ratio 取值范围为 (0, 1]；请求生存函数或累积风险函数前，先设置 fit_baseline_model=True。
• IPCRidge：IPC 加权的岭 AFT 模型；预测结果采用时间／对数时间尺度，而非 Cox 风险评分。
• RandomSurvivalForest / ExtraSurvivalTrees：用于非线性生存和累积风险预测；使用置换重要性，而非不纯度重要性。
• GradientBoostingSurvivalAnalysis：使用 "coxph"、"squared" 或 "ipcwls" 损失的树提升模型。criterion 已在 0.28 中移除。
• ComponentwiseGradientBoostingSurvivalAnalysis：稀疏线性逐分量提升模型。
• FastSurvivalSVM / FastKernelSurvivalSVM：排序或回归目标。只有 rank_ratio=1 会直接返回值越高、风险越大的评分；SVM 不会生成 Brier 指标所需的生存概率。

解读系数或预测结果前，请先阅读相应模型的参考文档：references/cox-models.md、references/ensemble-models.md 或 references/svm-models.md。

预测与指标约定

import numpy as np
from sksurv.metrics import (
    brier_score,
    concordance_index_ipcw,
    cumulative_dynamic_auc,
    integrated_brier_score,
)

risk = model.predict(X_test)  # (n_test,), higher means higher event risk
uno_c = concordance_index_ipcw(y_train, y_test, risk, tau=times[-1])[0]
auc_t, mean_auc = cumulative_dynamic_auc(y_train, y_test, risk, times)

surv_fns = model.predict_survival_function(X_test)
surv_prob = np.vstack([fn(times) for fn in surv_fns])  # (n_test, n_times)
_, brier_t = brier_score(y_train, y_test, surv_prob, times)
ibs = integrated_brier_score(y_train, y_test, surv_prob, times)

• Harrell C 和 Uno C 衡量的是排序区分能力，而非校准。
• 累积／动态 AUC 衡量选定时间点的区分能力，接受一维或随时间变化的二维风险评分；不接受生存概率。
• Brier 分数是经过删失加权的概率误差，反映区分能力和校准情况。它本身并不是校准曲线。
• 校准需要在独立数据上，针对特定时间点检查预测值与观察值。scikit-survival 0.28 没有专用的校准曲线 API。

有关假设、主要文献、安全的时间网格构建方式和评分器包装器，请参阅 references/evaluation-metrics.md。

管道、元数据路由与调参

普通的 Pipeline.fit(X, y) 无需设置元数据路由。像 as_concordance_index_ipcw_scorer 这样的指标包装器是估计器包装器，而不是 scoring= 可调用对象：

from sklearn.model_selection import GridSearchCV
from sksurv.metrics import as_concordance_index_ipcw_scorer

wrapped = as_concordance_index_ipcw_scorer(model, tau=tau)
search = GridSearchCV(
    wrapped,
    {"estimator__coxphsurvivalanalysis__alpha": [0.01, 0.1, 1.0]},
    cv=inner_splits,
)

该包装器会根据每个拟合折叠学习删失分布。给包装后的参数添加 estimator__ 前缀。只有在通过元估计器传递额外元数据时，才启用 scikit-learn 元数据路由。例如，只有在通过 sklearn.set_config(enable_metadata_routing=True) 路由 alpha 预测参数时，Coxnet 的 set_predict_request(alpha=True) 才有作用。

内层调参后，使用外层交叉验证循环获得无偏的交叉验证性能估计。不要在相同的折叠上选择参数并报告性能，还把结果当作外部评估。

竞争风险

from sksurv.nonparametric import cumulative_incidence_competing_risks

# status: integer array, 0=censored, 1..K=mutually exclusive causes
time, cif = cumulative_incidence_competing_risks(status, observed_time)
total_cif = cif[0]
cause_1_cif = cif[1]

cif 的形状为 (K + 1, n_times)；第 0 行是总风险，第 1 至 K 行是特定原因的累积发生率。特定原因 Cox 模型将其他原因视为删失，以估计特定原因风险，但单个此类模型的 1 - survival 并不是特定原因的 CIF。请参阅 references/competing-risks.md。

附带的本地 CLI

未提供输入时，所有辅助工具都会使用确定性的合成数据。它们不会发出网络请求，会拒绝 URL 和符号链接，会限制文件、行和特征的数量，会避免不安全的 pickle 加载，并会延迟导入科学计算软件包。

python skills/scikit-survival/scripts/validate_survival_csv.py --help
python skills/scikit-survival/scripts/train_survival_model.py --help
python skills/scikit-survival/scripts/evaluate_survival_metrics.py --help
python skills/scikit-survival/scripts/competing_risk_cif.py --help
python skills/scikit-survival/scripts/model_report.py --help

典型的本地工作流程：

python skills/scikit-survival/scripts/validate_survival_csv.py \
  --input data.csv --event-column event --time-column time \
  --feature-columns age,group,measurement --structured-output outcome.npy

python skills/scikit-survival/scripts/train_survival_model.py \
  --input data.csv --event-column event --time-column time \
  --numeric-columns age,measurement --categorical-columns group \
  --model coxph --tune --prediction-output predictions.npz \
  --output training-summary.json

python skills/scikit-survival/scripts/evaluate_survival_metrics.py \
  --input predictions.npz --output metrics-summary.json

python skills/scikit-survival/scripts/model_report.py \
  --training-summary training-summary.json \
  --metrics-summary metrics-summary.json --output model-report.md

只能使用已去标识化且经授权的本地数据。附带的测试仅包含合成记录，不含患者数据或 PHI。

安全审查

SECURITY.md 曾声称此技能包含名为 sklearn.py 和 sksurv.py 的包遮蔽文件。2026-07-23 的清点确认这些文件并不存在；该说法是分析器误报。本次更新仅添加了名称描述明确的辅助文件，不包含遮蔽模块，不读取环境，也不发起网络调用。

切勿将项目脚本命名为与导入包相同的名称（包括 sklearn.py、sksurv.py、numpy.py 或 pandas.py），因为 Python 可能会导入本地文件，而不是已安装的库。执行从不可信来源复制的示例之前，请检查工作目录。

参考文件

• references/data-handling.md — 结构化数组、数据集、架构验证、pandas/Polars 预处理和防止数据泄漏的划分。
• references/cox-models.md — Cox PH、Coxnet、IPCRidge、假设和调参。
• references/ensemble-models.md — 森林、树、提升、预测和置换重要性。
• references/svm-models.md — SVM 目标、预测方向、缩放、核函数和局限。
• references/evaluation-metrics.md — 指标输入、删失假设、时间网格、校准、嵌套交叉验证和主要文献。
• references/competing-risks.md — 整数事件编码、CIF API、内置数据集、原因特异性风险和不受支持的 Fine-Gray 回归。

日期明确的来源

官方 API 和兼容性来源，核查日期：2026-07-23：

• PyPI 0.28.0 — 发布于 2026-07-05。
• GitHub v0.28.0 release — 发布于 2026-07-05。
• 0.28 release notes。
• 安装指南。
• 稳定版用户指南。
• 稳定版 API 参考。

Agent 操作流程

1. 检查环境。 确认 Python 环境和库版本（python -c "import pkg; print(pkg.__version__)"），并检查数据的形状、类型和缺失值。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应先询问，切勿猜测。
3. 先运行小规模版本。 先用样本或单个折运行，并检查运行时间和内存。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 使用留出数据、固定随机种子和适当指标；检查是否存在数据泄漏；报告不确定性（置信区间、跨随机种子的标准差）。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些内容仍不确定。

如果发生这种情况	这样做
内存不足或运行非常缓慢	对数据抽样、使用分块或惰性计算，或缩小模型规模，并告知用户做了哪些更改。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅该已安装版本自己的文档（help()、--help、官方文档），调整做法并告知用户。切勿编造 API。
必需的输入、标识符或参数含义不明确	询问用户，或在运行前明确说明所采用的假设。

诚信规则

• 切勿捏造结果、参数、标识符、引用或统计数据。如果无法运行或验证某项内容，请直言说明。
• 切勿报告本次会话中未计算的指标；应展示生成每个数值的代码路径。
• 此处与特定版本相关的细节可能已过时：请根据已安装版本的官方文档进行确认。
• 对于涉及费用、占用共享 GPU 或云配额、接触个人或患者数据，或无法撤销的操作，必须先征得同意。