hce (version 0.9.0)

simTTE: Simulate an adhce dataset with two correlated outcomes (illness - death model)

Description

Simulate an adhce dataset with two correlated outcomes - death and hospitalization - from a heterogeneous population. The correlation between these outcomes arises from population heterogeneity. Models the risk of death following hospitalization as dependent on the timing of the hospitalization, reflecting strong dependence between the times to the first and second events (i.e., event clustering).

Usage

simTTE(
  n,
  n0 = n,
  TTE_A,
  TTE_P = TTE_A,
  shape = 1,
  shape0 = shape,
  fixedfy = 2,
  theta = 1,
  alpha0 = 1,
  alpha = 1,
  rHR = 1,
  m = Inf,
  hce_type = c("mi", "md")
)

Value

an object of class adhce.

Arguments

n

sample size in the active treatment group.

n0

sample size in the placebo treatment group.

TTE_A

event rates in the active group for the time-to-event outcomes; a numeric vector of length two.

TTE_P

event rates in the placebo group for the time-to-event outcomes; a numeric vector of length two.

shape

shape parameter of the Weibull distribution for time-to-event outcomes in the active group. Default is 1 (exponential distribution).

shape0

shape parameter of the Weibull distribution for time-to-event outcomes in the placebo group. Default is 1 (exponential distribution).

fixedfy

length of follow-up.

theta

heterogeneity coefficient for the first event, modeled via a gamma distribution with mean 1; theta controls the variance. When theta = 0, there is no heterogeneity, which implies that death and hospitalization are independent.

alpha0

exponential heterogeneity coefficient for modeling the heterogeneity of risk of death as the first event.

alpha

exponential heterogeneity coefficient for modeling the heterogeneity of risk of death after hospitalization; the heterogeneity of the second event is the inverse of the time of the first event.

rHR

recurrence hazard ratio comparing the active group to the control group for the second event, based on gap time measured from the first event.

m

categorization number used for to discretize time to death and time to hospitalization. Defaults to Inf (no discretization).

hce_type

the type of the hierarchical composite endpoint: use mi for the most-important outcome or md for the move-down approach. This parameter only affects results when m is finite.

Details

The default setting assumes TTE_A = TTE_P. Both TTE_A and TTE_P must be numeric vectors of length two, corresponding to the event rates (Weibull distribution) for the first event of hospitalization and death. The parameters shape and shape0 identify the shape parameters of Weibull distributions for the first event, simulated from a distribution with a cumulative hazard of rate × gamma × t^shape for hospitalization and gamma^alpha0 × rate × t^shape for death, where gamma is a patient-specific frailty drawn from a gamma distribution with mean 1 and variance theta, shared between death and hospitalization for a given patient. The parameter theta represents population heterogeneity and also induces correlation between death and hospitalization as competing first events. The parameter alpha0 controls the heterogeneity of time to death through its effect on heterogeneity. Death after hospitalization is simulated from an exponential distribution with a constant hazard that depends on the timing t1 of the first event (hospitalization) as (TTE_A[2] + TTE_P[2])/2 × (t1 / fixedfy)^alpha × gamma^alpha0 for the placebo arm and (TTE_A[2] + TTE_P[2])/2 × rHR × (t1 / fixedfy)^alpha × gamma^alpha0 for the active arm where rHR is the recurrence hazard ratio. When alpha < 0, earlier hospitalization (smaller t1) increases the risk of death following hospitalization.

By default, events are simulated in continuous time. When m is specified as a positive numeric value, the event times are discretized into m intervals over the follow-up period.

See Also

simHCE() for a general adhce dataset simulation, and simKHCE() for kidney disease-specific adhce simulation.

Examples

## Example 1 - positive correlation
i <- 1764002323
set.seed(i)
PADY <- 2
D <- simTTE(n = 1000, TTE_A = c(0.1, 0.04), 
TTE_P = c(.15, 0.045), theta = 4, alpha0 = 2, alpha = -1, shape = 2, 
fixedfy = PADY, rHR = 1)
####### Summary of first events by treatment group ########
table(D$EVENT1, D$TRTP)
####### Summary of second events by treatment group ########
table(D$EVENT2, D$TRTP)
######## Calculate win odds #########################
calcWO(D, ref = "P")
## Plot the ordinal dominance graph ######
D$TRTP <- factor(D$TRTP, levels = c("P", "A"))
plot(D, type = "l", col = 2, fill = TRUE)
abline(a = 0, b = 1, lwd = 2, lty = 3, col = "darkgreen")
grid()
################################################################
## Example 2 - Move-down approach (discrete‑time case only)
PADY <- 2
# Continuous-time
set.seed(2)
D <- simTTE(n = 1000, TTE_A = c(0.1, 0.04), 
TTE_P = c(.15, 0.045), theta = 4, alpha0 = 2, alpha = -1, shape = 2, 
fixedfy = PADY, rHR = 1, m = Inf)
summaryWO(D, ref = "P")$summary_by_GROUP
# Discrete-time (more-ties)
D0 <- simTTE(n = 1000, TTE_A = c(0.1, 0.04), 
TTE_P = c(.15, 0.045), theta = 4, alpha0 = 2, alpha = -1, shape = 2, 
fixedfy = PADY, rHR = 1, m = 5)
summaryWO(D0, ref = "P")$summary_by_GROUP
# Discrete-time and move-down approach (less ties on death)
D1 <- simTTE(n = 1000, TTE_A = c(0.1, 0.04), 
TTE_P = c(.15, 0.045), theta = 4, alpha0 = 2, alpha = -1, shape = 2, 
fixedfy = PADY, rHR = 1, m = 5, hce_type = "md")
summaryWO(D1, ref = "P")$summary_by_GROUP