Specifies the design of an adaptive trial with a continuous, normally
distributed outcome and validates all inputs. Uses normally distributed
posterior distributions for the mean values in each
trial arm; technically, no priors are used (as using normal-normal
conjugate prior models with extremely wide or uniform priors gives similar
results for these simple, unadjusted estimates). This corresponds to the use
of improper, flat priors, although not explicitly specified as such. Use
calibrate_trial() to calibrate the trial specification to obtain a specific
value for a certain performance metric (e.g., the Bayesian type 1 error
rate). Use run_trial() or run_trials() to conduct single/multiple
simulations of the specified trial, respectively.
Note: add_info as specified in setup_trial() is set to the arms and
standard deviations used for trials specified using this function.
Further details: please see setup_trial(). See setup_trial_binom()
for simplified setup of trials with binomially distributed binary outcomes.
For additional trial specification examples, see the the
Basic examples vignette
(vignette("Basic-examples", package = "adaptr")) and the
Advanced example vignette
(vignette("Advanced-example", package = "adaptr")).
arms |
character vector with unique names for the trial arms.
|
true_ys |
numeric vector, simulated means of the outcome in all trial
arms.
|
sds |
numeric vector, true standard deviations (must be > 0) of the
outcome in all trial arms.
|
start_probs |
numeric vector, allocation probabilities for each arm at
the beginning of the trial. The default (NULL) automatically generates
equal randomisation probabilities for each arm.
|
fixed_probs |
numeric vector, fixed allocation probabilities for each
arm. Must be either a numeric vector with NA for arms without fixed
probabilities and values between 0 and 1 for the other arms or NULL
(default), if adaptive randomisation is used for all arms or if one of the
special settings ("sqrt-based", "sqrt-based start",
"sqrt-based fixed", or "match") is specified for control_prob_fixed
(described below).
|
min_probs |
numeric vector, lower threshold for adaptive allocation
probabilities; lower probabilities will be rounded up to these values. Must
be NA (default for all arms) if no lower threshold is wanted and for arms
using fixed allocation probabilities.
|
max_probs |
numeric vector, upper threshold for adaptive allocation
probabilities; higher probabilities will be rounded down to these values.
Must be NA (default for all arms) if no threshold is wanted and for arms
using fixed allocation probabilities.
|
rescale_probs |
NULL (default) or one of either "fixed", "limits",
or "both". Rescales fixed_probs (if "fixed" or "both") and
min_probs/max_probs (if "limits" or "both") after arm dropping in
trial specifications with >2 arms using a rescale_factor defined as
initial number of arms/number of active arms. "fixed_probs and
min_probs are rescaled as initial value * rescale factor, except for
fixed_probs controlled by the control_prob_fixed argument, which are
never rescaled. max_probs are rescaled as
1 - ( (1 - initial value) * rescale_factor).
Must be NULL if there are only 2 arms or if control_prob_fixed is
"sqrt-based fixed". If not NULL, one or more valid non-NA values must
be specified for either min_probs/max_probs or fixed_probs (not
counting a fixed value for the original control if control_prob_fixed
is "sqrt-based"/"sqrt-based start"/"sqrt-based fixed").
Note: using this argument and specific combinations of values in
the other arguments may lead to invalid combined (total) allocation
probabilities after arm dropping, in which case all probabilities will
ultimately be rescaled to sum to 1. It is the responsibility of the user
to ensure that rescaling fixed allocation probabilities and minimum/maximum
allocation probability limits will not lead to invalid or unexpected
allocation probabilities after arm dropping.
Finally, any initial values that are overwritten by the
control_prob_fixed argument after arm dropping will not be rescaled.
|
data_looks |
vector of increasing integers, specifies when to conduct
adaptive analyses (= the total number of patients with available outcome
data at each adaptive analysis). The last number in the vector represents
the final adaptive analysis, i.e., the final analysis where superiority,
inferiority, practical equivalence, or futility can be claimed.
Instead of specifying data_looks, the max_n and look_after_every
arguments can be used in combination (in which case data_looks must be
NULL, the default value).
|
max_n |
single integer, number of patients with available outcome data
at the last possible adaptive analysis (defaults to NULL).
Must only be specified if data_looks is NULL. Requires specification of
the look_after_every argument.
|
look_after_every |
single integer, specified together with max_n.
Adaptive analyses will be conducted after every look_after_every
patients have available outcome data, and at the total sample size as
specified by max_n (max_n does not need to be a multiple of
look_after_every). If specified, data_looks must be NULL (default).
|
randomised_at_looks |
vector of increasing integers or NULL,
specifying the number of patients randomised at the time of each adaptive
analysis, with new patients randomised using the current allocation
probabilities at said analysis.
If NULL (the default), the number of patients randomised at each analysis
will match the number of patients with available outcome data at said
analysis, as specified by data_looks or max_n and look_after_every,
i.e., outcome data will be available immediately after randomisation for
all patients.
If not NULL, the vector must be of the same length as the number of
adaptive analyses specified by data_looks or max_n and
look_after_every, and all values must be larger than or equal to the
number of patients with available outcome data at each analysis.
|
control |
single character string, name of one of the arms or NULL
(default). If specified, this arm will serve as a common control arm, to
which all other arms will be compared and the
inferiority/superiority/equivalence thresholds (see below) will be for
those comparisons. See setup_trial() Details for information on
behaviour with respect to these comparisons.
|
control_prob_fixed |
if a common control arm is specified, this can
be set NULL (the default), in which case the control arm allocation
probability will not be fixed if control arms change (the allocation
probability for the first control arm may still be fixed using
fixed_probs, but will not be 'reused' for the new control arm).
If not NULL, a vector of probabilities of either length 1 or
number of arms - 1 can be provided, or one of the special arguments
"sqrt-based", "sqrt-based start", "sqrt-based fixed" or "match".
See setup_trial() Details for details on how this affects
trial behaviour.
|
inferiority |
single numeric value or vector of numeric values of the
same length as the maximum number of possible adaptive analyses, specifying
the probability threshold(s) for inferiority (default is 0.01). All
values must be >= 0 and <= 1, and if multiple values are supplied, no
values may be lower than the preceding value. If a common controlis not
used, all values must be < 1 / number of arms. An arm will be considered
inferior and dropped if the probability that it is best (when comparing all
arms) or better than the control arm (when a common control is used)
drops below the inferiority threshold at an adaptive analysis.
|
superiority |
single numeric value or vector of numeric values of the
same length as the maximum number of possible adaptive analyses, specifying
the probability threshold(s) for superiority (default is 0.99). All
values must be >= 0 and <= 1, and if multiple values are supplied, no
values may be higher than the preceding value. If the probability that an
arm is best (when comparing all arms) or better than the control arm (when
a common control is used) exceeds the superiority threshold at an
adaptive analysis, said arm will be declared the winner and the trial will
be stopped (if no common control is used or if the last comparator is
dropped in a design with a common control) or become the new control and
the trial will continue (if a common control is specified).
|
equivalence_prob |
single numeric value, vector of numeric values of the
same length as the maximum number of possible adaptive analyses or NULL
(default, corresponding to no equivalence assessment), specifying the
probability threshold(s) for equivalence. If not NULL, all values must be
> 0 and <= 1, and if multiple values are supplied, no value may be
higher than the preceding value. If not NULL, arms will be dropped for
equivalence if the probability of either (a) equivalence compared to a
common control or (b) equivalence between all arms remaining (designs
without a common control) exceeds the equivalence threshold at an
adaptive analysis. Requires specification of equivalence_diff and
equivalence_only_first.
|
equivalence_diff |
single numeric value (> 0) or NULL (default,
corresponding to no equivalence assessment). If a numeric value is
specified, estimated absolute differences smaller than this threshold will
be considered equivalent. For designs with a common control arm, the
differences between each non-control arm and the control arm is used, and
for trials without a common control arm, the difference between the
highest and lowest estimated outcome rates are used and the trial is only
stopped for equivalence if all remaining arms are equivalent.
|
equivalence_only_first |
single logical in trial specifications where
equivalence_prob and equivalence_diff are specified and a common
control arm is included, otherwise NULL (default). If a common
control arm is used, this specifies whether equivalence will only be
assessed for the first control (if TRUE) or also for subsequent control
arms (if FALSE) if one arm is superior to the first control and becomes
the new control.
|
futility_prob |
single numeric value, vector of numeric values of the
same length as the maximum number of possible adaptive analyses or NULL
(default, corresponding to no futility assessment), specifying the
probability threshold(s) for futility. All values must be > 0 and <= 1,
and if multiple values are supplied, no value may be higher than the
preceding value. If not NULL, arms will be dropped for futility if
the probability for futility compared to the common control exceeds the
futility threshold at an adaptive analysis. Requires a common control
arm (otherwise this argument must be NULL), specification of
futility_diff, and futility_only_first.
|
futility_diff |
single numeric value (> 0) or NULL (default,
corresponding to no futility assessment). If a numeric value is specified,
estimated differences below this threshold in the beneficial direction
(as specified in highest_is_best) will be considered futile when
assessing futility in designs with a common control arm. If only 1 arm
remains after dropping arms for futility, the trial will be stopped without
declaring the last arm superior.
|
futility_only_first |
single logical in trial specifications designs
where futility_prob and futility_diff are specified, otherwise NULL
(default and required in designs without a common control arm).
Specifies whether futility will only be assessed against the first
control (if TRUE) or also for subsequent control arms (if FALSE) if
one arm is superior to the first control and becomes the new control.
|
highest_is_best |
single logical, specifies whether larger estimates of
the outcome are favourable or not; defaults to FALSE, corresponding to,
e.g., an undesirable binary outcomes (e.g., mortality) or a continuous
outcome where lower numbers are preferred (e.g., hospital length of stay).
|
soften_power |
either a single numeric value or a numeric vector of
exactly the same length as the maximum number of looks/adaptive analyses.
Values must be between 0 and 1 (default); if < 1, then re-allocated
non-fixed allocation probabilities are all raised to this power (followed
by rescaling to sum to 1) to make adaptive allocation probabilities
less extreme, in turn used to redistribute remaining probability while
respecting limits when defined by min_probs and/or max_probs. If 1,
then no softening is applied.
|
cri_width |
single numeric >= 0 and < 1, the width of the
percentile-based credible intervals used when summarising individual trial
results. Defaults to 0.95, corresponding to 95% credible intervals.
|
n_draws |
single integer, the number of draws from the posterior
distributions for each arm used when running the trial. Defaults to
5000; can be reduced for a speed gain (at the potential loss of stability
of results if too low) or increased for increased precision (increasing
simulation time). Values < 100 are not allowed and values < 1000 are
not recommended and warned against.
|
robust |
single logical, if TRUE (default) the medians and median
absolute deviations (scaled to be comparable to the standard deviation for
normal distributions; MAD_SDs, see stats::mad()) are used to summarise
the posterior distributions; if FALSE, the means and standard deviations
(SDs) are used instead (slightly faster, but may be less appropriate for
posteriors skewed on the natural scale).
|
description |
character string, default is
"generic normally distributed outcome trial". See arguments of
setup_trial().
|
Because the posteriors used in this type of trial (with a generic,
continuous, normally distributed outcome) are by definition normally
distributed, FALSE is used as the default value for the robust argument.