survivalgpu.WCESurvivalAnalysis
- class survivalgpu.WCESurvivalAnalysis(*, cutoff, nknots=1, order=3, constrained=None, criterion='bic', survival_model=None, dtype=<class 'numpy.float64'>, device=None, nbootstraps=None, batchsize=None)
Bases:
object- __init__(*, cutoff, nknots=1, order=3, constrained=None, criterion='bic', survival_model=None, dtype=<class 'numpy.float64'>, device=None, nbootstraps=None, batchsize=None)
Weighted Cumulative Exposure Model that combines B-spline time-varying features with a CoxPH analysis.
The total number of degrees of freedom for the risk function (i.e. WCE covariates) is equal to:
nknots + order + 1 if constrained is None, nknots + 2 if constrained is “left” or “right”.
- Parameters:
cutoff (int) – Size of the time window for the risk function.
nknots (int or list of int) – Number of knots for the B-splines. If several candidates are given, one model is fitted per candidate and the one that minimizes the information criterion is selected; with nbootstraps, this selection is repeated in every bootstrap replicate (see fit()).
order (int) – Order of the B-splines used to model the risk function. order == 0 corresponds to a piecewise constant risk function, order == 1 corresponds to a piecewise linear risk function, order == 3 corresponds to a piecewise cubic risk function.
criterion (str) – Which information criterion to report in self.info_criterion_: “aic” (penalty = 2 per degree of freedom) or “bic” (penalty = log(n_events) per degree of freedom). Defaults to “bic”. The BIC is the one of Volinsky and Raftery (2000).
constrained (str or None) –
Whether the B-splines should be constrained. Defaults to None (i.e. no constraint).
Other options are:
- ”Left” or “L”: the drug has no immediate effect on the risk.
We remove features that correspond to basis functions that have a non-zero value or derivative on the “left” of the domain, i.e. around the exposure time. This is useful to model a risk function that has no “immediate” impact.
- ”Right” or “R”: the drug has no effect on the risk around the cutoff time.
We remove features that correspond to basis functions that have a non-zero value or derivative on the “right” of the domain, i.e. around the “exposure+cutoff” time. This is useful to model a risk function that vanishes “at infinity”.
survival_model – Estimator that will be used to perform a risk analysis from the WCE covariates. For now, we only support the CoxPHSurvivalAnalysis model.
dtype – Either np.float32 or np.float64. Defaults to np.float64.
device – Device (e.g. “cpu” or “cuda”) on which to run the computations. Defaults to the best available device.
nbootstraps (int, optional) – Number of bootstrap resamples to fit, in addition to the main model. Defaults to None (i.e. no bootstrapping).
batchsize (int, optional) – Number of bootstrap resamples to process at once on the GPU. Defaults to None, i.e. all the bootstraps are processed at once.
Methods
HR(vecnum, vecdenom[, level])Computes the Hazard Ratio between two exposure scenarios.
__init__(*, cutoff[, nknots, order, ...])Weighted Cumulative Exposure Model that combines B-spline time-varying features with a CoxPH analysis.
fit(*, dose, stop, start, event, patient[, ...])Fits the WCE model to the data and stores the results as attributes.
set_non_negative_int(value, name)Attributes
Compute the "total risk area under the curve" that is associated to the B-spline basis functions.
Samples the B-spline basis functions on the interval [0, cutoff-1].
The candidate nknots values to fit and select from, always as a tuple.
- HR(vecnum, vecdenom, level=0.95)
Computes the Hazard Ratio between two exposure scenarios.
Each scenario is a vector of doses in reverse chronological order: the first value is the dose at the current time, the second the dose one time unit earlier, and so on. A vector longer than
cutoffis truncated, and a shorter one is padded with zeros (no exposure further back in time).- Parameters:
vecnum (array-like of float) – doses of the scenario of interest (numerator of the HR).
vecdenom (array-like of float) – doses of the reference scenario (denominator of the HR).
level (float, optional) – confidence level of the bootstrap interval, used only if the model was fitted with bootstrap. Defaults to 0.95.
- Returns:
dict –
{"HR": hr}with the Hazard Ratio as a float. If the model was fitted with bootstrap, also"CI_lower"and"CI_upper": the bounds of the bootstrap percentile interval atlevel.
- property atom_areas
Compute the “total risk area under the curve” that is associated to the B-spline basis functions.
- property atoms
Samples the B-spline basis functions on the interval [0, cutoff-1].
- property constrained
- property cutoff
- fit(*, dose, stop, start, event, patient, covariates=None, strata=None, batch=None, init=None)
Fits the WCE model to the data and stores the results as attributes.
- Parameters:
dose ((I,) float64 array) – drug dose received during each interval.
stop ((I,) int64 array) – end time of each interval.
start ((I,) int64 array) – start time of each interval. Currently, only unit-length intervals (stop == start + 1) are supported.
event ((I,) int64 array) – 1 if the interval ends with an event (death), 0 if it is censored.
patient ((I,) int64 array) – patient id for each interval.
covariates ((I,C) float64 array, optional) – additional (non-WCE) covariates. Defaults to None, i.e. only the WCE features are used.
strata ((I,) int64 array, optional) – stratum id for each interval. Defaults to a single stratum for all patients.
batch ((I,) int64 array, optional) – batch id for each interval. Independent WCE models are fitted for each batch.
init ((C + n_atoms,) float64 array, optional) – initial values for the coefficients. Defaults to zeros.
Results are stored as attributes:
knots_,coef_,WCE_coef_,risk_function_,std_,SED_,means_,score_,loglik_,loglik_init_,sctest_init_,hessian_,imat_,iter_,n_events_,info_criterion_, and (if nbootstraps is set)bootstrap_coef_,bootstrap_risk_functions_and, only when a single nknots value is given,bootstrap_WCE_coef_.When nknots is a list of candidates, one model is fitted per candidate and the flat attributes above reflect whichever one minimizes
info_criterion_(see alsobest_index_,best_nknots_). Every candidate’s own results are kept in parallel*_grid_attributes:knots_grid_,coef_grid_,WCE_coef_grid_,std_grid_,SED_grid_,risk_function_grid_,loglik_grid_,info_criterion_grid_.If, in addition, nbootstraps is set, every bootstrap replicate independently selects its own best candidate by information criterion on its own resampled data (all candidates share the same resamples, drawn once):
bootstrap_coef_andbootstrap_risk_functions_reflect that per-replicate winner, andbootstrap_best_index_,bootstrap_best_nknots_record which candidate won each replicate. The full per-candidate bootstrap grid is kept inbootstrap_coef_grid_,bootstrap_WCE_coef_grid_,bootstrap_risk_functions_grid_,bootstrap_loglik_grid_,bootstrap_info_criterion_grid_, plus the (candidate-invariant)bootstrap_n_events_.
- property n_atoms
- property nknots
- property nknots_candidates
The candidate nknots values to fit and select from, always as a tuple.
- property order
- set_non_negative_int(value, name)