Gradient-boosted cumulative incidence model for competing risks.
Usage
Builds an ensemble of regression trees that estimates the cause-specific cumulative incidence functions (CIFs) and the any-event survival function via multi-class softmax gradient boosting. At each boosting iteration, random time horizons are sampled and concatenated as an extra input feature. IPCW weights correct for right censoring. The result is a flexible, nonparametric competing-risks model that learns CIFs directly from the data.
n_estimators: int = 100Number of boosting iterations. Each iteration fits one tree per class (event type + survival).
learning_rate: float = 0.05Shrinkage applied to each tree’s contribution.
max_depth: int = 3Maximum depth of each regression tree.
min_samples_leaf: int = 10Minimum number of samples required in each leaf.
subsample: float = 1.0Fraction of the training rows sampled (without replacement) per iteration.
max_features: Any = NoneFeatures considered per split: None (all), "sqrt", "log2", an int, or a float.
n_time_grid_steps: int = 100Number of time points in the default prediction grid. The grid is built from quantiles of observed event times.
hard_zero_fraction: float = 0.1Fraction of sampled time horizons forced to zero at each iteration, ensuring the model learns zero incidence at t = 0.
n_horizons_per_observation: int = 3Number of independent time horizons sampled per subject at each iteration. Higher values give more stable gradients at the cost of larger per-iteration datasets.
epsilon_censoring: float = 0.05Floor for censoring survival probabilities to prevent extreme IPCW weights.
random_state: Any = Nonenumpy.random.Generator for reproducibility.
Fit to synthetic competing-risks data and predict cumulative incidence:
import greenwood as gw
sim = gw.simulate_competing_risks(n=500, n_causes=2, n_covariates=3, seed=42)
sb = gw.SurvivalBoost(n_estimators=50, learning_rate=0.1, max_depth=3, random_state=0)
sb.fit(sim.surv, covariates=sim.covariates)
sbSurvivalBoost (50 rounds, learning_rate=0.1, max_depth=3)
n = 500, events = 296, causes = 2, features = 3| Name | Description |
|---|---|
| fit() | Fit the gradient-boosted cumulative incidence model. |
| predict_cumulative_incidence() | Predict cause-specific cumulative incidence functions. |
| predict_proba() | Predict class probabilities at a single time horizon. |
| predict_survival_function() | Predict the any-event survival function. |
Fit the gradient-boosted cumulative incidence model.
Usage
surv: Surv | Outcome | strA multi-state Surv response, built with gw.Surv() and a categorical event. An Outcome or a formula string such as "Surv(time, factor(cause, c(0, 1, 2), c('censor', 'pcm', 'death'))) ~ age" is also accepted, with its columns read from data. The right-hand side sets covariates.
covariates: Any = NoneA dataframe, a 2-D array, or a right-hand-side formula string evaluated against data. A list of column names in data also works.
data: Any = Nonecovariates. When surv is an Outcome or a formula, rows with a missing value in any column used are dropped before fitting. Covariate formula strings and lists of column names are also resolved here.
selfFit a boosted CIF model to synthetic competing-risks data and inspect the result. The model learns a separate tree per class at each round:
import greenwood as gw
sim = gw.simulate_competing_risks(
n=500, n_causes=2, n_covariates=3, seed=42
)
sb = gw.SurvivalBoost(
n_estimators=50, learning_rate=0.1, max_depth=3, random_state=0
).fit(sim.surv, covariates=sim.covariates)
sbSurvivalBoost (50 rounds, learning_rate=0.1, max_depth=3)
n = 500, events = 296, causes = 2, features = 3Predict cause-specific cumulative incidence functions.
Usage
newdata: Any = NoneCovariates for prediction. A dataframe, 2-D array, or formula string. None is not supported (training covariates are not cached). A data frame may also hold other columns. The covariates are picked out by name and coded as they were at fit time, so the frame the model was fit on can be passed as is.
times: Any = NoneTime points at which to evaluate the CIFs. Defaults to the training-time grid.
format: str | None = NoneNone, returns a 3-D NumPy array of shape (n_subjects, n_events, n_times). Event index 0 is the survival probability (complement of all CIFs). Indices 1..K correspond to cause-specific CIFs. When a DataFrame backend name is given (e.g., "polars"), returns a long-format table with columns time, cause, subject, and probability.
numpy.ndarray or DataFramePredict class probabilities at a single time horizon.
Usage
Returns an array of shape (n_subjects, n_classes) where column 0 is the probability of remaining event-free and columns 1..K are cause-specific CIFs at time_horizon.
newdata: AnyCovariates for prediction. A data frame may also hold other columns. The covariates are picked out by name and coded as they were at fit time, so the frame the model was fit on can be passed as is.
time_horizon: float numpy.ndarray(n_subjects, n_classes).
Predict the any-event survival function.
Usage
newdata: Any = NoneCovariates for prediction. A data frame may also hold other columns. The covariates are picked out by name and coded as they were at fit time, so the frame the model was fit on can be passed as is.
times: Any = NoneTime points at which to evaluate. Defaults to the training-time grid.
format: str | None = NoneNone returns a 2-D NumPy array of shape (n_subjects, n_times).
numpy.ndarray or DataFrame