simulation

Generate a simulated survival datasets

bart_survival.simulation.check_inputs(scale, shape, u=array([0.9]), t=array([1]))

Checks input types. If inputs are not type ndarray then converts to ndarray.

Parameters:

  • scale (ndarray) – sets scale parameter for weibull Survival componenets

  • shape (ndarray) – sets shape parameter for weibull Survival components

  • u (ndarray, optional) – _description_. Defaults to np.array([.9]).

  • t (ndarray, optional) – _description_. Defaults to np.array([1]).

Raises:

Exception – Raises exception if (u<=0 or u>=1), scale<=0, shape<=0, t<=0

Returns:

tuple containing scale, shape, u, t

Return type:

tuple

bart_survival.simulation.get_x_matrix(N=100, x_vars=1, VAR_CLASS=None, VAR_PROB=None, rng=None)

Generates a covariate matrix to use in simulating survival functions and components. If x_vars > length VAR_CLASS, then any additionally generated variables are drawn from a uniform distribution (0,1).

Parameters:

  • N (int, optional) – Number of observations. Defaults to 100.

  • x_vars (int, optional) – Number of variabiables. Defaults to 1.

VAR_CLASS (ndarray, optional): 1D array of integers defining range of numbers in each variable. VAR_CLASS of 2 will generate a binary variable. All other positive integers will draw from a uniform distribution with lower=0, upper=Integer. Defaults to None.

VAR_PROB (ndarray, optional): 1D array defines the probability parameter of binary variables created by VAR_CLASS`==2. All non-binary variables should have a value of `None. Defaults to None. rng (_type_, optional): Random Number Generator from numpy. Used to generate multiple datasets. Defaults to None.

Returns:

2D array, where rows are observations and columns are variables.

Return type:

ndarray

bart_survival.simulation.inverse_weibull_survival(scale, shape, u)

Generates event times from an inverse weibull distribution.

Parameters:

  • scale (ndarray) – Scale parameter.

  • shape (ndarray) – Shape parameter.

  • u (ndarray) – Draw from uniform probability distribution [0,1].

Returns:

Event times given scale, shape, u parameters.

Return type:

ndarray

bart_survival.simulation.simulate_survival(x_mat=None, scale_f=None, shape_f=None, eos=None, cens_scale=None, time_scale=None, true_only=False, rng=None)

Generates survival outcome data from a covariate data.

Using a covariate matrix and a linear equation that defines the linear combination of the covariates, the function will generate a Hazard Rate and Survival probability curve for each observation in the covariate matrix. Additionaly, an event time for each observation. Randomized right censoring and End-of-Study censoring can also be incorporated into the simulated dataset.

Survival times are generated from a Weibull Distribution with a user specified by the evaluation of the shape_f and scale_f parameters.

Increasing the scale will increase the number of time points. Shape controls if the hazard rate is increasing or decreasing.

scale_f must be parameterized as ‘np.exp(…linear equation…)’ this allows appropriate computation of hazard rates. Expected HR can be computed through np.power(np.exp(Beta_x), shape).

A few documents that demonstarte the weibull distribution and function in Survival Analysis can be found here:

https://wilmarigl.de/wp-content/uploads/2018/01/tutorial_hr_parsurvmodels.pdf https://www.itl.nist.gov/div898/handbook/eda/section3/eda3668.htm

Parameters:

  • x_mat (ndarray, optional) – 2D array of the covariate matrix. Defaults to None.

  • scale_f (string, optional) – Equation that defines the scale parameter as a combination the covariate matrix. Defaults to None.

  • shape_f (string, optional) – Equation that defines the shape parameter as a combination of the covariate matrix. Combination with the covariate matrix is not always needed and will provide a Survival Components that follow a proportional hazard. Defaults to None.

  • eos (int, optional) – End of Study time point. Allows truncation of time-points as full-stop right censoring for generated event times. Defaults to None.

  • cens_scale (int, optional) – Incorporates uninformative censoring into the generated event times. Defaults to None.

  • time_scale (int, optional) – Downscales event times and Survival component times to value. Defaults to None.

  • true_only (bool, optional) – If True returns only the Survival components and not the generated event times. Defaults to False.

  • rng (_type_, optional) – Random Number Generator to generate sequential survival datasets. Defaults to None.

Returns:

Tuble of dictionaries containing the various survival components.

Return type:

tuple

bart_survival.simulation.weibull_hazard(scale, shape, t)

Generates hazard rates at time from weibull distribution.

Parameters:

  • scale (ndarray) – Scale parameter.

  • shape (ndarray) – Shape parameter.

  • t (ndarray) – Time points to generate hazard rates.

Returns:

2D ndarray that contains survival probabilites for t.shape[0] times points and scale.shape[0] observations.

Return type:

ndarray

bart_survival.simulation.weibull_survival(scale, shape, t)

Generates survival probabilites from weibull distribution.

Parameters:

  • scale (ndarray) – Scale parameter.

  • shape (ndarray) – Shape parameter.

  • t (ndarray) – Time points to generate survival probabilities.

Returns:

2D ndarray that contains survival probabilites for t.shape[0] times points and scale.shape[0] observations.

Return type:

ndarray