API Reference / algorithms / survival /

kaplan_meier.py

Non-parametric survival_curve estimators (Kaplan-Meier and Nelson-Aalen).

Classes

KaplanMeierEstimator

class algorithms.survival.kaplan_meier.KaplanMeierEstimator(Survival)

Kaplan-Meier product-limit estimator of the survival function.

The non_parametric maximum-likelihood estimate of S(t) = P(T > t) under right-censoring. No covariates: it describes the population as a whole, so it is a baseline every covariate model must beat rather than a per-sample risk model.
Constructor 
__init__(
    self,
)

Overview

  1. Sort the observed times and keep only the times at which an event
occurred (timeline_).
  1. At each event time t_j, compute d_j (events at
t_j) and n_j (subjects at risk just before t_j).
  1. Multiply the survival factors (1 - d_j / n_j) to form the
step-function estimate of S(t).

Theory

The product-limit estimator is

\hat{S}(t) = \prod_{j: t_j \leq t} \left(1 - \frac{d_j}{n_j}\right)

and the corresponding Nelson-Aalen cumulative hazard is

\hat{H}(t) = \sum_{j: t_j \leq t} \frac{d_j}{n_j}.

Censored observations contribute to n_j while they are still at risk, but never contribute an event, which is how the estimator respects partial information.

Parameters

This estimator takes no hyperparameters.

Attributes

timeline_
np.ndarray of shape (n_events,)
Sorted unique event times.
survival_
np.ndarray of shape (n_events,)
Product-limit survival at each timeline_ entry.
cumulative_hazard_
np.ndarray of shape (n_events,)
Nelson-Aalen cumulative hazard at each timeline_ entry.
n_risk_
np.ndarray of shape (n_events,)
Number of subjects at risk just before each event time.
n_events_
np.ndarray of shape (n_events,)
Number of events at each event time.
total_cumulative_hazard_
float
Cumulative hazard at the final event time; the constant risk score.

Notes

Complexity:

  • Fitting: O(n \log n) (sorting dominates).
  • Prediction: O(\log n) per query via binary search.
When to use KaplanMeierEstimator:
  • As a descriptive summary of a single population's survival curve.
  • As the baseline against which covariate models are compared.
  • The survival function is only defined up to the last event time; beyond
the largest observed time the estimate is not identifiable.

References

Kaplan1958
Kaplan, E.L. and Meier, P. (1958). Nonparametric Estimation from Incomplete Observations. Journal of the American Statistical Association, 53(282), 457-481. DOI: 10.1080/01621459.1958.10501452

See Also

NelsonAalenEstimator

Cumulative-hazard analogue.
CoxPHSurvival

Covariate-adjusted model.
python 
>>> from tuiml.algorithms.survival import KaplanMeierEstimator
>>> import numpy as np
>>> km = KaplanMeierEstimator().fit([2, 3, 4, 5], [1, 1, 0, 1])
>>> km.timeline_.tolist()
[2.0, 3.0, 5.0]
>>> np.round(km.survival_, 4).tolist()
[0.75, 0.5, 0.0]
>>> np.round(km.predict_survival_function([1, 2, 3, 4, 5, 6]), 6).tolist()
[1.0, 0.75, 0.5, 0.5, 0.0, 0.0]

Methods

get_parameter_schema (cls) -> Dict[str, Dict[str, Any]]

Return JSON Schema for constructor parameters.

get_capabilities (cls) -> List[str]

Return supported capabilities.

get_complexity (cls) -> str

Return complexity analysis.

get_references (cls) -> List[str]

Return academic citations.

fit (self, time, event) -> 'KaplanMeierEstimator'

Fit the product-limit estimator.

Parameters
time
array-like of shape (n_samples,)
Observed time (event or censoring).
event
array-like of shape (n_samples,)
Event indicator (1 = event observed, 0 = right-censored).
Returns
self
KaplanMeierEstimator
Fitted estimator.
predict_survival_function (self, times)

Return the estimated survival probability at times.

Parameters
times
float or array-like
Time point(s) at which to evaluate :math:`\hat{S}(t)`.
Returns
S
float or np.ndarray
Product-limit survival estimate at each query time.
predict_cumulative_hazard (self, times)

Return the Nelson-Aalen cumulative hazard at times.

Parameters
times
float or array-like
Time point(s) at which to evaluate :math:`\hat{H}(t)`.
Returns
H
float or np.ndarray
Cumulative hazard estimate at each query time.
predict_risk (self, X) -> np.ndarray

