When the question is when an event happens (churn, failure, default, death, conversion) and some subjects have not had it yet, ordinary classification and regression are wrong. Dropping the censored subjects biases toward short times, treating them as "no event" biases toward long ones, and regressing on observed durations ignores who is still at risk. Survival analysis uses everyone for as long as they were observed.
scripts/km_report.pydescribes the curves and compares groupsscripts/cox_fit.pyfits and checks a Cox model with no dependenciesscripts/gen_survival_script.pycompares Cox, Weibull AFT, random survival forest and gradient boosting with survival metrics
Trigger Conditions
Activate this skill when the user:
- Asks how long until customers churn, machines fail, loans default or patients have an event
- Has durations where some subjects are still active / alive / working (censored)
- Wants survival curves, median time-to-event, hazard ratios, or a comparison of groups over time
- Builds a churn or lifetime model and is unsure how to handle customers who have not churned
If the question is only "will it happen within 30 days?" and everyone has been observed for 30 days, a classifier with a clear label window works too. See ml-problem-framing-advisor.
Workflow
1. DATA -> one row per subject: duration (start -> event or censoring), event (1/0), covariates at start
2. DESCRIBE -> python scripts/km_report.py data.csv --duration-col t --event-col e --group plan --at 90 180 365
3. COX -> python scripts/cox_fit.py data.csv --duration-col t --event-col e --covariates plan age
4. CHECK -> PH test per covariate; crossing curves; events per covariate; censoring pattern
5. COMPARE -> python scripts/gen_survival_script.py --data data.csv --duration-col t --event-col e --covariates plan age -o surv.py
6. REPORT -> curves, medians/RMST, hazard ratios with CIs, model comparison, assumptionsGetting the Data Right
| Item | Rule |
|---|---|
| Time origin | the same meaningful start for everyone: signup, installation, diagnosis, loan origination |
| Duration | from origin to the event, or to the last time the subject was observed event-free (censoring) |
| Event | 1 if the event was observed, 0 if censored; one event type per model (see competing risks) |
| Covariates | known at the origin (baseline). Time-varying values need a counting-process (start, stop] format |
| Administrative censoring | everyone still active at the data cut-off is censored at the cut-off date |
| Left truncation | subjects who enter observation late (e.g. customers acquired before the data start) need entry times |
Censoring must be non-informative: being censored must not depend on the risk of the event. Customers who cancel by switching to another plan, or patients withdrawn because they got worse, violate it. Details, pitfalls and the long format: survival-data.md.
Choosing the Model
| Need | Model |
|---|---|
| Describe and compare groups | Kaplan-Meier + log-rank; RMST difference |
| Interpretable effects (hazard ratios) | Cox PH (cox_fit.py); penalised when covariates are many |
| Predict survival time directly, extrapolate | parametric AFT (Weibull, log-normal, log-logistic) |
| Non-linear effects and interactions, non-PH | random survival forest, gradient-boosted survival |
| Several event types (churn vs downgrade) | competing risks: cause-specific Cox, Fine-Gray, Aalen-Johansen |
| Covariates that change over time | time-varying Cox (lifelines CoxTimeVaryingFitter) |
| Discrete time (monthly) and many rows | discrete-time hazard: logistic regression on person-period data |
On the fixture with a proportional effect, penalised Cox had the best integrated Brier score (0.172). On the fixture with crossing hazards (surgery: early risk, later benefit), the random survival forest won and the script flagged the PH violation. Model guide with code: survival-models.md.
Assumptions and Diagnostics
| Check | Tool | If it fails |
|---|---|---|
| Proportional hazards | cox_fit.py PH p per covariate (Grambsch-Therneau, rank time) | stratify, add covariate x time, or use RMST / time-specific effects |
| Crossing survival curves | km_report.py warning | a single hazard ratio misleads; report RMST and S(t) at key times |
| Enough events | >= 10 events per covariate | penalise (--penalizer), fewer covariates |
| Heavy censoring | km_report.py (> 70%) | the late curve is uncertain; report earlier time points |
| Linear covariate effects | martingale residual plots, splines | transform or bin the covariate |
| Influential subjects | dfbeta | check for data errors |
cox_fit.py and km_report.py reproduce lifelines exactly on the fixtures (coefficients, standard errors,
log-likelihood, concordance, PH p-values, Kaplan-Meier CIs, medians, RMST and the log-rank statistic).
Evaluation
| Metric | Measures | Note |
|---|---|---|
| Harrell's C | ranking of risk vs observed order | depends on the censoring distribution |
| Uno's C (IPCW, truncated at tau) | ranking, censoring-adjusted | preferred for comparing models |
| Time-dependent AUC at t | who has the event by t vs who survives past t | report at decision-relevant times |
| Integrated Brier score | calibration + discrimination of S(t) over time | 0 is perfect; around 0.25 is uninformative |
| Calibration at t | predicted S(t) vs Kaplan-Meier observed by risk group | needed when probabilities drive decisions |
Never evaluate with accuracy or RMSE on observed durations. Metric details: survival-evaluation.md.
Output Format
When delivering a survival analysis, provide:
- Data definition - origin, event, censoring rule, follow-up, number of events.
- Descriptive curves - KM by group with CIs, median survival or "not reached", S(t) at key times, RMST.
- Model - hazard ratios with 95% CIs (or AFT time ratios), concordance, PH diagnostics.
- Prediction comparison - Uno's C, time-dependent AUC, integrated Brier score and calibration per model.
- Caveats - censoring assumptions, PH violations, extrapolation beyond follow-up.
Scripts
python scripts/km_report.py survival.csv --duration-col duration_days --event-col event --group plan --at 90 180 365
python scripts/km_report.py data.csv --duration-col t --event-col died --group arm --tau 365 --jsonExit codes: 0 reported, 2 usage or read error.
python scripts/cox_fit.py survival.csv --duration-col duration_days --event-col event --covariates plan age
python scripts/cox_fit.py data.csv --duration-col t --event-col died --covariates age stage --penalizer 0.1 --jsonCategorical covariates are one-hot encoded against the first sorted level. Exit codes: 0 fitted and PH holds, 1 PH violated, 2 usage error or no convergence.
python scripts/gen_survival_script.py --data survival.csv --duration-col duration_days --event-col event --covariates plan age -o surv.py
python scripts/gen_survival_script.py --data data.csv --duration-col t --event-col churn --covariates plan --time-col signup_date --times 90 180Exit codes: 0 written, 2 usage error. scripts/_surv_io.py holds the shared loading and chi-square /
normal tail functions.
Additional Resources
| File | Content |
|---|---|
| survival-data.md | origins, censoring types, informative censoring, truncation, long format, data checks |
| survival-models.md | Kaplan-Meier, Cox, AFT, RSF, boosting, competing risks, time-varying covariates, discrete time |
| survival-evaluation.md | concordance, time-dependent AUC, Brier score, calibration, RMST, reporting |
anomaly-detection-model-builder
Build and evaluate anomaly detection for tabular, sensor and transaction data with few or no labels: define the anomaly type (point, contextual, collective), choose detectors (robust z-score/MAD and IQR rules, Mahalanobis with robust covariance, k-NN distance, LOF, Isolation Forest, one-class SVM, PCA reconstruction / autoencoders, forecasting residuals for time series), combine them by rank, explain each alert by its deviating features, set thresholds from an alert budget or the score distribution, and evaluate with precision@k, PR-AUC and recall on known incidents, or detector agreement when no labels exist. Includes pure-Python detectors (robust z, Mahalanobis, kNN, Isolation Forest, ensemble) and an evaluation script.
catboost-model-builder
Build CatBoost models that use its strengths correctly: raw categorical columns as cat_features (ordered target statistics, no manual encoding), text_features, Pool construction with NaN-safe categories, ordered boosting and has_time for temporal data, symmetric (oblivious) trees, overfitting detector with eval_set and use_best_model, losses for classification, regression (Quantile, Poisson, Tweedie) and ranking (YetiRank), class weights, monotone constraints, feature importance (PredictionValuesChange, LossFunctionChange) and SHAP values, GPU training and model export. Plans cat/text/numeric columns from a CSV and generates a runnable training script, and checks parameter sets for the conflicts CatBoost rejects (iterations vs n_estimators, Bayesian bootstrap with subsample, multiple class-weight options, depth > 16, use_best_model without eval_set).
categorical-encoding-selector
Choose and implement the right encoding for every categorical column given the model family and the data: one-hot (with infrequent-level grouping and handle_unknown), ordinal with an explicit order, cross-fitted target encoding (scikit-learn TargetEncoder, CatBoost ordered statistics, category_encoders inside CV), frequency/count encoding, feature hashing, native categorical support in LightGBM, HistGradientBoosting, XGBoost and CatBoost, prefix levels for codes (zip3, NAICS-2), and embeddings. Measures cardinality, rare-level share, unseen-level rate on a time-ordered holdout and target signal per column, emits the ColumnTransformer, and quantifies target-encoding leakage (in-sample vs out-of-fold vs holdout AUC).
classification-model-selector
Choose the right classification algorithm for tabular, text or mixed data and prove the choice with a fair bake-off: logistic regression (L2, L1, elastic net), linear SVM, naive Bayes, k-NN, RBF SVM, decision trees, random forest, extra trees, HistGradientBoosting, LightGBM, XGBoost, CatBoost, explainable boosting machines (EBM/GAM), points scorecards and MLPs, matched to data size, width, categorical and high-cardinality share, missingness, class imbalance, text, and constraints such as interpretability, monotonic constraints, calibrated probabilities, latency budgets and tiny deployable models. Ranks candidates with starting hyperparameters and cautions, then generates a bake-off script running every candidate on identical CV folds with per-fold metrics, fit time and prediction latency.
clustering-algorithm-selector
Choose the right clustering algorithm and check that clustering makes sense at all: cluster tendency (Hopkins statistic with a correlated-features caveat, nearest-neighbour isolation), then k-means / MiniBatchKMeans, Gaussian mixtures with BIC, agglomerative (Ward, average, complete, single) with dendrograms, DBSCAN, HDBSCAN, OPTICS, spectral clustering, BIRCH, mean shift, k-prototypes and k-modes for mixed or categorical data, and Gower distance, matched to data size, expected shapes, noise, varying density, known k, soft memberships, hierarchy and streaming. Covers preprocessing (scaling, encoding, dimensionality, distance metrics), validation (internal indices, bootstrap stability, external labels, business profiling) and assigning new points.
collaborative-filtering-implementer
Implement collaborative filtering recommenders that beat popularity: item-based kNN with cosine, Jaccard or asymmetric similarity, shrinkage, neighbourhood size, positive-only or mean-centred rating signals and 'because you liked X' explanations; implicit ALS with confidence weighting, BPR pairwise ranking and the closed-form EASE model in plain NumPy, tuned on a temporal validation split by recall@k and NDCG@k and refit on all data; plus user-kNN, explicit matrix factorisation, the implicit/LightFM libraries, hyperparameter ranges, cold-start fallbacks, scaling with sparse matrices and approximate nearest neighbours. Produces top-k lists in the format of the recommendation evaluator.