uv run python; requires scikit-survival >= 0.28 (current as of 2026-09), which needs scikit-learn >= 1.9.\nmetadata:\nskill-author: AlterLab\nversion: \"1.1.0\"\nlast_updated: \"2026-09-23\"scikit-survival is a Python library for survival analysis built on top of scikit-learn. It provides specialized tools for time-to-event analysis, handling the unique challenge of censored data where some observations are only partially known.
\nSurvival analysis aims to establish connections between covariates and the time of an event, accounting for censored records (particularly right-censored data from studies where participants don't experience events during observation periods).
\nUse this skill when:
\n| Scenario | \nUse Instead | \n
|---|---|
| Binary outcome at a fixed follow-up with no censoring (logistic regression, odds ratios) | \nalterlab-statsmodels | \n
| Standard regression or classification with no time-to-event outcome | \nalterlab-scikit-learn | \n
| Writing a clinical decision-support report or biomarker-stratified cohort document with survival curves and hazard ratios | \nalterlab-clinical-decision | \n
scikit-survival is prediction-oriented: CoxPHSurvivalAnalysis returns coefficients but no standard errors, confidence intervals, or p-values. When hazard ratios need inferential reporting, use lifelines' CoxPHFitter or statsmodels' PHReg (statsmodels.duration.hazard_regression).
scikit-survival provides multiple model families, each suited for different scenarios:
\nUse for: Standard survival analysis with interpretable coefficients
\nCoxPHSurvivalAnalysis: Basic Cox modelCoxnetSurvivalAnalysis: Penalized Cox with elastic net for high-dimensional dataIPCRidge: Ridge regression for accelerated failure time modelsSee: references/cox-models.md for detailed guidance on Cox models, regularization, and interpretation
Use for: High predictive performance with complex non-linear relationships
\nRandomSurvivalForest: Robust, non-parametric ensemble methodGradientBoostingSurvivalAnalysis: Tree-based boosting for maximum performanceComponentwiseGradientBoostingSurvivalAnalysis: Linear boosting with feature selectionExtraSurvivalTrees: Extremely randomized trees for additional regularizationSee: references/ensemble-models.md for comprehensive guidance on ensemble methods, hyperparameter tuning, and when to use each model
Use for: Medium-sized datasets with margin-based learning
\nFastSurvivalSVM: Linear SVM optimized for speedFastKernelSurvivalSVM: Kernel SVM for non-linear relationshipsHingeLossSurvivalSVM: SVM with hinge lossClinicalKernelTransform: Specialized kernel for clinical + molecular dataSee: references/svm-models.md for detailed SVM guidance, kernel selection, and hyperparameter tuning
Start\n├─ High-dimensional data (p > n)?\n│ ├─ Yes → CoxnetSurvivalAnalysis (elastic net)\n│ └─ No → Continue\n│\n├─ Need interpretable coefficients?\n│ ├─ Yes → CoxPHSurvivalAnalysis or ComponentwiseGradientBoostingSurvivalAnalysis\n│ └─ No → Continue\n│\n├─ Complex non-linear relationships expected?\n│ ├─ Yes\n│ │ ├─ Large dataset (n > 1000) → GradientBoostingSurvivalAnalysis\n│ │ ├─ Medium dataset → RandomSurvivalForest or FastKernelSurvivalSVM\n│ │ └─ Small dataset → RandomSurvivalForest\n│ └─ No → CoxPHSurvivalAnalysis or FastSurvivalSVM\n│\n└─ For maximum performance → Try multiple models and compare\nBefore modeling, properly prepare survival data:
\nfrom sksurv.util import Surv\n\n# From separate arrays\ny = Surv.from_arrays(event=event_array, time=time_array)\n\n# From DataFrame\ny = Surv.from_dataframe('event', 'time', df)\nBuilt-in datasets use their own field names and categorical features. load_breast_cancer() returns fields ('e.tdm', 't.tdm'), load_gbsg2() ('cens', 'time'), load_whas500() ('fstat', 'lenfol'), and load_veterans_lung_cancer() ('Status', 'Survival_in_days'), and their X contains pandas categorical columns that scalers and most estimators reject. Normalize both before reusing code that indexes y['event'] / y['time']:
from sksurv.preprocessing import encode_categorical\n\nX = encode_categorical(X) # one-hot encode categorical columns\nevent_field, time_field = y.dtype.names\ny = Surv.from_arrays(event=y[event_field], time=y[time_field]) # fields 'event', 'time'\nSee: references/data-handling.md for complete preprocessing workflows, data validation, and best practices
Proper evaluation is critical for survival models. Use appropriate metrics that account for censoring:
\nPrimary metric for ranking/discrimination:
\nfrom sksurv.metrics import concordance_index_censored, concordance_index_ipcw\n\n# Harrell's C-index\nc_harrell = concordance_index_censored(y_test['event'], y_test['time'], risk_scores)[0]\n\n# Uno's C-index (recommended)\nc_uno = concordance_index_ipcw(y_train, y_test, risk_scores)[0]\nEvaluate discrimination at specific time points:
\nfrom sksurv.metrics import cumulative_dynamic_auc\n\ntimes = [365, 730, 1095] # 1, 2, 3 years\nauc, mean_auc = cumulative_dynamic_auc(y_train, y_test, risk_scores, times)\nAssess both discrimination and calibration:
\nfrom sksurv.metrics import integrated_brier_score\n\nibs = integrated_brier_score(y_train, y_test, survival_functions, times)\nSee: references/evaluation-metrics.md for comprehensive evaluation guidance, metric selection, and using scorers with cross-validation
Handle situations with multiple mutually exclusive event types:
\nfrom sksurv.nonparametric import cumulative_incidence_competing_risks\n\n# Pass SEPARATE arrays: integer-coded event status (0=censored, 1, 2, ...)\n# and the observed time. Do NOT collapse the status to a boolean.\ntimes, cif = cumulative_incidence_competing_risks(event_status, time)\n# cif[0] = total risk (any event); cif[1:] = CIF for each event type k\ncif_event1, cif_event2 = cif[1], cif[2]\nUse competing risks when:
\nSee: references/competing-risks.md for detailed competing risks methods, cause-specific hazard models, and interpretation
Estimate survival functions without parametric assumptions:
\nfrom sksurv.nonparametric import kaplan_meier_estimator\n\ntime, survival_prob = kaplan_meier_estimator(y['event'], y['time'])\nfrom sksurv.nonparametric import nelson_aalen_estimator\n\ntime, cumulative_hazard = nelson_aalen_estimator(y['event'], y['time'])\nfrom sksurv.datasets import load_breast_cancer\nfrom sksurv.linear_model import CoxPHSurvivalAnalysis\nfrom sksurv.metrics import concordance_index_ipcw\nfrom sksurv.preprocessing import encode_categorical\nfrom sksurv.util import Surv\nfrom sklearn.model_selection import train_test_split\nfrom sklearn.preprocessing import StandardScaler\n\n# 1. Load and prepare data (encode categoricals; rename outcome fields to event/time)\nX, y = load_breast_cancer()\nX = encode_categorical(X)\nevent_field, time_field = y.dtype.names # ('e.tdm', 't.tdm') for this dataset\ny = Surv.from_arrays(event=y[event_field], time=y[time_field])\nX_train, X_test, y_train, y_test = train_test_split(\n X, y, test_size=0.2, random_state=42, stratify=y['event'])\n\n# 2. Preprocess\nscaler = StandardScaler()\nX_train_scaled = scaler.fit_transform(X_train)\nX_test_scaled = scaler.transform(X_test)\n\n# 3. Fit model (alpha > 0 adds a ridge penalty; unpenalized Cox fails when\n# features are many relative to events, as in this 198-patient, 80-feature dataset)\nestimator = CoxPHSurvivalAnalysis(alpha=0.1)\nestimator.fit(X_train_scaled, y_train)\n\n# 4. Predict\nrisk_scores = estimator.predict(X_test_scaled)\n\n# 5. Evaluate\nc_index = concordance_index_ipcw(y_train, y_test, risk_scores)[0]\nprint(f\"C-index: {c_index:.3f}\")\nThe IPCW scorer wrappers (as_concordance_index_ipcw_scorer, as_integrated_brier_score_scorer, as_cumulative_dynamic_auc_scorer) WRAP the estimator and override its .score() method — they are NOT passed to scoring=. Pass the wrapped object as the GridSearchCV estimator and prefix tuned params with estimator__. There is no valid scoring='concordance_index_ipcw' string.
CoxnetSurvivalAnalysis fits a whole regularization path: coef_ has shape (n_features, n_alphas), one column per penalty in alphas_. Tune a single penalty from that path, then read the non-zero coefficients of the chosen column.
import numpy as np\nfrom sksurv.linear_model import CoxnetSurvivalAnalysis\nfrom sklearn.model_selection import GridSearchCV\nfrom sksurv.metrics import as_concordance_index_ipcw_scorer\n\n# 1. Fit once to get the penalty path (l1_ratio near 1 = lasso-like sparsity)\npath = CoxnetSurvivalAnalysis(l1_ratio=0.9, alpha_min_ratio=0.01).fit(X_train_scaled, y_train)\n\n# 2. Wrap the estimator so .score() uses Uno's C-index, then tune one alpha per fit.\n# tau caps the evaluation horizon to avoid unstable IPCW weights in the tail.\nwrapped = as_concordance_index_ipcw_scorer(\n CoxnetSurvivalAnalysis(l1_ratio=0.9, fit_baseline_model=True), tau=y_train['time'].max())\nparam_grid = {'estimator__alphas': [[a] for a in path.alphas_]}\n# With p >> n the smallest penalties can fail to converge; GridSearchCV reports them as\n# FitFailedWarning / NaN scores and still selects among the penalties that fit.\ncv = GridSearchCV(wrapped, param_grid, cv=5)\ncv.fit(X_train_scaled, y_train)\n\n# 3. Identify selected features (unwrap to reach the Coxnet estimator; coef_ is (n_features, 1))\nbest_model = cv.best_estimator_.estimator_\nselected_features = X.columns[np.flatnonzero(best_model.coef_[:, 0])]\nfrom sksurv.ensemble import GradientBoostingSurvivalAnalysis\nfrom sklearn.model_selection import GridSearchCV\nfrom sksurv.metrics import as_concordance_index_ipcw_scorer, concordance_index_ipcw\n\n# 1. Define parameter grid\nparam_grid = {\n 'learning_rate': [0.01, 0.05, 0.1],\n 'n_estimators': [100, 200, 300],\n 'max_depth': [3, 5, 7]\n}\n\n# 2. Grid search (wrap estimator so .score() is Uno's C-index; prefix params)\ngbs = GradientBoostingSurvivalAnalysis(random_state=42)\nwrapped = as_concordance_index_ipcw_scorer(gbs, tau=y_train['time'].max())\nparam_grid = {f'estimator__{k}': v for k, v in param_grid.items()}\ncv = GridSearchCV(wrapped, param_grid, cv=5, n_jobs=-1)\ncv.fit(X_train, y_train)\n\n# 3. Evaluate best model on held-out test set\nbest_model = cv.best_estimator_.estimator_\nrisk_scores = best_model.predict(X_test)\nc_index = concordance_index_ipcw(y_train, y_test, risk_scores)[0]\nfrom sksurv.linear_model import CoxPHSurvivalAnalysis\nfrom sksurv.ensemble import RandomSurvivalForest, GradientBoostingSurvivalAnalysis\nfrom sksurv.svm import FastSurvivalSVM\nfrom sksurv.metrics import concordance_index_ipcw, integrated_brier_score\n\n# Define models\nmodels = {\n 'Cox': CoxPHSurvivalAnalysis(alpha=0.1),\n 'RSF': RandomSurvivalForest(n_estimators=100, random_state=42),\n 'GBS': GradientBoostingSurvivalAnalysis(random_state=42),\n 'SVM': FastSurvivalSVM(random_state=42)\n}\n\n# Evaluate each model\nresults = {}\nfor name, model in models.items():\n model.fit(X_train_scaled, y_train)\n risk_scores = model.predict(X_test_scaled)\n c_index = concordance_index_ipcw(y_train, y_test, risk_scores)[0]\n results[name] = c_index\n print(f\"{name}: C-index = {c_index:.3f}\")\n\n# Select best model\nbest_model_name = max(results, key=results.get)\nprint(f\"\\nBest model: {best_model_name}\")\nscikit-survival fully integrates with scikit-learn's ecosystem:
\nfrom sklearn.pipeline import Pipeline\nfrom sklearn.model_selection import cross_val_score, GridSearchCV\nfrom sklearn.preprocessing import StandardScaler\nfrom sksurv.linear_model import CoxPHSurvivalAnalysis\nfrom sksurv.metrics import as_concordance_index_ipcw_scorer\n\n# Build the pipeline, then wrap it so .score() is Uno's C-index.\n# Wrapping the whole pipeline keeps scaling inside each CV fold (no leakage).\npipeline = Pipeline([\n ('scaler', StandardScaler()),\n ('model', CoxPHSurvivalAnalysis())\n])\nwrapped = as_concordance_index_ipcw_scorer(pipeline, tau=y['time'].max())\n\n# Cross-validation uses the wrapped estimator's .score(); leave scoring=None\nscores = cross_val_score(wrapped, X, y, cv=5)\n\n# Grid search: params live under estimator__ (wrapper) then the pipeline step\nparam_grid = {'estimator__model__alpha': [0.1, 1.0, 10.0]}\ncv = GridSearchCV(wrapped, param_grid, cv=5)\ncv.fit(X, y)\nas_concordance_index_ipcw_scorer() to scoring= → It WRAPS the estimator (overriding .score()); pass the wrapped object as the estimator and prefix params with estimator__criterion parameter from GradientBoostingSurvivalAnalysis; 0.27 added pandas 3 support.CoxnetSurvivalAnalysis requires 0 < l1_ratio ≤ 1; for a pure ridge penalty use CoxPHSurvivalAnalysis(alpha=...).This skill includes detailed reference files for specific topics:
\nreferences/cox-models.md: Complete guide to Cox proportional hazards models, penalized Cox (CoxNet), IPCRidge, regularization strategies, and interpretationreferences/ensemble-models.md: Random Survival Forests, Gradient Boosting, hyperparameter tuning, feature importance, and model selectionreferences/evaluation-metrics.md: Concordance index (Harrell's vs Uno's), time-dependent AUC, Brier score, comprehensive evaluation pipelinesreferences/data-handling.md: Data loading, preprocessing workflows, handling missing data, feature encoding, validation checksreferences/svm-models.md: Survival Support Vector Machines, kernel selection, clinical kernel transform, hyperparameter tuningreferences/competing-risks.md: Competing risks analysis, cumulative incidence functions, cause-specific hazard modelsLoad these reference files when detailed information is needed for specific tasks.
\nsksurv.datasets for practice datasets (GBSG2, WHAS500, veterans lung cancer, etc.)# Models\nfrom sksurv.linear_model import CoxPHSurvivalAnalysis, CoxnetSurvivalAnalysis, IPCRidge\nfrom sksurv.ensemble import RandomSurvivalForest, GradientBoostingSurvivalAnalysis\nfrom sksurv.svm import FastSurvivalSVM, FastKernelSurvivalSVM\nfrom sksurv.tree import SurvivalTree\n\n# Evaluation metrics\nfrom sksurv.metrics import (\n concordance_index_censored,\n concordance_index_ipcw,\n cumulative_dynamic_auc,\n brier_score,\n integrated_brier_score,\n as_concordance_index_ipcw_scorer,\n as_integrated_brier_score_scorer\n)\n\n# Non-parametric estimation\nfrom sksurv.nonparametric import (\n kaplan_meier_estimator,\n nelson_aalen_estimator,\n cumulative_incidence_competing_risks\n)\n\n# Data handling\nfrom sksurv.util import Surv\nfrom sksurv.preprocessing import OneHotEncoder, encode_categorical\nfrom sksurv.datasets import load_gbsg2, load_breast_cancer, load_veterans_lung_cancer\n\n# Kernels\nfrom sksurv.kernels import ClinicalKernelTransform\n