Return a constant risk score (a non_parametric baseline).

Parameters
X
array-like of shape (n_samples, n_features)
Covariates. Only the number of rows is used.
Returns
risk
np.ndarray of shape (n_samples,)
Constant baseline risk.

NelsonAalenEstimator

class algorithms.survival.kaplan_meier.NelsonAalenEstimator(Survival)

Nelson-Aalen estimator of the cumulative hazard function.

The non_parametric estimate of the cumulative hazard H(t) = -\log S(t), from which a survival curve \hat{S}(t) = e^{-\hat{H}(t)} follows. Like Kaplan-Meier it is a population-level baseline with no covariates.
Constructor 
__init__(
    self,
)

Overview

  1. Keep only the event times (timeline_).
  2. Accumulate the increments d_j / n_j into the cumulative hazard.
  3. Expose the survival function as \exp(-\hat{H}(t)).

Theory

\hat{H}(t) = \sum_{j: t_j \leq t} \frac{d_j}{n_j}, \qquad \hat{S}(t) = \exp\!\left(-\hat{H}(t)\right).

The Nelson-Aalen estimator has slightly lower finite-sample bias than the Kaplan-Meier estimate of the same quantity and is the canonical input for leaf-hazard conventions in survival ensembles.

Parameters

This estimator takes no hyperparameters.

Attributes

timeline_
np.ndarray of shape (n_events,)
Sorted unique event times.
cumulative_hazard_
np.ndarray of shape (n_events,)
Nelson-Aalen cumulative hazard at each timeline_ entry.
survival_
np.ndarray of shape (n_events,)
Exponential survival :math:`\exp(-\hat{H}(t))` at each entry.
n_risk_
np.ndarray of shape (n_events,)
Number of subjects at risk just before each event time.
n_events_
np.ndarray of shape (n_events,)
Number of events at each event time.
total_cumulative_hazard_
float
Cumulative hazard at the final event time; the constant risk score.

Notes

Complexity:

  • Fitting: O(n \log n) (sorting dominates).
  • Prediction: O(\log n) per query via binary search.

References

Nelson1969
Nelson, W. (1969). Hazard Plotting for Incomplete Failure Data. Journal of Quality Technology, 1(1), 27-52.
Aalen1978
Aalen, O. (1978). Nonparametric Inference for a Family of Counting Processes. The Annals of Statistics, 6(4), 701-726.

See Also

KaplanMeierEstimator

Product-limit analogue.
python 
>>> from tuiml.algorithms.survival import NelsonAalenEstimator
>>> import numpy as np
>>> na = NelsonAalenEstimator().fit([2, 3, 4, 5], [1, 1, 0, 1])
>>> np.round(na.cumulative_hazard_, 4).tolist()
[0.25, 0.5833, 1.5833]
>>> np.round(na.predict_cumulative_hazard([1, 2, 3, 5]), 4).tolist()
[0.0, 0.25, 0.5833, 1.5833]

Methods

get_parameter_schema (cls) -> Dict[str, Dict[str, Any]]

Return JSON Schema for constructor parameters.

get_capabilities (cls) -> List[str]

Return supported capabilities.

get_complexity (cls) -> str

Return complexity analysis.

get_references (cls) -> List[str]

Return academic citations.

fit (self, time, event) -> 'NelsonAalenEstimator'

Fit the cumulative-hazard estimator.

Parameters
time
array-like of shape (n_samples,)
Observed time (event or censoring).
event
array-like of shape (n_samples,)
Event indicator (1 = event observed, 0 = right-censored).
Returns
self
NelsonAalenEstimator
Fitted estimator.
predict_survival_function (self, times)

Return the estimated survival probability :math:`e^{-\hat{H}(t)}`.

Parameters
times
float or array-like
Time point(s) at which to evaluate :math:`\hat{S}(t)`.
Returns
S
float or np.ndarray
Exponential survival estimate at each query time.
predict_cumulative_hazard (self, times)

Return the Nelson-Aalen cumulative hazard at times.

Parameters
times
float or array-like
Time point(s) at which to evaluate :math:`\hat{H}(t)`.
Returns
H
float or np.ndarray
Cumulative hazard estimate at each query time.
predict_risk (self, X) -> np.ndarray

Return a constant risk score (a non_parametric baseline).

Parameters
X
array-like of shape (n_samples, n_features)
Covariates. Only the number of rows is used.
Returns
risk
np.ndarray of shape (n_samples,)
Constant baseline risk.