Simulates enrollment, treatment allocation, event or censoring times, and loss to follow-up for a single-arm or randomized two-arm trial. Event times follow a piecewise-exponential distribution within each arm.
sim_comp_data(
hazard_treatment,
hazard_control = NULL,
generation_cutpoints = NULL,
N_total,
lambda = 0.3,
lambda_time = NULL,
end_of_study,
block = 2,
rand_ratio = c(control = 1, treatment = 1),
prop_loss = 0
)A data frame with one row per subject and columns:
time: Numeric event or censoring time.
treatment: Numeric treatment indicator, coded 1 for the treatment arm
and 0 for the control arm. Single-arm designs have treatment = 1 for
every subject.
event: Numeric event indicator, coded 1 for an event and 0 for
right-censoring.
enrollment: Numeric time of subject enrollment relative to first
patient in. The package treats enrollment and randomization as occurring
at the same time.
id: Integer subject identifier.
loss_to_fu: Logical indicator that dropout occurred before both the
event and the administrative follow-up horizon.
A required numeric vector of finite, non-negative
event rates for the treatment arm. Supply one rate per interval defined by
generation_cutpoints; a single value specifies a constant event rate.
NULL (the default) for a single-arm trial, or a
numeric vector of finite, non-negative event rates for the control arm in a
two-arm trial. It must contain one rate per interval defined by
generation_cutpoints.
NULL (the default), or a numeric vector of
finite, positive, strictly increasing interior follow-up times at which the
data-generating hazard changes. The number of hazards for each arm must be
one greater than the number of generation cutpoints. NULL specifies a
constant-hazard data-generating model.
A required positive integer giving the maximum total sample size.
A numeric vector of finite, positive enrollment rates per unit
of calendar time. Supply one rate for each interval defined by
lambda_time. The default is 0.3. See enrollment() for the
continuous-time enrollment model and time origin.
NULL (the default), or a numeric vector of finite,
positive, strictly increasing calendar times at which the enrollment rate
changes. Time zero is implicit, and length(lambda) must equal
length(lambda_time) + 1.
A required finite, positive numeric value giving the
planned follow-up time for each subject. It must be later than the final
generation_cutpoints value and use the same time unit.
A positive integer vector of permitted randomization block
sizes. Every value must be a multiple of sum(rand_ratio). The default is
2 and the argument is ignored for a single-arm trial.
A length-two positive integer vector giving the control to
treatment randomization ratio. The default is
c(control = 1, treatment = 1). Name the values control and treatment;
either supplied order is accepted and matched by name. A legacy unnamed
vector remains accepted in c(control, treatment) order. Unequal unnamed
values produce a warning because names may be required in a future major
release. See randomization() for more details.
A numeric vector containing one or two probabilities in
[0, 1). Each value is the dropout-time CDF at end_of_study:
\(P(D \le \tau) = p\), where \(\tau\) is the planned follow-up duration
per subject. Independently of event time and enrollment, each subject's
dropout time \(D\) is exponentially distributed with rate
\(-\log(1-p)/\tau\). The observed time is the minimum of event time,
dropout time, and end_of_study; an event occurring before dropout is
retained. Thus, prop_loss is not the expected proportion actually
censored by dropout: that proportion can be lower because events occur
first, and the realized number of dropouts varies between trials. A single
value applies the same dropout distribution to every arm. For a two-arm
design, supply a length-two vector named control and treatment for
arm-specific probabilities; supplied order does not matter. Single-arm
designs require one probability. The default 0 sets dropout time to
infinity without drawing random numbers. A value of 1 is rejected because
it requires an infinite exponential rate.
Enrollment is simulated directly in continuous time by
enrollment(). The first patient is placed at time zero and all subsequent
enrollment times are measured from first patient in. No uniform jitter is
added in sim_comp_data().
lambda_time and generation_cutpoints both contain internal change
times, but they describe different clocks. lambda_time describes changes
in the trial's calendar-time enrollment rate measured from first patient
in. generation_cutpoints describes changes in an individual subject's
event hazard measured from that subject's enrollment. They need not have
the same values or length. All time quantities supplied to a simulation
should nevertheless use one common unit, such as days or months.
PWEALL represents the continuous generating hazard with pieces closed on the left and open on the right. This differs from the package's open-left, closed-right convention for assigning realized times only at the cutpoints themselves, which have probability zero under the continuous model. The cumulative hazard, event-time distribution, and generated simulations are therefore unchanged.
Dropout is independent censoring conditional on treatment arm. For event
time \(T\), loss_to_fu is true only when \(D < \min(T, \tau)\).
Administrative censoring and dropout after an observed event are not
counted as loss to follow-up. For example, prop_loss = 0.05 with
end_of_study = 12 specifies a 5% dropout CDF at 12 months if the time
unit is months; it does not force five losses in a 100-subject trial. Equal
dropout probabilities in arms with different event hazards need not yield
equal observed dropout proportions.
To express a dropout probability \(q\) supplied at a different reference
time \(t_0\), use \(p = 1 - (1-q)^{\tau/t_0}\) at end_of_study to
preserve the same exponential dropout hazard. Treatment discontinuation is
not separately modeled and should not be treated as loss to follow-up if
endpoint collection continues.
This independent exponential mechanism replaces selection of
ceiling(prop_loss * arm size) subjects followed by censoring uniformly
before each selected subject's potential event or administrative time.
Positive prop_loss values therefore change seeded results and design
operating characteristics relative to the previous mechanism. Simulations
with prop_loss = 0 are unchanged.