API Reference / algorithms / survival /

cox_ph.py

Cox proportional_hazards model with partial-likelihood estimation.

Classes

CoxPHSurvival

class algorithms.survival.cox_ph.CoxPHSurvival(Survival)

Cox proportional_hazards model.

The semiparametric workhorse of survival analysis. It models the hazard of subject i as

h(t \mid x_i) = h_0(t) \exp(x_i^T \beta)

where h_0(t) is an unspecified baseline hazard and \beta are covariate effects. A positive coefficient means the covariate raises the hazard and therefore shortens expected survival.

Constructor 
__init__(
    self,
    penalty: Optional[str] = 'l2',
    alpha: float = 0.0,
    tol: float = 1e-06,
    max_iter: int = 100,
)

Overview

  1. Order subjects by observed time, descending.
  2. Maximise the partial likelihood in \beta with Newton-Raphson
(optional L2 penalty).
  1. Estimate the baseline hazard via the Breslow estimator and expose the
corresponding baseline survival function.

Theory

For right-censored data the partial log-likelihood is

\ell(\beta) = \sum_{i: \delta_i = 1} \left[ x_i^T \beta - \log \sum_{j: t_j \geq t_i} \exp(x_j^T \beta) \right]

whose gradient and Hessian are accumulated over risk sets R(t_i) = \{j : t_j \geq t_i\}:

\nabla \ell = \sum_{i: \delta_i = 1} \left( x_i - \frac{\sum_{j \in R(t_i)} x_j e^{x_j^T \beta}} {\sum_{j \in R(t_i)} e^{x_j^T \beta}} \right)

With L2 regularisation, \ell(\beta) - \frac{\alpha}{2}\|\beta\|^2 is maximised, which shrinks coefficients toward zero. The baseline hazard is

\hat{h}_0(t_j) = \frac{d_j}{\sum_{i \in R(t_j)} \exp(x_i^T \beta)}

and \hat{S}_0(t) = \exp\!\left(-\sum_{t_j \leq t} \hat{h}_0(t_j)\right).

Parameters

penalty
str = "l2"
Regularisation type. "l2" adds a ridge penalty; None fits the unpenalised partial likelihood.
alpha
float = 0.0
Regularisation strength (ignored unless penalty="l2").
tol
float = 1e-6
Newton-Raphson convergence tolerance on the max coefficient change.
max_iter
int = 100
Maximum Newton-Raphson iterations.

Attributes

coefficients_
np.ndarray of shape (n_features,)
Fitted covariate effects (log hazard ratios).
baseline_times_
np.ndarray of shape (n_events,)
Sorted unique event times.
baseline_hazard_
np.ndarray of shape (n_events,)
Breslow baseline hazard increments.
baseline_cumulative_hazard_
np.ndarray of shape (n_events,)
Cumulative baseline hazard.
baseline_survival_
np.ndarray of shape (n_events,)
Baseline survival :math:`\exp(-H_0(t))`.
n_features_in_
int
Number of features seen during fit().

Notes

Complexity:

  • Fitting: O(I \cdot (n p + n p^2)) for I iterations,
dominated by the per-risk-set Hessian accumulation.
  • Prediction: O(p) per sample.
When to use CoxPHSurvival:
  • When the proportional_hazards assumption is reasonable.
  • When you need interpretable coefficients rather than pure predictive power.

References

Cox1972
Cox, D.R. (1972). Regression Models and Life-Tables. Journal of the Royal Statistical Society, Series B, 34(2), 187-220. DOI: 10.1111/j.2517-6161.1972.tb00899.x
Breslow1972
Breslow, N.E. (1972). Discussion of Cox (1972). Journal of the Royal Statistical Society, Series B, 34(2), 216-217.

See Also

KaplanMeierEstimator

Non-parametric baseline.
RandomSurvivalForest

Non-linear ensemble.
python 
>>> from tuiml.algorithms.survival import CoxPHSurvival
>>> import numpy as np
>>> # A single binary covariate: group 1 always fails first.
>>> X = np.array([[1.], [1.], [1.], [0.], [0.], [0.]])
>>> time = np.array([1., 2., 3., 4., 5., 6.])
>>> event = np.ones(6)
>>> cox = CoxPHSurvival().fit(X, time, event)
>>> bool(cox.coefficients_[0] > 0)
True

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, X, time, event) -> 'CoxPHSurvival'

Fit the model by maximising the (penalised) partial likelihood.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Covariate matrix.
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
CoxPHSurvival
Fitted estimator.
predict_risk (self, X) -> np.ndarray

Return the linear predictor :math:`X \beta` for each sample.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Covariates.
Returns
risk
np.ndarray of shape (n_samples,)
Linear predictor. Higher values mean higher hazard and an earlier expected event.
predict_cumulative_hazard (self, X, times=None) -> np.ndarray

Return the predicted cumulative hazard for each sample.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Covariates.
times
array-like
Time point(s) at which to evaluate the hazard. Defaults to the fitted baseline_times_.
Returns
H
np.ndarray of shape (n_samples, n_times)
:math:`H_i(t) = H_0(t) \exp(x_i^T \beta)`.
predict_survival_function (self, X, times=None) -> np.ndarray

Return the predicted survival function for each sample.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Covariates.
times
array-like
Time point(s) at which to evaluate the survival function. Defaults to the fitted baseline_times_.
Returns
S
np.ndarray of shape (n_samples, n_times)
:math:`S_i(t) = \exp(-H_i(t))`.