survival: implement Kaplan-Meier and Nelson-Aalen estimators

[TheHiddenObserver]

Context

statgpu has a mature CoxPH/CoxPHCV core, including right-censored, delayed-entry, start-stop, strata, ties, prediction, and inference contracts. It does not yet provide the foundational nonparametric survival estimators expected in a complete survival workflow.

Roadmap: PR #89. Module reference: dev/plans/plan_survival.md.

Goal

Implement maintained Kaplan-Meier and Nelson-Aalen estimators with explicit statistical, backend, prediction, and inference contracts.

Proposed public surface

The design phase must decide and document:

• estimator class names and top-level exports;
• array and formula/dataframe inputs;
• event/time encoding;
• grouped/stratified output representation;
• result object shape for event table, survival/cumulative hazard, variance, confidence intervals, quantiles, and median survival;
• prediction/evaluation behavior between observed event times;
• handling of all-censored, no-at-risk, zero-weight, and empty-group cases.

A consistent relationship with existing Cox baseline-hazard and survival-prediction objects should be preferred over a separate incompatible result system.

Statistical scope — first phase

Kaplan-Meier

• right-censored data;
• product-limit survival estimate;
• Greenwood variance;
• confidence intervals with at least one explicitly documented transformation;
• median survival and arbitrary survival quantiles where defined;
• event table with at-risk, events, censoring, and weights.

Nelson-Aalen

• cumulative hazard estimate;
• corresponding variance estimate;
• confidence intervals;
• event table aligned with Kaplan-Meier output.

Grouped output

• group/strata-specific curves with independent risk sets;
• deterministic group ordering and labels;
• no accidental pooling across groups.

Left truncation/delayed entry may be included in the first phase only if the contract and external alignment are fully validated. Otherwise it must be explicitly deferred to a follow-up issue rather than partially supported.

Backend contract

• NumPy CPU;
• CuPy CUDA;
• Torch CUDA;
• backend-native sorting, grouping, risk-set aggregation, and cumulative operations;
• only final scalar/table conversion may synchronize to CPU when the public result contract requires it;
• explicit GPU requests must not silently fall back;
• dtype and finite-input behavior must be documented.

External alignment

Use matched comparisons against:

• R survival::survfit;
• lifelines.KaplanMeierFitter;
• lifelines.NelsonAalenFitter;
• statsmodels SurvfuncRight where semantics align.

Document differences in confidence-interval transformation, event-time convention, weights, left truncation, and quantile interpolation.

Formula and input validation

Cover:

• Surv(time, event)-style formula if supported by current formula infrastructure;
• boolean/integer event validation;
• nonnegative finite times;
• sample-weight validation;
• missing-data alignment;
• tied events and censoring at the same time;
• deterministic ordering after sorting;
• one-row and all-censored edge cases.

Non-goals

• no AFT model in this issue;
• no Fine-Gray competing risks;
• no frailty or multi-state model;
• no survival forest or boosting;
• no universal plotting dependency in the core package.

Required validation

• exact small-sample hand calculations;
• tied event/censoring cases;
• all-censored and degenerate cases;
• weighted cases if weights are supported;
• grouped/stratified cases;
• NumPy/CuPy/Torch parity;
• external alignment for estimates, variance, intervals, and median/quantiles;
• physical CuPy and Torch GPU runs;
• EN/CN documentation with CPU and GPU examples;
• benchmark artifact only if a performance claim is made.

Acceptance criteria

• Public APIs and result objects are documented before implementation is finalized.
• Kaplan-Meier estimates, Greenwood variance, confidence intervals, and quantiles are implemented.
• Nelson-Aalen cumulative hazard, variance, and confidence intervals are implemented.
• Grouped/stratified curves use independent risk sets and deterministic labels.
• NumPy, CuPy, and Torch paths pass parity tests without silent fallback.
• External alignment records all convention differences explicitly.
• Degenerate and invalid inputs have deliberate, tested behavior.
• Complete CPU, compatibility, and physical-GPU gates pass.
• User documentation is synchronized in English and Chinese.

Dependency and follow-up

This issue is independent of the benchmark dashboard. Parametric AFT models are tracked separately.