scikit-survival
Builds, evaluates, and audits right-censored survival analysis workflows with scikit-survival (sksurv): Cox PH, Coxnet, IPC ridge, survival trees, forests, boosting, and SVMs, plus nonparametric cumulative incidence for competing risks. Covers leakage-safe scikit-learn pipelines, nested CV, and censoring-aware metrics. Use when fitting survival models on time-to-event data, building structured outcome arrays, computing IPCW concordance, dynamic AUC, or Brier scores, estimating cause-specific cumulative incidence, or tuning models without leakage. Not for Fine-Gray regression, which scikit-survival does not provide.
Install this skill
Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.
npx skills add KalarisLabs/research-agent-skills --skill scikit-survivaluvx research-agent-skills install scikit-survivalDocumentation & Instructions
scikit-survival
Scope
Use this skill for scikit-survival 0.28.0 workflows involving:
- right-censored structured outcomes;
- Cox PH, Coxnet, IPC ridge, survival trees, forests, boosting, and SVMs;
- discrimination, prediction error, calibration-oriented checks, and time-dependent prediction;
- nonparametric cumulative incidence with competing risks;
- scikit-learn pipelines, nested model selection, and reproducible reports.
scikit-survival primarily models right-censored outcomes. Its built-in competing-risk support is nonparametric cumulative incidence; it does not provide Fine-Gray regression. Do not present model output as clinical advice, causal evidence, or proof of clinical utility.
Current release and installation
Verified 2026-07-23:
- Latest stable: scikit-survival 0.28.0, released 2026-07-05.
- Python: 3.11 or later; PyPI wheels cover CPython 3.11-3.14 on Linux x86-64, macOS x86-64/ARM64, and Windows x86-64.
- Runtime bounds: 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 adds pandas/Polars estimator support through narwhals and removes
criterionfromGradientBoostingSurvivalAnalysis.
Create an isolated environment and install the tested snapshot:
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"
Binary wheels are preferred. A source build requires a C/C++ compiler; OSQP may also require CMake. This skill is MIT-licensed; the upstream scikit-survival package is GPL-3.0-or-later, so review upstream licensing before redistribution.
Non-negotiable workflow
- Define the estimand and event coding. Decide whether the target is all-event survival, cause-specific hazard, or cause-specific cumulative incidence.
- Validate outcomes. Standard estimators need a two-field structured array: boolean event first, observed time second. Competing-risk CIF instead needs a separate integer event vector: 0=censored, 1..K=causes.
- Split before learned preprocessing. Never fit imputers, encoders, scalers, feature selectors, or alpha choices on all rows before splitting.
- Fit preprocessing inside a pipeline. Unknown categories and missingness must be handled using training-fold state only.
- Tune without reusing evaluation data. Use nested CV when reporting cross-validated tuned performance, or reserve a truly untouched final holdout.
- Fit censoring distributions on training data. IPCW concordance, dynamic AUC,
and Brier metrics receive
survival_train, never a pooled train+test outcome. - Restrict evaluation times. Use a strictly increasing grid inside test follow-up and below the end of training support where the estimated censoring survival remains positive.
- Match predictions to metrics. Concordance/dynamic AUC consume higher-is-riskier
scores. Brier metrics consume survival probabilities with shape
(n_test, n_times), not risk scores or unevaluated step functions. - Handle competing causes explicitly. Standard survival probabilities and CIFs
answer different questions. Never estimate event-specific probability with
1 - Kaplan-Meierwhile censoring competing events. - Report limits. Separate discrimination, calibration, prediction error, and cumulative incidence. None alone establishes decision or clinical utility.
Outcome construction
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)
The first field is boolean (True=event, False=right-censored); the second is
floating-point time. Field names may vary, but field order and meaning may not.
Use references/data-handling.md before loading custom or competing-risk data.
Leakage-safe pipeline
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)
The split precedes every learned transformation. For repeated or grouped records, use a group-aware split; for temporal deployment, use a time-respecting split.
Model choice
CoxPHSurvivalAnalysis: interpretable log-hazard coefficients under proportional hazards;alphais ridge shrinkage andtiesis"breslow"or"efron".CoxnetSurvivalAnalysis: LASSO/elastic-net path for high-dimensional data.l1_ratiois in(0, 1]; usefit_baseline_model=Truebefore requesting survival or cumulative-hazard functions.IPCRidge: IPC-weighted ridge AFT model; prediction is on a time/log-time scale, not a Cox risk score.RandomSurvivalForest/ExtraSurvivalTrees: nonlinear survival and cumulative hazard predictions; use permutation importance, not impurity importance.GradientBoostingSurvivalAnalysis: tree boosting with"coxph","squared", or"ipcwls"loss.criterionwas removed in 0.28.ComponentwiseGradientBoostingSurvivalAnalysis: sparse linear componentwise boosting.FastSurvivalSVM/FastKernelSurvivalSVM: ranking or regression objectives. Onlyrank_ratio=1directly returns higher-is-riskier scores; SVMs do not yield survival probabilities for Brier metrics.
Read the model-specific reference before interpreting coefficients or predictions:
references/cox-models.md, references/ensemble-models.md, or
references/svm-models.md.
Prediction and metric contracts
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 and Uno C measure rank discrimination, not calibration.
- Cumulative/dynamic AUC measures discrimination at selected horizons and accepts 1D or time-dependent 2D risk scores; it rejects survival probabilities.
- Brier score is censoring-weighted probability error and reflects both discrimination and calibration. It is not a standalone calibration curve.
- Calibration requires horizon-specific predicted-versus-observed checks on independent data. scikit-survival 0.28 has no dedicated calibration-curve API.
See references/evaluation-metrics.md for assumptions, primary literature, safe
time-grid construction, and scorer wrappers.
Pipelines, metadata routing, and tuning
Ordinary Pipeline.fit(X, y) needs no metadata-routing setup. Metric wrappers such
as as_concordance_index_ipcw_scorer are estimator wrappers, not scoring=
callables:
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,
)
The wrapper learns the censoring distribution from each fit fold. Prefix wrapped
parameters with estimator__. Enable scikit-learn metadata routing only when
passing extra metadata through a meta-estimator. For example, Coxnet's
set_predict_request(alpha=True) matters only when routing the alpha prediction
argument with sklearn.set_config(enable_metadata_routing=True).
Use an outer CV loop for an unbiased CV performance estimate after inner tuning. Do not select parameters and report performance from the same folds as if external.
Competing risks
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 has shape (K + 1, n_times); row 0 is total risk and rows 1..K are
cause-specific cumulative incidence. Cause-specific Cox models treat other causes
as censored to estimate cause-specific hazards, but one such model's
1 - survival is not the cause-specific CIF. See references/competing-risks.md.
Bundled local CLIs
All helpers use deterministic synthetic data when no input is given. They make no network calls, reject URLs and symlinks, bound files/rows/features, avoid unsafe pickle loading, and lazily import scientific packages.
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
Typical local flow:
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
Use only de-identified, authorized local data. The bundled tests contain synthetic records only and no patient data or PHI.
Security triage
SECURITY.md previously claimed this skill bundled package-shadowing files named
sklearn.py and sksurv.py. The 2026-07-23 inventory confirmed those files did
not exist; the claim was a phantom analyzer finding. This refresh adds only
descriptively named helpers and no shadow modules, environment reads, or network
calls.
Never name a project script after an imported package (including sklearn.py,
sksurv.py, numpy.py, or pandas.py), because Python may import the local file
instead of the installed library. Inspect the working directory before executing
examples copied from untrusted sources.
Reference files
references/data-handling.md— structured arrays, datasets, schema validation, pandas/Polars preprocessing, and leakage-safe splitting.references/cox-models.md— Cox PH, Coxnet, IPCRidge, assumptions, and tuning.references/ensemble-models.md— forests, trees, boosting, predictions, and permutation importance.references/svm-models.md— SVM objectives, prediction direction, scaling, kernels, and limitations.references/evaluation-metrics.md— metric inputs, censoring assumptions, time grids, calibration, nested CV, and primary literature.references/competing-risks.md— integer event coding, CIF API, built-in datasets, cause-specific hazards, and unsupported Fine-Gray regression.
Dated sources
Official API and compatibility sources, checked 2026-07-23:
- PyPI 0.28.0 — released 2026-07-05.
- GitHub v0.28.0 release — published 2026-07-05.
- 0.28 release notes.
- Installation guide.
- Stable user guide.
- Stable API reference.
Agent operating procedure
- Check the environment. Confirm the Python environment and library versions (
python -c "import pkg; print(pkg.__version__)") and inspect the data's shape, types and missing values. - Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
- Run a small version first. Run on a sample or a single fold first and check runtime and memory.
- Execute the full task using the instructions and references above.
- Validate the result. Use held-out data, fixed random seeds and appropriate metrics; check for leakage; report uncertainty (CIs, std over seeds).
- Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.
| If this happens | Do this |
|---|---|
| Out-of-memory or very slow execution | Subsample, use chunked or lazy computation, or reduce model size, and tell the user what changed. |
| A function, flag or endpoint in these instructions is missing in the installed version | Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API. |
| A required input, identifier or parameter is ambiguous | Ask the user, or state the assumption explicitly before running. |
Integrity rules
- Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
- Never report a metric you did not compute in this session; show the code path that produced every number.
- Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
- Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.
Trigger Prompts & Evaluation Corpus
These evaluation prompts test that the agent correctly selects scikit-survival for relevant tasks and leaves it out for near misses.
Should trigger (3)
- should trigger
“How do I get Uno's C-index for my Coxnet model in sksurv? I keep getting an error about survival_train.”
expects Explains that concordance_index_ipcw takes the training structured array (survival_train) first, then test outcome, and higher-is-riskier test risk scores. The censoring distribution must come from training data only, not pooled train+test. Notes that tau must stay within test follow-up and below the end of training support.
- should trigger
“I have clinic_outcomes.csv with columns age, sex, creatinine, stage, months_to_relapse, relapsed (0/1), and about 8% missing creatinine. I want to compare a random survival forest and a penalized Cox model, tune hyperparameters, and report an honest cross-validated integrated Brier score and time-dependent AUC. Currently I impute and scale the whole table first, then run GridSearchCV. Can you fix this workflow?”
expects Identifies the leakage from imputing and scaling before the split and tuning on the same folds used for reporting. Builds the structured array with boolean event first and time second. Puts imputer, encoder and scaler in a Pipeline fit on training folds only, and uses nested CV or an untouched holdout. Passes survival_train to the Brier and AUC metrics, uses a strictly increasing time grid inside test follow-up, and feeds survival probabilities of shape (n_test, n_times) to Brier and risk scores to AUC. Caveats that none of these metrics alone shows clinical utility.
- should trigger
“My transplant cohort has patients who either relapse, die without relapse, or are censored at last follow-up. I want to estimate the probability of relapse by 3 years without treating death as just censoring. What should I do in Python?”
expects Recommends nonparametric cumulative incidence with competing risks, using a separate integer event vector (0=censored, 1=relapse, 2=death), rather than 1 minus Kaplan-Meier with deaths censored. Explains the cif output shape (K+1, n_times) and that row 1 is relapse incidence at the chosen time. Mentions that Fine-Gray regression is not available in scikit-survival, and that cause-specific Cox models answer a different question.
Near misses (2)
- near miss
“Can you fit a Fine-Gray subdistribution hazard regression for my competing-risks data with covariates and give me the subdistribution hazard ratios?”
expects Should not use this skill's workflow to produce Fine-Gray output, since scikit-survival does not provide Fine-Gray regression. A better answer points to R (cmprsk or tidycmprsk) or another package that implements it.
- near miss
“I have RNA-seq counts for treated vs control mice and want to run differential expression with DESeq2 and make a volcano plot.”
expects Recognizes this is a bulk RNA-seq differential expression task unrelated to survival modelling. It should not use the scikit-survival skill. It should use a DESeq2 or RNA-seq analysis workflow if one is available.