API Reference / algorithms / survival /

random_survival_forest.py

Random survival forest: an ensemble of censoring-aware survival trees.

Classes

RandomSurvivalForest

class algorithms.survival.random_survival_forest.RandomSurvivalForest(Survival)

Random survival forest: an ensemble of survival trees.

An ensemble of regression trees adapted to right-censored data. Each tree partitions the covariate space into homogeneous leaves; a leaf's risk is its Nelson-Aalen cumulative hazard evaluated at a fixed horizon, and the ensemble risk is the average leaf hazard across trees.
Constructor 
__init__(
    self,
    n_estimators: int = 100,
    max_depth: Optional[int] = None,
    min_samples_split: int = 2,
    min_samples_leaf: int = 3,
    max_features = 'sqrt',
    random_state: Optional[int] = None,
)

Overview

  1. For each tree, bootstrap-sample the data and (optionally) subsample the
features.
  1. Fit a DecisionTreeRegressor to the
observed times, which yields a variance-reduction partition of the covariate space (a cheap stand-in for the log-rank split of full RSF).
  1. Route the full training set through the tree and, per leaf, compute the
Nelson-Aalen cumulative hazard of the leaf's (time, event) pairs, evaluated at a common horizon \tau.
  1. predict_risk routes a sample to one leaf per tree and averages the
leaf hazards.

Theory

Within a leaf holding samples \{(t_i, \delta_i)\} the leaf risk is the Nelson-Aalen cumulative hazard up to a fixed horizon \tau (the median training event time):

\hat{H}_{\text{leaf}}(\tau) = \sum_{j: t_j \leq \tau} \frac{d_j}{n_j}.

Evaluating at an intermediate \tau — rather than at \infty — is what makes the leaf risk sensitive to when events happen: a leaf whose members fail early has accumulated most of its hazard by \tau, whereas a leaf whose members fail late is still close to zero. For a sample x landing in leaf \ell_t(x) of tree t, the ensemble risk is

\text{risk}(x) = \frac{1}{T} \sum_{t=1}^{T} \hat{H}_{\ell_t(x)}(\tau).

A higher score means an earlier expected event, matching the Survival convention.

Parameters

n_estimators
int = 100
Number of trees in the forest.
max_depth
int or None = None
Maximum depth of each tree (None = unlimited).
min_samples_split
int = 2
Minimum samples to split an internal node.
min_samples_leaf
int = 3
Minimum samples required in a leaf (kept above 1 so every leaf has a stable hazard estimate).
max_features
int, float, str or None = "sqrt"
Features to consider per tree. "sqrt", "log2", an int, a float fraction, or None for all features.
random_state
int or None = None
Seed for reproducibility.

Attributes

estimators_
list of DecisionTreeRegressor
The fitted base trees.
leaf_hazards_
list of dict
Mapping from leaf node index to cumulative hazard at horizon_, one per tree.
feature_subsets_
list of np.ndarray
Feature columns used by each tree.
max_features_
int
Resolved number of features per tree.
horizon_
float
Time horizon at which leaf hazards are evaluated (median training event time).
n_features_in_
int
Number of features seen during fit().

Notes

Complexity:

  • Fitting: O(T \cdot n \cdot p \cdot n \log n) for the base
trees plus O(T \cdot n \cdot k) for leaf hazards.
  • Prediction: O(T \cdot d) per sample.
When to use RandomSurvivalForest:
  • When the proportional-hazards assumption of Cox fails.
  • When covariate effects are non_linear or interactive.
  • Interpretability and coefficient inference are not required.

References

Ishwaran2008
Ishwaran, H., Kogalur, U.B., Blackstone, E.H. and Lauer, M.S. (2008). Random Survival Forests. The Annals of Applied Statistics, 2(3), 841-860. DOI: 10.1214/08-AOAS169
Breiman2001
Breiman, L. (2001). Random Forests. Machine Learning, 45(1), 5-32.

See Also

CoxPHSurvival

Semiparametric baseline.
NelsonAalenEstimator

Leaf hazard source.
python 
>>> from tuiml.algorithms.survival import RandomSurvivalForest
>>> import numpy as np
>>> rng = np.random.RandomState(0)
>>> X = rng.normal(size=(40, 2))
>>> time = np.exp(X[:, 0]) + rng.uniform(0, 1, size=40)
>>> event = np.ones(40)
>>> rsf = RandomSurvivalForest(n_estimators=10, random_state=0).fit(X, time, event)
>>> rsf.predict_risk(X[:3]).shape
(3,)

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) -> 'RandomSurvivalForest'

Fit the forest on right-censored survival data.

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
RandomSurvivalForest
Fitted estimator.
predict_risk (self, X) -> np.ndarray

Return the mean leaf cumulative hazard across trees.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Covariates.
Returns
risk
np.ndarray of shape (n_samples,)
Ensemble risk. Higher values mean an earlier expected event.