survival-analysis ยท diff
v1.0.0 to v1.2.0
200 added, 26 removed. Audit A to A.
---
name: survival-analysis
description: >-
- [TODO] Define the specific workflow this skill standardises, including default libraries,
- quality checks, and expected deliverables.
- version: 1.0.0
- tags:
- - data-science
- - [TODO]
+ Expert-standard support for survival and time-to-event analysis at any experience
+ level: cohort design, code, diagnostics, evaluation, interpretation and review.
+ Use for customer churn, retention, failure, readmission or other censored outcomes;
+ Kaplan-Meier, Cox proportional hazards, AFT, competing risks, delayed entry,
+ recurrent events, time-varying covariates, discrete-time models, survival forests,
+ calibration, temporal leakage, immortal time, large-cohort runtime or survival-model
+ audits. Python first, with a secondary R path. Adapt explanations to the user's
+ experience, ask about unresolved estimands and observation rules, and distinguish
+ hazards from event probabilities.
metadata:
skill-author: 'Marie-Lynne Block'
+ version: 1.2.0
---
- ## What this skill does
+ # Survival Analysis
- [TODO] Define the specific workflow this skill standardises, including default libraries,
- quality checks, and expected deliverables.
+ Provide expert-standard support for data scientists at any experience level. Cover
+ description, association, prediction and analysis review across domains, with
+ customer churn as a recurring example. Briefly define unfamiliar concepts in plain
+ language, connect them to the immediate decision, then offer deeper technical detail
+ when it helps. Prioritise the estimand, observation process, executable work and
+ evidence over a tutorial or paperwork.
- ## When to use it
+ ## Request Routing
- [TODO] List concrete user intents and trigger phrases that should activate this skill.
+ | Request | Steps that apply | Reference to load |
+ | --- | --- | --- |
+ | Define a cohort, event or estimand | 1-2 | Design and assumptions |
+ | Choose or justify a method | 1, 5 | Methods and interpretation |
+ | Write or adapt code | 2, 5, 6 | Implementation |
+ | Diagnose a failing or suspect fit | 2, 6 | Implementation, methods |
+ | Design or repair validation | 3, 7 | Evaluation and reporting |
+ | Interpret or explain a result | 4, 8 | Methods and interpretation |
+ | Review someone else's analysis | 1-8 as evidence allows | All, as the findings require |
+ | Cohort too large or too slow | 2, 5, 7 | Scale and performance |
- ## Instructions
+ ## Working Agreement
- 1. Clarify the objective, data assumptions, and success metrics.
- 2. Execute a leakage-safe and reproducible workflow for this skill domain.
- 3. Validate outputs with diagnostics, edge-case checks, and documented caveats.
+ - Establish whether the request is to design, implement, diagnose, evaluate,
+ interpret or review. Do the requested slice; do not restart a settled analysis.
+ - Inspect the existing schema, code, environment and documented decisions first.
+ Ask only questions whose answers change the next step. Never invent event
+ definitions, censoring rules, business thresholds or results.
+ - Separate confirmed facts, proposed choices and unresolved questions. Mark
+ material unknowns `[TODO]` only when recording them is useful. Explain why a
+ material unknown blocks fitting or interpretation and what evidence resolves it.
+ A clearly labelled synthetic example may proceed without real data.
+ - Use Python primarily and R when requested or already established. Preserve the
+ project's libraries, versions and environment manager where suitable. Confirm
+ API support for the installed version before writing library-specific code.
+ - Ask before installing, upgrading or removing dependencies. Do not auto-install
+ on import failure; report the missing prerequisite.
+ - Work with the project's existing data-access constraints. Prefer schemas,
+ aggregate diagnostics or synthetic examples over sensitive row-level output.
- ## Output format
+ ## Workflow
- - A concise plan of action
- - Executable code or commands
- - Validation summary with assumptions and risks
+ ### 1. Define the Question and Estimand
- ## Examples
+ Confirm the population, unit of analysis, decision, event and meaningful time
+ horizons. Distinguish describing event-free survival, estimating adjusted
+ associations, predicting absolute risk, and estimating a causal intervention
+ effect. A predictive model or adjusted hazard ratio alone does not identify a
+ causal effect. Retention targeting needs evidence of intervention benefit, not
+ only a ranking of churn risk.
- ### Example 1 - baseline workflow
+ Record time zero, prediction time, eligibility, time scale and units, event coding,
+ observation end, censoring reasons, competing events, delayed entry, repeated
+ episodes and feature-availability timestamps. Ask whether churn is cancellation,
+ non-renewal or a confirmed inactivity rule, and whether reactivation is possible.
+ Do not fit while these definitions materially change the target or risk sets.
- **Input:** User asks for help in survival-analysis.
- **Expected output:** A reproducible, validated workflow using the skill's core tools.
+ ### 2. Validate the Cohort and Observation Process
- ## Notes
+ Reconcile cohort counts and exclusions. Check IDs, event-code meanings, missing
+ outcomes, non-finite or negative durations, zero-time events, timestamp order,
+ duplicates, time units and the last date at which events can genuinely be observed.
+ Never turn a missing event flag into censoring or drop censored rows by default.
- - Prefer documented, stable APIs over experimental shortcuts.
- - Record assumptions explicitly when data quality or labels are uncertain.
+ Use the correct schema: duration/event for ordinary right censoring; entry/exit
+ for delayed entry; lower/upper bounds for interval censoring; event types for
+ competing risks; ID/start/stop/event for changing covariates or repeated episodes.
+ Check non-overlapping, positive-length intervals and events at the correct stops.
+ Do not force unsupported observation schemes into a two-column right-censored API.
+
+ Examine censoring by reason, cohort and predictors. Independent censoring is an
+ assumption, not something a diagnostic can certify. Distinguish assumptions for
+ unadjusted Kaplan-Meier from those conditional on covariates in a regression model.
+ Escalate plausible informative dropout with sensitivity analyses and limitations.
+
+ ### 3. Establish a Leakage-Safe Validation Design
+
+ For prediction, agree training, tuning and held-out evaluation populations and
+ calendar cut-offs before fitting. Match validation to the intended deployment.
+ Keep dependent entities and episodes together unless an explicit existing-customer
+ backtest justifies otherwise; preserve temporal order and label availability.
+ Fit preprocessing, feature selection and tuning only within training folds.
+
+ At prediction time, use only information already available, including ingestion
+ and reporting delays. For time-varying analysis, covariates must be available at
+ each interval start. Do not use final tenure, later cancellations or future
+ behaviour as predictors. A later training-label freeze can leak into an earlier
+ deployment backtest even when feature timestamps are correct.
+
+ For an association study, use a justified inferential design, diagnostics and
+ sensitivity analyses; do not impose a predictive train/test split automatically.
+
+ ### 4. Describe Before Modelling
+
+ Report subjects, events by type, censoring, follow-up and numbers at risk. Use
+ Kaplan-Meier with confidence intervals and a risk table for suitable single-event
+ data; use cumulative incidence for cause-specific probabilities with competing
+ events. Do not call one minus cause-specific Kaplan-Meier an observed event risk.
+
+ Report the median only if the curve reaches 0.5; otherwise say "not reached within
+ follow-up". Consider restricted mean survival over an agreed supported horizon.
+ An unadjusted log-rank comparison is neither an effect size nor a causal result.
+
+ ### 5. Select the Simplest Suitable Model
+
+ Start with a transparent baseline compatible with the estimand and observation
+ scheme, often Cox PH for baseline covariates and ordinary right censoring. Consider
+ penalisation and nonlinear terms where justified. Compare a limited set of
+ alternatives rather than conducting an unbounded algorithm search.
+
+ Route competing probabilities to cumulative-incidence methods; changing
+ covariates to start-stop methods or a justified landmark design; non-PH effects to
+ time interactions, stratification or suitable alternatives; time ratios to AFT;
+ repeated events to an explicit recurrent-event or multi-state design. Consider
+ survival forests, boosting or discrete-time models when prediction warrants them.
+ Do not assume a Weibull AFT model resolves PH violations: its usual form is also PH.
+
+ When cohort size, expanded row count or runtime constrains the choice, size the
+ problem before abandoning a method. Treat any sampling design as an explicit
+ observation and estimator choice: report the inclusion rule, compatible estimator
+ and variance procedure rather than applying it as a silent shortcut.
+
+ ### 6. Check Fit and Assumptions
+
+ For Cox models, combine scaled Schoenfeld diagnostics and plots with effect size,
+ functional form and domain knowledge. Non-significance is not proof of PH. Check
+ convergence, separation, collinearity, sparse events, influential observations and
+ dependence. Do not silence warnings or use penalisation to hide a broken cohort.
+
+ Explain how each material violation changes the conclusion or model. Stratifying
+ on a variable does not estimate its hazard ratio. Time-varying covariates do not
+ automatically create time-varying coefficients. Extrapolation needs explicit
+ distributional assumptions, sensitivity analysis and a labelled extrapolated range.
+
+ ### 7. Evaluate What Will Be Used
+
+ For prediction, assess held-out discrimination, censoring-aware probability error
+ and calibration at agreed horizons, with uncertainty and a simple baseline. Name
+ the concordance estimator, AUC definition, time grid, censoring estimator and
+ integration interval. A high C-index is not evidence of calibrated probabilities.
+
+ Verify follow-up and censoring support before IPCW metrics. Do not silently remove
+ long-followed subjects, clip their outcomes or change horizons to make a metric
+ run. Use competing-risk metrics for a competing-risk estimand. Review subgroup and
+ calendar-period performance where sample support permits; report unsupported
+ horizons and unstable estimates instead of inventing thresholds or precision.
+
+ ### 8. Interpret and Hand Over
+
+ Distinguish survival probability, event probability, hazard ratio, subdistribution
+ hazard ratio and time ratio. State units, reference categories, conditioning,
+ uncertainty and limitations. Keep association, prediction and causation separate.
+
+ For work that will be rerun, retain the cohort/query version, extraction and label
+ cut-offs, split membership, feature specification, seeds, package versions,
+ transformations and model settings in the project's existing artefact. Provide
+ reproducible code plus evidence appropriate to the requested slice.
+ For prediction use, state scoring time, eligible population, feature freshness and
+ outcome maturation so the analysis can be reproduced and evaluated over time.
+
+ ## Response Contract
+
+ Return the decision or finding first, then only the supporting evidence relevant to
+ the request:
+
+ 1. Objective, estimand and scope; unresolved blocking questions when applicable.
+ 2. Method choice and observation-scheme fit when selecting or reviewing a method.
+ 3. Code or analysis changes when requested, using the project's established stack.
+ 4. Checks actually run, results, remaining assumptions and unavailable validation.
+ 5. Interpretation, limitations and the next analytical decision when needed.
+
+ For reviews, lead with severity-ranked findings tied to the supplied code or
+ analysis, consequences and suggested corrections. Never claim that documentation
+ review, code generation or a synthetic smoke test validates a real-world model.
+
+ ## Bundled Resources
+
+ Load only the resources needed for the current task. Prefer the project's existing
+ notebook, code comments, analysis document or issue context. Use a template only
+ when it helps resolve material decisions or the user asks for one; copy only the
+ relevant sections and omit the rest without justification.
+
+ - [Design and assumptions](./references/design-and-assumptions.md): estimands,
+ observation schemas, churn definitions, leakage and informative censoring.
+ - [Methods and interpretation](./references/methods-and-interpretation.md): method
+ selection, equations, diagnostics, advanced designs and interpretation traps.
+ - [Evaluation and reporting](./references/evaluation-and-reporting.md): validation
+ design, metric contracts, calibration, uncertainty and evidence by task.
+ - [Scale and performance](./references/scale-and-performance.md): load when cohort
+ size, expanded row count or runtime constrains the work. Single-workstation
+ choices, design-specific sampling and warehouse escalation.
+ - [Implementation](./references/implementation.md): library compatibility, capability
+ checks, troubleshooting, Python usage and sources, plus a secondary R example that
+ is not execution-tested. Read before running the bundled script.
+ - [Synthetic Python workflow](./scripts/synthetic_workflow.py): single-event
+ example with input guards, Cox diagnostics, held-out metrics and calibration.
+ Requires the documented dependencies; it never installs or accesses real data.
+ - [Analysis plan](./assets/analysis-plan.md): optional prompts for unresolved
+ estimand, cohort, leakage, assumption and validation decisions.
+ - [Evidence report](./assets/analysis-report.md): optional prompts for findings,
+ diagnostics, validation limits and reproducibility evidence.