RealSurvSim

RealSurvSim is an R package that provides a variety of methods for simulating survival (time-to-event) datasets. It is particularly useful for survival analysis applications in research and simulation studies. The package includes both non-parametric (kernel density estimation), parametric, and bootstrap-based simulation approaches for generating realistic time-to-event data.

Features

• Parametric Simulation: Fit a distribution (e.g., exponential, Weibull, log-logistic, mixture distributions) to existing data and generate new samples from the fitted distribution.
• Kernel Density Simulation: Non-parametric simulation via kernel density estimation, using an accept-reject approach.
• Bootstrap Methods:
  • Conditional Bootstrap (cond): Splits event and censoring times, then resamples to preserve the observed event/censoring ratio.
  • Case Resampling (case): Simple random resampling of entire observations with replacement.
• Flexible Group/Strata Handling: Simulate data separately by group while preserving group sizes or allowing user-specified sample sizes.

Installation

1. From Source

If you have downloaded or cloned this repository:

# Install devtools if you don't already have it
install.packages("devtools")

# Then, from the root of the package directory:
devtools::install_github()

Dependencies

This package uses several R libraries for density estimation, distribution fitting, and survival analysis. They will be automatically installed (if not already present) when installing RealSurvSim. Key dependencies include:

• kdensity (for kernel density estimation)
• fitdistrplus (for fitting various distributions to data)
• flexsurv (for Gompertz and other survival distributions)
• univariateML (for maximum-likelihood estimation of some distributions, e.g., inverse gamma)
• actuar (for distributions like log-logistic and inverse gamma)
• survival (core survival analysis functionality)

Usage

Below is an overview of the core functions and some example usages. For detailed information on parameters and return values, refer to the function documentation.

Core Functions

1. data_simul_KDE(orig_vals, n = NULL, kernel = "gaussian")
   Simulates data via kernel density estimation from a numeric vector of original values.

   • Parameters:
     • orig_vals: Numeric vector of original data values.
     • n: Number of observations to simulate (defaults to the length of orig_vals).
     • kernel: The kernel to use for KDE (currently supports "gaussian").
   • Returns: A numeric vector of simulated values.

2. data_simul_Estim(orig_vals, n = NULL, distrib = "exp")
   Fits a specified parametric distribution to orig_vals and draws new samples from the fitted distribution.

   • Supported distributions include: "inverse_gamma", "gompertz", "llogis", "gumbel", "myMix", "exp".

3. data_simul_bootstr(dat, n = NULL, type = "cond")
   Bootstrap-based simulation of event and censoring times.

   • Parameters:
     • dat: Dataframe containing at least V1 (time) and V2 (censor indicator, 0/1).
     • n: Number of observations to sample. Defaults to the same size as dat.
     • type: "cond" for conditional bootstrap or "case" for case-resampling.
   • Returns: A resampled or reconstructed dataframe containing simulated times and censor indicators.

4. RealSurvSim(dat, col_time, col_status, col_group, reps = 10000, random_seed = 123, n = NULL, simul_type, distribs = c("exp", "exp", "exp", "exp"))
   The main wrapper function for simulating multiple survival datasets using one of four approaches:

   • "cond": Conditional bootstrap

   • "case": Case resampling

   • "distr": Parametric distribution-based simulation

   • "KDE": Kernel density estimation-based simulation

   • Parameters:

     • dat: Original (or reconstructed) dataset with time, status, and group columns.
     • col_time: Column name/index for time.
     • col_status: Column name/index for censoring indicator (1=event, 0=censored).
     • col_group: Column name/index for treatment/group identifier.
     • reps: Number of datasets to simulate (default 10,000).
     • random_seed: Random seed (default 123) for reproducibility.
     • n: Vector specifying sample sizes per group (optional).
     • simul_type: Single string specifying the simulation method ("cond", "case", "distr", "KDE").
     • distribs: Which distributions to use if simul_type = "distr".

   • Returns:
     A list containing multiple simulated datasets (one for each repetition). Each dataset is a data.frame with columns V1 (time), V2 (status), and V3 (group).

Examples

Below are brief examples demonstrating how to simulate data. In practice, replace the placeholders (example_data, "time", etc.) with your actual dataset and column names.

library(RealSurvSim)

# Example dataset construction (for demonstration):
set.seed(123)
example_data <- data.frame(
  time = rexp(100, rate = 0.1),            # Times
  status = sample(0:1, 100, replace = TRUE), # 0=censored, 1=event
  group = sample(0:1, 100, replace = TRUE)   # Two groups, 0 or 1
)

# 1. Kernel Density Estimation Simulation
sim_kde <- RealSurvSim(
  dat = example_data,
  col_time   = "time",
  col_status = "status",
  col_group  = "group",
  reps       = 5,            # Simulate 5 datasets
  simul_type = "KDE"         # Use KDE-based simulation
)
str(sim_kde$datasets)  # Check the structure of generated datasets

# 2. Parametric Distribution Simulation
sim_distr <- RealSurvSim(
  dat = example_data,
  col_time   = "time",
  col_status = "status",
  col_group  = "group",
  reps       = 5,
  simul_type = "distr",
  distribs   = c("exp", "exp", "exp", "exp")
)
str(sim_distr$datasets)

# 3. Conditional Bootstrap
sim_cond <- RealSurvSim(
  dat = example_data,
  col_time   = "time",
  col_status = "status",
  col_group  = "group",
  reps       = 5,
  simul_type = "cond"
)
str(sim_cond$datasets)

# 4. Case Resampling
sim_case <- RealSurvSim(
  dat = example_data,
  col_time   = "time",
  col_status = "status",
  col_group  = "group",
  reps       = 5,
  simul_type = "case"
)
str(sim_case$datasets)

data(liang)
data(wu)
# 5. liang_kde<- RealSurvSim(liang, liang$V1, liang$V2, liang$V3, reps=3, simul_type = "KDE")

# For arbitary n
# 6. arbliang_distr<- RealSurvSim(liang,  liang$V1, liang$V2, liang$V3,reps=10,n = c(40,50), simul_type = "distr", distrib=c("exp", "llogis","llogis", "exp"))

# 7. arbwu_case<- RealSurvSim(wu, wu$V1, wu$V2, wu$V3, reps=100,n = c(40,50),  simul_type = "case")

References and Further Reading

Underlying Paper for the Package
Analysis and Methods for Survival Data (arXiv:2308.07842)

Data Reconstruction Algorithm
Guyot et al. (2012), describing the algorithm for reconstructing survival data from published Kaplan-Meier curves.

WebPlotDigitizer
WebPlotDigitizer for extracting data points from Kaplan-Meier curves.