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

atom_areas

Compute the "total risk area under the curve" that is associated to the B-spline basis functions.

atoms

Samples the B-spline basis functions on the interval [0, cutoff-1].

constrained

cutoff

n_atoms

nknots

nknots_candidates

The candidate nknots values to fit and select from, always as a tuple.

order

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 cutoff is 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 at level.

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 also best_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_ and bootstrap_risk_functions_ reflect that per-replicate winner, and bootstrap_best_index_, bootstrap_best_nknots_ record which candidate won each replicate. The full per-candidate bootstrap grid is kept in bootstrap_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)