Weighted Cumulative Exposure (WCE)

WCESurvivalAnalysis models a time-varying drug exposure by combining it with a bank of B-spline basis functions (“atoms”) over a cutoff-long time window, then fits a Cox model on top of the resulting features (plus any extra covariates). The fitted risk function (model.risk_function_) describes how much a dose received u days ago still contributes to the current risk.

A simulated dataset

We simulate a single time-varying dose covariate that follows a “bi_linear_scenario” risk shape (risk decreases linearly with time-since-dose over the cutoff window) with a known target hazard ratio, plus a constant sex covariate to illustrate mixing WCE and standard covariates in one model. Unlike the CoxPH dataset, this one is not compressed, since WCESurvivalAnalysis currently requires unit-length (start, start+1] intervals.

import numpy as np
from survivalgpu import ConstantCovariate, WCECovariate, simulate_dataset

WCE_TRUE_HR = 3.0

dose = WCECovariate(
    name="dose", values=[1, 1.5, 2, 2.5, 3],
    scenario_name="bi_linear_scenario", HR_target=WCE_TRUE_HR,
)
sex = ConstantCovariate(name="sex", values=[0, 1], weights=[1, 1], coef=0.5)

df = simulate_dataset(
    max_time=200, n_patients=300, list_covariates=[dose, sex], compress=False, seed=1
)

dose_arr = df["dose"].to_numpy(dtype=np.float64)
covariates = df[["sex"]].to_numpy(dtype=np.float64)
start = df["start"].to_numpy(dtype=np.int64)
stop = df["stop"].to_numpy(dtype=np.int64)
event = df["events"].to_numpy(dtype=np.int64)
patient = df["patients"].to_numpy(dtype=np.int64)

Fitting the model

from survivalgpu import WCESurvivalAnalysis

model = WCESurvivalAnalysis(
    cutoff=180,      # size of the exposure time window (in days)
    nknots=1,        # number of interior knots for the B-splines
    order=3,         # cubic B-splines
    constrained="right",  # risk vanishes at the cutoff
    device="cpu",    # use device="cuda" for a GPU speedup if available
)

model.fit(dose=dose_arr, stop=stop, start=start, event=event, patient=patient, covariates=covariates)

print("Coefficient for 'sex':", model.coef_[0, 0])
print("risk_function_ shape (n_batch, cutoff):", model.risk_function_.shape)
print("Information criterion (BIC by default):", model.info_criterion_[0])
/opt/hostedtoolcache/Python/3.11.17/x64/lib/python3.11/site-packages/survivalgpu/wce.py:303: UserWarning: The given NumPy array is not writable, and PyTorch does not support non-writable tensors. This means writing to this tensor will result in undefined behavior. You may want to copy the array to protect its data or make it writable before converting it to a tensor. This type of warning will be suppressed for the rest of this program. (Triggered internally at /__w/pytorch/pytorch/torch/csrc/utils/tensor_numpy.cpp:208.)
  patient = torch.from_numpy(patient).to(self.device)
Coefficient for 'sex': 0.4587665582356777
risk_function_ shape (n_batch, cutoff): torch.Size([1, 180])
Information criterion (BIC by default): 2124.2666825838055

Results are stored as attributes on model: knots_, coef_, WCE_coef_, risk_function_, std_, SED_, means_, score_, loglik_, n_events_, info_criterion_ and more — see WCESurvivalAnalysis for the full list.

Choosing the number of knots

The number of interior knots is usually not known in advance. Instead of a single value, nknots accepts a list of candidates: one model is fitted per candidate, and the one that minimizes the information criterion is selected (criterion="bic" by default, or criterion="aic"). All the flat attributes (coef_, risk_function_, loglik_, …) then describe that selected model, while every candidate’s results are kept in parallel *_grid_ attributes.

model = WCESurvivalAnalysis(
    cutoff=180, nknots=[1, 2, 3], order=3, constrained="right", device="cpu",
)
model.fit(dose=dose_arr, stop=stop, start=start, event=event, patient=patient, covariates=covariates)

for nknots, loglik, bic in zip(
    model.nknots_candidates, model.loglik_grid_[:, 0], model.info_criterion_grid_[:, 0]
):
    print(f"nknots={nknots}: loglik={loglik:.2f}, BIC={bic:.2f}")
