simulation

bart_survival.simulation

Simulation engines and synthetic benchmark generators for survival analysis.

Provides: - simulate_survival: Parametric Weibull survival time and hazard curve simulator. - get_x_matrix: Covariate matrix generator with specified discrete and continuous distributions. - simulate_confounded_survival_data: High-level realistic synthetic cohort generator

incorporating confounding, treatment effects, structural support violations (e.g. Inpatient/LOS), and uninformative right censoring without using any real clinical data.

bart_survival.simulation.check_inputs(scale: float | ndarray, shape: float | ndarray, u: float | ndarray = array([0.9]), t: float | ndarray = array([1])) → Tuple[ndarray, ndarray, ndarray, ndarray]

Validates and coerces numerical parameters for Weibull functions.

Parameters:

  • scale (Union[float, np.ndarray]) – Scale parameter.

  • shape (Union[float, np.ndarray]) – Shape parameter.

  • u (Union[float, np.ndarray], optional) – Uniform quantile draw in (0, 1). Defaults to 0.9.

  • t (Union[float, np.ndarray], optional) – Time points. Defaults to 1.

Raises:

ValueError – If any parameter violates domain boundaries (scale > 0, shape > 0, 0 < u < 1, t > 0).

Returns:

Coerced (scale, shape, u, t) arrays.

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

bart_survival.simulation.get_x_matrix(N: int = 100, x_vars: int = 1, VAR_CLASS: List[int] | None = None, VAR_PROB: List[float | None] | None = None, rng: Generator | None = None) → ndarray

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 variables. Defaults to 1.

  • VAR_CLASS (List[int], 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 (List[Optional[float]], optional) – 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 (np.random.Generator, optional) – Random Number Generator from numpy. Defaults to None.

Returns:

2D array of shape (N, x_vars), where rows are observations and columns are variables.

Return type:

np.ndarray

bart_survival.simulation.inverse_weibull_survival(scale: float | ndarray, shape: float | ndarray, u: float | ndarray) → ndarray

Generates event times from an inverse Weibull distribution.

Parameters:

  • scale (Union[float, np.ndarray]) – Scale parameter.

  • shape (Union[float, np.ndarray]) – Shape parameter.

  • u (Union[float, np.ndarray]) – Uniform random draw in (0, 1).

Returns:

Simulated event times of shape (N, 1).

Return type:

np.ndarray

bart_survival.simulation.simulate_confounded_survival_data(N: int = 500, treatment_hr: float = 2.0, censoring_rate: float = 0.25, include_support_violation: bool = True, n_noise_features: int = 5, seed: int | None = 42) → Tuple[DataFrame, Dict[str, Any]]

Generates a realistic synthetic survival dataset for benchmarking and testing.

Models a clinical scenario with: - Baseline confounders: ‘age’ (continuous) and ‘stage’ (ordinal 1, 2, 3). - Primary exposure: ‘inpatient’ (binary 0/1) assigned via logistic propensity. - Structural positivity/support violator: ‘los’ (Length of Stay).

If include_support_violation is True, P(los > 0 | inpatient = 0) = 0 deterministically, creating an off-support boundary that challenges naive PDP and requires Causal G-Computation.

  • Noise features: Uninformative continuous variables to benchmark DART feature selection.

  • Right-censoring: Exponential uninformative censoring calibrated to target censoring_rate.

Strictly synthetic: Uses 100% mathematical formulations and contains NO patient or restricted clinical data.

Parameters:

  • N (int, optional) – Cohort sample size. Defaults to 500.

  • treatment_hr (float, optional) – Ground-truth hazard ratio for primary exposure. Defaults to 2.0.

  • censoring_rate (float, optional) – Target proportion of right-censored subjects. Defaults to 0.25.

  • include_support_violation (bool, optional) – If True, induces structural zero LOS for outpatients. Defaults to True.

  • n_noise_features (int, optional) – Number of uninformative noise features for DART testing. Defaults to 5.

  • seed (Optional[int], optional) – Random seed for reproducibility. Defaults to 42.

Returns:

  • df: DataFrame containing [‘time’, ‘status’, ‘inpatient’, ‘los’, ‘age’, ‘stage’] + noise columns.

  • meta: Metadata dictionary with true parameters, column categories, and true HR.

Return type:

Tuple[pd.DataFrame, Dict[str, Any]]

bart_survival.simulation.simulate_survival(x_mat: ndarray, scale_f: str, shape_f: str = '1', eos: float | None = None, cens_scale: float | None = None, time_scale: float | None = None, true_only: bool = False, rng: Generator | None = None) → Tuple[Dict[str, Any], Dict[str, Any] | None] | Tuple[Dict[str, Any], Dict[str, Any], Dict[str, Any] | None]

Generates survival outcome data from a covariate matrix using a Weibull distribution.

Parameters:

  • x_mat (np.ndarray) – 2D array of the covariate matrix.

  • scale_f (str) – Equation that defines the scale parameter as a combination of covariates (e.g. ‘np.exp(2 + .4*x_mat[:,0])’).

  • shape_f (str, optional) – Equation that defines the shape parameter. Defaults to “1” (constant exponential hazard).

  • eos (float, optional) – End of Study time point (administrative right-censoring truncation). Defaults to None.

  • cens_scale (float, optional) – Scale multiplier for random exponential censoring. Defaults to None.

  • time_scale (float, optional) – Downscaling factor for event and discrete time grid intervals. Defaults to None.

  • true_only (bool, optional) – If True, returns only ground-truth survival/hazard curves. Defaults to False.

  • rng (np.random.Generator, optional) – Random Number Generator for reproducible draws. Defaults to None.

Returns:

If true_only: (sv_dict, sv_scale_dict) Otherwise: (event_dict, sv_dict, sv_scale_dict)

Return type:

Union[Tuple[Dict, Optional[Dict]], Tuple[Dict, Dict, Optional[Dict]]]

bart_survival.simulation.weibull_hazard(scale: float | ndarray, shape: float | ndarray, t: float | ndarray) → ndarray

Calculates hazard rates at specified time points from a Weibull distribution.

Parameters:

  • scale (Union[float, np.ndarray]) – Scale parameter.

  • shape (Union[float, np.ndarray]) – Shape parameter.

  • t (Union[float, np.ndarray]) – Time points to evaluate.

Returns:

2D array of shape (N, len(t)) containing hazard rates.

Return type:

np.ndarray

bart_survival.simulation.weibull_survival(scale: float | ndarray, shape: float | ndarray, t: float | ndarray) → ndarray

Calculates survival probabilities at specified time points from a Weibull distribution.

Parameters:

  • scale (Union[float, np.ndarray]) – Scale parameter.

  • shape (Union[float, np.ndarray]) – Shape parameter.

  • t (Union[float, np.ndarray]) – Time points to evaluate.

Returns:

2D array of shape (N, len(t)) containing survival probabilities.

Return type:

np.ndarray