Simulates one single-arm or randomized two-arm trial under a Goldilocks sample-size design. At each planned interim look, posterior predictive probabilities determine whether to declare immediate success, stop accrual for expected success, stop for futility, or continue toward the maximum sample size.
survival_adapt(
hazard_treatment,
hazard_control = NULL,
cutpoints = NULL,
N_total,
lambda = 0.3,
lambda_time = NULL,
interim_look = NULL,
end_of_study,
prior_surv = c(0.1, 0.1),
prior_bin = c(1, 1),
bin_method = "mc",
block = 2,
rand_ratio = c(control = 1, treatment = 1),
prop_loss = 0,
alternative = "greater",
h0 = 0,
Fn = 0.05,
Sn = 0.9,
prob_ha = 0.95,
N_impute = 500,
N_mcmc = 1000,
mc_conf_level = 0.95,
empty_interval = c("prior", "propagate", "error"),
method = "logrank",
imputed_final = FALSE,
return_trace = FALSE,
binary_imputation = c("event-time", "bernoulli"),
prior_surv_final = prior_surv,
generation_cutpoints = cutpoints,
Qn = 1,
rmst_tau = end_of_study
)With return_trace = FALSE (the default), a one-row data frame
containing the evaluated design and final trial results, including:
N_treatment: Number of patients enrolled in the treatment arm.
N_control: Number of patients enrolled in the control arm.
est_final: Treatment effect estimated at the final analysis. For RMST
this is treatment minus control RMST through rmst_tau, in time units.
The final analysis occurs when either the maximum sample size is reached
and follow-up is complete, or the interim analysis triggered early
stopping of enrollment/accrual and follow-up for those subjects is
complete. It is NA after an immediate-success decision, for which no
later analysis is required, or when the optional diagnostic analysis
after binding futility cannot be computed.
post_prob_ha: Posterior probability from the final analysis. If a
Bayesian method uses imputed_final = TRUE, this is calculated for each
imputed final-analysis dataset and averaged over N_impute imputations.
For an imputed Cox analysis it is \(1 - P\) from the Rubin-pooled Wald
test. The same interpretation applies to imputed RMST and risk-difference
analyses. For non-imputed frequentist analyses it is \(1 - P\) from the
corresponding test. It is NA after an immediate-success decision, for
which no later analysis is required, or when the optional diagnostic
analysis after binding futility cannot be computed.
stop_futility: Logical indicator of whether the trial stopped early for
binding futility.
stop_immediate_success: Logical indicator of whether the trial stopped
and declared immediate success at an interim look.
stop_expected_success: Logical indicator of whether the trial stopped
accruing for expected success and continued planned follow-up.
trial_success: Logical indicator of the trial's official success
outcome. An immediate-success decision is final at the interim look;
binding futility is a final failure.
stopping_reason: One of "immediate_success", "expected_success",
"futility", or "maximum_sample_size".
decision_time: Calendar time at which the trial decision becomes final.
This is the interim look time for immediate success or futility, and the
analysis-ready time otherwise.
accrual_stop_time: Calendar time of the last enrollment in the trial.
analysis_ready_time: Calendar time at which the last enrolled subject's
observed event or censoring becomes available. This excludes external
data-cleaning and database-lock delays.
planned_completion_time: Calendar time at which the last enrolled
subject would complete the full planned follow-up.
followup_person_time: Sum of observed follow-up times across enrolled
subjects.
peak_active_followup: Largest number of enrolled subjects concurrently
under follow-up.
Calendar time is measured from the first patient's enrollment at time zero.
Times use the same units as lambda_time, cutpoints,
generation_cutpoints, and end_of_study.
The returned object has a decision_design attribute containing
interim_look, Fn, Sn, Qn, and the Monte Carlo settings. Thresholds
in this information are stored as one value per interim look (and have
length zero when no interim looks are planned). A prior_design attribute
contains the resolved Gamma shape, rate, mean hazard, and standard
deviation for every stage, arm, and interval.
Both return forms have an arguments attribute containing a named list of
the evaluated argument values, including defaults. It can be saved with
saveRDS() and supplied to a later call with
do.call(survival_adapt, attr(result, "arguments")). Its prop_loss
element contains a named value for every simulated arm. Its rand_ratio
element is stored in control, treatment order for two-arm designs. Its
cutpoints and generation_cutpoints elements retain the analysis and
data-generation partitions, respectively. For method = "bayes-bin", this
metadata explicitly retains the imputation priors (prior_surv and
prior_surv_final), completed-data analysis prior (prior_bin), and
imputation horizon (end_of_study). The separate prior_design attribute
gives the resolved Gamma parameters by stage, arm, and interval.
With return_trace = TRUE, a goldilocks_trial object is returned. Its
summary element is the same data frame and its trace element has one
row per interim look. prior_diagnostics contains the resolved interim and
final priors. posterior_diagnostics reports observed and effective
sufficient statistics and conjugate posterior parameters by completed look,
arm, and interval. The trace records calendar time, the number of subjects
actively under follow-up, enrollment and observed events by arm, predictive
probabilities, diagnostic Monte Carlo standard errors and exact bounds,
draw counts, thresholds, the decision and reason, empty-interval fallback
diagnostics, and warnings raised during that look. It deliberately excludes
imputed data sets and posterior draws to keep the output compact.
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 defining the
piecewise-exponential model used for interim posterior estimation,
predictive imputation, and final analysis. The number of interval-specific
prior columns must be one greater than the number of cutpoints. NULL
specifies a constant-hazard analysis 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.
NULL (the default) for no interim analyses, or a
strictly increasing positive integer vector giving the cumulative sample
size at each interim look. Do not include the maximum sample size. For
two-arm designs, each interim look must be at least the (largest) block
size (see block), ensuring both treatment groups are present at every
interim analysis; a smaller look could enroll subjects from one treatment
group only, leaving the interim posterior undefined for the missing group.
A required finite, positive numeric value giving the
planned subject-level follow-up time. It must be greater than the final
value in both cutpoints and generation_cutpoints, when supplied, and
use the same time unit.
A numeric vector, matrix, or named list specifying the
Gamma prior for the piecewise-exponential hazards used to generate outcomes
during interim prediction. A length-two vector supplies shape and rate and
applies the same prior to every arm and interval. A 2 by
length(cutpoints) + 1 matrix supplies interval-specific values shared by
all arms, with shapes in row 1 and rates in row 2. For independent
arm-specific priors, supply a list named control and treatment in a
two-arm design, or treatment in a single-arm design. Each list element
may be a length-two vector or an interval-specific matrix. Both arms must
be supplied; no values are borrowed or filled from the other arm. Rates
must use the same time unit as event times, exposure, and cutpoints. The
default is c(0.1, 0.1).
A length-two numeric vector of finite, positive shape
parameters c(a, b) for the Beta(a, b) event-probability prior used when
method = "bayes-bin". The same prior is applied to both arms. The default
is c(1, 1), a uniform prior.
A single character string selecting how to calculate the
posterior probability for method = "bayes-bin". It must be one of "mc"
(Monte Carlo sampling), "normal" (normal approximation), or
"quadrature" (numerical integration). The default is "mc".
The normal approximation can be inaccurate with sparse events or
non-events and posterior event probabilities near 0 or 1. It can change
whether prob_ha is exceeded. Increasing N_mcmc does not improve this
approximation; use "quadrature" or sufficiently precise "mc" instead.
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.
A single character string specifying the alternative
hypothesis. It must be one of "greater" (the default), "less", or
"two.sided". One-sided alternatives ("greater" and "less") are
supported for method = "bayes-surv" and method = "bayes-bin". All three
options are supported for method = "logrank", method = "cox",
method = "rmst", method = "riskdiff-wald", and
method = "riskdiff-fm". For an adverse event, benefit is in the
"greater" direction for RMST (longer event-free time) and the "less"
direction for the other methods (lower hazard or event probability).
A single finite numeric value specifying the null hypothesis or
margin. The default is 0. For Bayesian analyses, h0 must lie in
[0, 1] for a single-arm design and [-1, 1] for a two-arm design.
When method = "bayes-surv", h0 is the null value of
\(p_\textrm{treatment} - p_\textrm{control}\). In a single-arm design,
h0 is the external benchmark event probability, often referred to as a
performance goal (PG) or objective performance criterion (OPC).
When method = "bayes-bin", h0 is the null value of
\(p_\textrm{treatment} - p_\textrm{control}\) for a two-arm design, or
the null event probability for a single-arm design.
When method = "cox", h0 is the null log hazard ratio for treatment
versus control. Use h0 = 0 for the usual hazard ratio of 1 null, or
h0 = log(margin) for a non-inferiority margin specified as a hazard
ratio. A Cox non-inferiority test should usually use
alternative = "less".
When method = "rmst", h0 is the null treatment-control RMST
difference in time units and must lie in [-rmst_tau, rmst_tau]. For
non-inferiority allowing a loss of m time units, use h0 = -m and
alternative = "greater".
When method = "riskdiff-wald" or method = "riskdiff-fm", h0 is the
null value of \(p_\textrm{treatment} - p_\textrm{control}\) and must
lie in [-1, 1].
When method = "logrank", only h0 = 0 is supported; this denotes the
usual equal-survival null. Nonzero values are rejected because the
standard log-rank statistic does not implement a nonzero effect margin.
NULL, or a numeric vector of probabilities in [0, 1]. Each
value is the predictive-probability threshold to stop at the \(i\)-th
look early for futility. If there are no interim looks (i.e.
interim_look = NULL), then Fn is not used in the simulations or
analysis. Set Fn = 0 to disable futility monitoring; Fn = NULL has the
same effect. Supply either one value, which is repeated at every interim
look, or exactly one value per interim_look. Other lengths are rejected
rather than recycled. The default is 0.05.
A numeric vector of probabilities in [0, 1]. Each value is the
predictive-probability threshold to stop accrual at the \(i\)-th look for
expected success. If there are no interim looks (i.e.
interim_look = NULL), then Sn is not used in the simulations or
analysis. Supply either one value, which is repeated at every interim look,
or exactly one value per interim_look. Other lengths are rejected rather
than recycled. The default is 0.9.
A single numeric probability in [0, 1] defining success in
each completed-data analysis. For Bayesian methods this is compared with
the posterior probability of the alternative; for frequentist methods it is
compared with 1 - P. The default is 0.95.
A positive integer giving the number of predictive
imputations used at each interim look and, when requested, for final
multiple imputation. The default is 500. An imputed Cox, RMST, or
risk-difference final analysis requires at least two.
A positive integer giving the number of posterior draws used
within each method = "bayes-surv" and by method = "bayes-bin" when
bin_method = "mc". The default is 1000.
A single numeric probability strictly between 0.5 and
1, giving the confidence level for one-sided exact binomial bounds
reported as diagnostics of finite Monte Carlo uncertainty. The bounds do
not alter completed-data success classifications or interim decisions,
which use strict point-estimate comparisons with prob_ha, Qn, Sn, and
Fn. The default is 0.95.
A single character string specifying how to handle
empty piecewise-exponential intervals when updating Gamma hazard models for
predictive imputation and Bayesian survival analysis. An empty interval is
an interval with no exposed subjects in a treatment arm at the analysis
time. "prior" (the default) leaves the interval at zero exposure time and
zero events, so its posterior is driven only by its assigned survival
prior. "propagate" is a legacy heuristic that copies exposure time and
event counts from the nearest non-empty interval in the same treatment arm
and emits a warning. "error" stops when any empty interval is found.
A single character string specifying the completed-data and
final analysis. Available choices are a log-rank (method = "logrank")
test, Cox proportional hazards regression model Wald test
(method = "cox"), a restricted mean survival time difference Wald test
(method = "rmst"), a fully-Bayesian piecewise-exponential analysis
(method = "bayes-surv"), a Bayesian beta-binomial analysis of complete
binary outcomes (method = "bayes-bin"), a frequentist risk-difference
Wald test (method = "riskdiff-wald"), or a Farrington-Manning score test
(method = "riskdiff-fm") of complete binary outcomes. The deprecated
method = "riskdiff" is accepted as an alias for "riskdiff-wald" with a
warning. The default is "logrank". See Details.
A single logical value indicating whether the final
analysis should be based on imputed outcomes for subjects who were LTFU
(i.e. right-censored with time less than end_of_study). The default is
FALSE, which uses the observed-data analysis. If no outcomes require
imputation, the selected complete-data test is used directly with either
flag. With missing outcomes and method = "cox", "rmst", or
"riskdiff-wald", setting this to TRUE pools the scalar treatment
effects and variances using Rubin's rules; this requires N_impute >= 2
and positive total variance. Genuine final imputation is unsupported for
method = "riskdiff-fm" because no validated FM pooling rule is
implemented. Simulations combining FM and imputed_final = TRUE therefore
require prop_loss = 0 in both arms. Imputed final analyses remain
unavailable for method = "logrank".
A single logical value indicating whether the interim
decision path should be returned in addition to the usual final summary.
The default, FALSE, returns the historical one-row data frame. When
TRUE, the result is a goldilocks_trial object with summary, trace,
prior and posterior diagnostics, and call elements.
A single character string selecting the predictive
imputation approach for method = "bayes-bin", method = "riskdiff-wald",
or method = "riskdiff-fm". "event-time" (the default) draws a
conditional piecewise-exponential event time and reduces it to event status
at end_of_study. "bernoulli" draws the endpoint status directly from
its conditional event probability. This argument is ignored for
time-to-event analysis methods.
A numeric vector, matrix, or named list specifying
the Gamma prior used for final-stage piecewise-exponential imputation and,
for method = "bayes-surv", both the analysis of each hypothetical
completed trial at interim looks and the actual final analysis. It accepts
the same shared or arm-specific forms as prior_surv and defaults to
prior_surv. An informative prior_surv can therefore predict outstanding
outcomes while a weak prior_surv_final defines the Bayesian survival
success criterion. To use different priors for these roles, supply
prior_surv_final explicitly; an informative predictive prior is otherwise
also the default analysis prior. See Predictive and analysis priors
below.
NULL, or a numeric vector of finite, positive,
strictly increasing interior follow-up times defining the
piecewise-exponential model used to generate event times.
hazard_treatment and hazard_control must each have one value per
resulting interval. Defaults to cutpoints, preserving the historical
behavior in which generation and analysis used one partition.
A numeric vector of probabilities in [0, 1]. Each value is the
upper predictive-probability threshold for declaring immediate trial
success at the \(i\)-th look. If there are no interim looks (i.e.
interim_look = NULL), then Qn is not used in the simulations or
analysis. Supply either one value, which is repeated at every interim look,
or exactly one value per interim_look; other lengths are rejected. Qn
must be greater than or equal to Sn at every look. The default, 1,
disables immediate-success stopping.
A single finite positive restriction time for
method = "rmst", in the same units as end_of_study. Defaults to
end_of_study and must not exceed it. Prespecify the same horizon for all
looks, imputations, and simulations. It may precede analysis cutpoints and
does not shorten the planned follow-up or imputation horizon. Ignored for
other methods.
For method = "bayes-surv", prior_surv_final is used during interim
calculations as well as at the actual final analysis. The two arguments
specify different roles, not simply different calendar stages:
| Calculation | Gamma prior used |
| At interim, generate outstanding outcomes for enrolled and future participants | prior_surv |
| At interim, test each hypothetical completed trial at the current or maximum sample size | prior_surv_final |
At final analysis, impute missing outcomes if imputed_final = TRUE | prior_surv_final |
| Analyze the actual final trial data | prior_surv_final |
Within one interim predictive replicate, first update prior_surv with the
observed events and exposure, draw hazards, and generate outstanding
outcomes. Then start a fresh analysis posterior using prior_surv_final
and the completed dataset's events and exposure. Compare its posterior
probability of the alternative with prob_ha. The proportion of replicates
that pass is the predictive probability used by Qn, Sn, and Fn.
To incorporate external evidence in prediction while using a weak analysis
prior, explicitly supply an informative prior_surv and the chosen weak
prior_surv_final. Omitting prior_surv_final uses prior_surv for
both roles; the package does not automatically weaken the analysis prior.
The predictive prior can still affect the selected sample size and stopping
decision, so calibrate the design using both prespecified priors.
This table describes Bayesian survival analysis. For
method = "bayes-bin", completed-data success tests at interim and final
use prior_bin; prior_surv_final governs only optional final imputation.
Frequentist completed-data tests use no analysis prior.
evaluate_interim() performs the two interim calculations; use the same
prior arguments as in the simulated design.
Implements the Goldilocks design method described in Broglio et al. (2014). At each interim analysis, two probabilities are computed:
The posterior predictive probability of eventual success. This is
calculated as the proportion of imputed datasets at the current sample
size that satisfy the completed-data success criterion. At each interim
analysis this proportion is first compared to the corresponding element
of Qn. If it is strictly greater than Qn, the trial stops and
declares immediate success. Otherwise, if it is strictly greater than
Sn, accrual/enrollment is suspended and the outstanding follow-up is
allowed to complete before conducting the pre-specified final analysis.
The posterior predictive probability of success at the maximum sample
size. This is calculated as the proportion of imputed datasets at the
maximum sample size that satisfy the completed-data success criterion.
It is compared to the corresponding element of Fn, and if it is below
the threshold, accrual/enrollment is suspended and the trial terminated.
Typically this would be a binding decision. If it is not a binding
decision, then one should also explore the simulations with Fn = 0.
Hence, each interim look has four possible decisions, applied in this order:
Stop and declare immediate success when \(P_{n,l} > Q_l\).
Stop accruing for expected success and follow when \(S_l < P_{n,l} \le Q_l\).
Stop for futility when \(P_{n_{max},l} < F_l\).
Continue to enroll new subjects, or if at maximum sample size, proceed to final analysis.
The following completed-data analysis methods are available at interim and final analyses:
Log-rank test (method = "logrank"). Each (imputed) dataset with both
treatment and control arms can be compared using a standard log-rank test.
The output is a P-value, and there is no treatment effect reported. The
function returns \(1 - P\), which is reported in post_prob_ha. Whilst
not a posterior probability, it can be contrasted in the same manner. For
example, if the success threshold is \(P < 0.05\), then one requires
post_prob_ha \(> 0.95\). The reason for this is to enable simple
switching between Bayesian and frequentist paradigms for analysis. When
alternative = "less" or "greater", a one-sided P-value is computed
from the log-rank z-statistic.
Cox proportional hazards regression Wald test (method = "cox"). Similar
to the log-rank test, a P-value is calculated and \(1 - P\) is
reported in post_prob_ha. When alternative = "two.sided", the
standard two-sided Wald P-value is used when h0 = 0. For other values
of h0, the Wald test is centered on the specified null log hazard
ratio. When alternative = "less" or "greater", a one-sided P-value
is derived from the Wald z-statistic relative to h0. The treatment
effect (log hazard ratio) is also reported. When imputed_final = TRUE
and outcomes are missing, the Cox model is fitted to each of at least
two imputed datasets. The log hazard ratios and their within-imputation variances are
combined using Rubin's rules; the pooled Wald test uses Rubin's
large-sample degrees of freedom. When imputed_final = FALSE, the
existing single Cox model is fitted directly to the observed
right-censored data.
Restricted mean survival time (method = "rmst"). Estimates the area
under each Kaplan-Meier survival curve from zero through the prespecified
rmst_tau. The effect is treatment minus control RMST, measured in time
units. The Wald test uses the sum of the independent arm-specific
Greenwood variances and reports \(1 - P\). All three alternatives and
nonzero margins are supported. For an adverse event, a positive
difference favors treatment. Observed censored subjects remain in the
analysis. An arm whose last follow-up precedes rmst_tau with positive
estimated survival makes the analysis non-estimable; the horizon is never
reduced automatically. A curve reaching zero earlier is allowed. The test
requires positive total variance, including after Rubin pooling for
imputed_final = TRUE. This unadjusted two-arm analysis does not assume
proportional hazards. Interim prediction and final imputation still
depend on the specified piecewise-exponential model. See
vignette("rmst", package = "goldilocks").
Bayesian difference in cumulative event probability
(method = "bayes-surv"). Each imputed dataset is used to update the
conjugate Gamma analysis prior prior_surv_final, at both interim looks
and the final stage, yielding a posterior distribution for the piecewise
exponential rate parameters. In turn, the posterior distribution of the
cumulative incidence function (\(1 - S(t)\), where \(S(t)\) is the
survival function) evaluated at time end_of_study is calculated. In a
single-arm study, inference concerns the treatment-arm event probability.
In a two-arm study, the independent arm-specific posteriors define the
posterior distribution of the treatment-minus-control difference. The
reported posterior probability is determined by alternative and h0.
For piecewise-exponential analyses, an interim or final dataset may
contain intervals with no exposed subjects in one treatment arm,
especially when later cutpoints occur after the available follow-up at
early looks. The empty_interval argument controls this case. The
default, "prior", leaves an empty interval prior-driven, making the
absence of interval data explicit. The legacy "propagate" option
borrows sufficient statistics from the nearest non-empty interval within
the same treatment arm. It is operationally stable but statistically
consequential because adjacent observed data then inform the empty
interval's posterior. "error" is strict and stops the simulation or
analysis when an empty interval is encountered.
Bayesian beta-binomial analysis (method = "bayes-bin"). Each complete
or imputed dataset is reduced to binary event outcomes at end_of_study.
A conjugate Beta(a, b) prior, specified with prior_bin, is updated
with the number of events and non-events in each arm. In a single-arm
study, inference is based on the posterior event probability. In a
two-arm study, inference is based on
\(p_\textrm{treatment} - p_\textrm{control}\). This posterior
probability can be calculated using Monte Carlo beta draws
(bin_method = "mc"), a normal approximation ("normal"), or numerical
quadrature ("quadrature"). Like the risk-difference test, this method
requires complete binary outcomes: censored subjects must either be
followed to end_of_study, imputed, or excluded when
imputed_final = FALSE.
The normal approximation matches posterior moments but can misrepresent
tail probabilities when a Beta posterior is skewed, particularly near
event-probability boundaries of 0 or 1. This can change success and
interim stopping decisions. Use bin_method = "quadrature" or
sufficiently precise "mc" when the approximation is unsuitable;
increasing N_mcmc does not correct normal-approximation error.
Two equivalent predictive imputation approaches are available through
binary_imputation. With "event-time", the package samples a future
event time conditional on the available event-free follow-up and then
records whether it falls by end_of_study. With "bernoulli", it
calculates the same endpoint probability directly. If \(T\) is the
observed event-free follow-up, \(T^*\) is end_of_study, \(S(t)\)
is the survival function, and \(H(t)\) is the cumulative hazard, that
probability is
$$\Pr(X = 1 \mid T_\mathrm{event} > T) = \frac{S(T) - S(T^*)}{S(T)} = 1 - \exp\{-[H(T^*) - H(T)]\}.$$
A Bernoulli outcome is drawn with this probability. For a subject not
yet enrolled, \(T = 0\); observed events are retained unchanged.
Because no precise event time is generated, the imputed time is set to
end_of_study and only the binary event status is analyzed. Each
imputation still uses a sampled posterior hazard draw, so uncertainty in
the piecewise-exponential model is retained.
Frequentist risk difference (method = "riskdiff-wald" or
"riskdiff-fm"). Each complete or predictively imputed dataset is reduced
to binary event outcomes at end_of_study. The estimated treatment effect is
\(p_\textrm{treatment} - p_\textrm{control}\). "riskdiff-wald" uses
the observed arm risks in an unpooled Wald variance. "riskdiff-fm"
instead uses maximum likelihood arm risks constrained by the null
difference h0 in a Farrington-Manning score variance. The latter remains
defined for common sparse tables, including equal-arm all-zero and all-one
outcomes. Both methods report \(1 - P\) in post_prob_ha and support
all three alternatives. Because they require complete binary outcomes,
lost-to-follow-up subjects are excluded when imputed_final = FALSE.
With genuinely missing final outcomes, only "riskdiff-wald" supports
imputed_final = TRUE: estimates and variances from at least two completed
datasets are pooled using Rubin's rules, requiring positive total variance.
FM final imputation is rejected rather than converted to a Wald test.
With complete final outcomes, either flag preserves the selected test.
Imputed final analysis (imputed_final). The overall final analysis
conducted after accrual is suspended and follow-up is complete can be
analyzed on imputed datasets for Bayesian methods ("bayes-surv" and
"bayes-bin"), Cox regression, RMST, and the frequentist risk-difference
Wald analysis, or on the non-imputed dataset. Interim prediction completes
outcomes that are not yet observed, whereas final imputation applies only
to subjects right-censored because of loss to follow-up before
end_of_study. Design evaluations should prespecify whether the final
analysis imputes these outcomes and assess sensitivity to that choice,
particularly when appreciable attrition is expected. Simulated dropout is
independent of event time within each arm, as described under prop_loss.
This supports survival analyses with right-censoring, but does not make
complete-case binary analysis unbiased: early events can be observed
before dropout, whereas later endpoint outcomes can be missing. Binary
designs with dropout should assess model-based final imputation and its
assumptions. For Cox regression and RMST the final estimates and variances
are pooled with Rubin's rules. It cannot be used with
method = "logrank".
When imputation is involved, either at interim analyses or through
imputed_final = TRUE, the package uses a two-stage impute-then-analyze
procedure. First, the piecewise-exponential model is fitted to the
observed time-to-event data and used to complete pending outcomes.
Second, each completed dataset is analyzed using the model selected by
method.
For method = "bayes-bin", these are deliberately separate models. The
imputation model has piecewise hazards with Gamma prior prior_surv (or
prior_surv_final during final imputation), whereas the completed-data
analysis has an event probability at end_of_study with Beta prior
prior_bin. The Beta prior is not derived from the Gamma prior, and the
two stages are not one joint Bayesian model. Both prior specifications can
therefore affect predictive decisions when outcomes require imputation. The
"event-time" and "bernoulli" binary-imputation options use the same
piecewise-exponential prediction model and do not change this separation.
For method = "bayes-surv", the second analysis instead forms a fresh
piecewise-exponential posterior from the completed data and
prior_surv_final. At interim looks the first stage uses prior_surv,
allowing predictive borrowing to differ from the final success criterion.
For frequentist methods ("logrank", "cox", "rmst", "riskdiff-wald",
and "riskdiff-fm"), each completed dataset uses a standard test rather
than a posterior. Imputed Cox, RMST, and risk-difference final analyses
pool estimates and variances using Rubin's rules.
At each interim look, follow-up times are masked (censored) to reflect the
calendar time of the analysis. The package treats enrollment and
randomization as occurring at the same time. Subjects enrolled at the exact
interim boundary have zero follow-up time. These times are clamped to
.Machine$double.eps (approximately \(2.2 \times 10^{-16}\)) so that
they contribute negligible but non-zero exposure to the interim posterior.
This affects at most one subject per interim look.
Broglio KR, Connor JT, Berry SM. Not too big, not too small: a Goldilocks approach to sample size selection. Journal of Biopharmaceutical Statistics, 2014; 24(3): 685–705.
# RCT with exponential hazard (no piecewise breaks)
# Note: the number of imputations is small to enable this example to run
# quickly on CRAN tests. In practice, much larger values are needed.
survival_adapt(
hazard_treatment = -log(0.85) / 36,
hazard_control = -log(0.7) / 36,
cutpoints = NULL,
N_total = 600,
lambda = 20,
lambda_time = NULL,
interim_look = 400,
end_of_study = 36,
prior_surv = c(0.1, 0.1),
block = 2,
rand_ratio = c(control = 1, treatment = 1),
prop_loss = 0.30,
alternative = "less",
h0 = 0,
Fn = 0.05,
Sn = 0.9,
prob_ha = 0.975,
N_impute = 10,
N_mcmc = 10,
method = "bayes-surv")
Run the code above in your browser using DataLab