print("Selected number of knots:", model.best_nknots_[0])
nknots=1: loglik=-1051.21, BIC=2124.27
nknots=2: loglik=-1051.00, BIC=2129.32
nknots=3: loglik=-1050.70, BIC=2134.18
Selected number of knots: 1

Comparing exposure profiles

model.HR() computes the hazard ratio between two dose “profiles” over the cutoff window — for example, a constant dose of 1 for the first 30 days versus no exposure at all:

exposed = np.zeros(180, dtype=np.int64)
exposed[:30] = 1
unexposed = np.zeros(180, dtype=np.int64)

hr = model.HR(exposed, unexposed)
print(f"HR(30 days of exposure vs. none) = {hr['HR']:.3f}")
print(f"(dataset was simulated with a target HR of {WCE_TRUE_HR})")
HR(30 days of exposure vs. none) = 2.369
(dataset was simulated with a target HR of 3.0)

Bootstrap resampling

Just like CoxPHSurvivalAnalysis, WCESurvivalAnalysis accepts nbootstraps/batchsize: the model is fitted once on the full data and nbootstraps times on patient-level resamples.

When nknots is a list of candidates, the number of knots is selected again in every bootstrap replicate:

  1. the resamples are drawn once and shared by all the candidates, so that they are compared on exactly the same data;

  2. every candidate is fitted on every resample;

  3. each replicate keeps the candidate that minimizes the information criterion computed on its own resampled data (for the BIC, with that replicate’s own number of events).

The bootstrap distribution therefore reflects the uncertainty on the choice of the number of knots, and not only the uncertainty on the coefficients for a fixed, pre-selected number of knots.

boot_model = WCESurvivalAnalysis(
    cutoff=180, nknots=[1, 2, 3], order=3, constrained="right",
    device="cpu", nbootstraps=100, batchsize=50,
)
boot_model.fit(dose=dose_arr, stop=stop, start=start, event=event, patient=patient, covariates=covariates)

print("Selected number of knots on the full data:", boot_model.best_nknots_[0])
values, counts = np.unique(boot_model.bootstrap_best_nknots_, return_counts=True)
for nknots, count in zip(values, counts):
    print(f"nknots={nknots} selected in {count} / {boot_model.nbootstraps} replicates")
Selected number of knots on the full data: 1
nknots=1 selected in 85 / 100 replicates
nknots=2 selected in 13 / 100 replicates
nknots=3 selected in 2 / 100 replicates

bootstrap_coef_ (covariates) and bootstrap_risk_functions_ hold, for every replicate, the results of the candidate selected for that replicate. The results of every candidate on every replicate are kept in bootstrap_coef_grid_, bootstrap_WCE_coef_grid_, bootstrap_risk_functions_grid_, bootstrap_loglik_grid_ and bootstrap_info_criterion_grid_. Since different replicates may select spline bases of different sizes, bootstrap_WCE_coef_ is only available when a single nknots value is given.

model.HR() automatically detects that bootstrapping was requested and returns a percentile confidence interval for the hazard ratio alongside the point estimate, using each replicate’s selected risk function:

print("bootstrap_risk_functions_ shape (nbootstraps, n_batch, cutoff):", boot_model.bootstrap_risk_functions_.shape)

hr = boot_model.HR(exposed, unexposed, level=0.95)
print(f"HR(30 days of exposure vs. none) = {hr['HR']:.3f}")
print(f"95% bootstrap CI: [{hr['CI_lower']:.3f}, {hr['CI_upper']:.3f}]")
bootstrap_risk_functions_ shape (nbootstraps, n_batch, cutoff): torch.Size([100, 1, 180])
HR(30 days of exposure vs. none) = 2.369
95% bootstrap CI: [1.912, 2.912]

With a single value such as nknots=1, there is nothing to select: every replicate uses that number of knots, as in a standard bootstrap.

References

  • Sylvestre MP, Abrahamowicz M (2009). Flexible modeling of the cumulative effects of time-dependent exposures on the hazard. Statistics in Medicine, 28(27), 3437–3453. doi:10.1002/sim.3701

  • Sylvestre M (2025). WCE: Weighted Cumulative Exposure Models, the WCE R package. doi:10.32614/CRAN.package.WCE. The reference implementation of the method: survivalGPU’s WCE model follows its conventions, and its results are tested against it.

Going further

Full API reference: WCESurvivalAnalysis.