Setup a trial specification using a binary, binomially distributed outcome

Specifies the design of an adaptive trial with a binary, binomiallydistributed outcome and validates all inputs. Usesbeta-binomialconjugate models withbeta(1, 1) prior distributions, corresponding to auniform prior (or the addition of 2 patients, 1 with an event and 1 without,in eacharm) to the trial. Usecalibrate_trial() to calibrate the trialspecification to obtain a specific value for a certain performance metric(e.g., the Bayesian type 1 error rate). Userun_trial() orrun_trials()to conduct single/multiple simulations of the specified trial, respectively.
Note:add_info as specified insetup_trial() is set toNULL fortrial specifications setup by this function.
Further details: please seesetup_trial(). Seesetup_trial_norm() forsimplified setup of trials with a normally distributed continuous outcome.
For additional trial specification examples, see the theBasic examplesvignette (vignette("Basic-examples", package = "adaptr")) and theAdvanced example vignette(vignette("Advanced-example", package = "adaptr")).

Usage

setup_trial_binom(arms,true_ys,  start_probs=NULL,  fixed_probs=NULL,  min_probs=rep(NA,length(arms)),  max_probs=rep(NA,length(arms)),  rescale_probs=NULL,  data_looks=NULL,  max_n=NULL,  look_after_every=NULL,  randomised_at_looks=NULL,  control=NULL,  control_prob_fixed=NULL,  inferiority=0.01,  superiority=0.99,  equivalence_prob=NULL,  equivalence_diff=NULL,  equivalence_only_first=NULL,  futility_prob=NULL,  futility_diff=NULL,  futility_only_first=NULL,  highest_is_best=FALSE,  soften_power=1,  cri_width=0.95,  n_draws=5000,  robust=TRUE,  description="generic binomially distributed outcome trial")

Arguments

arms

character vector with unique names for the trial arms.

true_ys

numeric vector, true probabilities (between0 and1) ofoutcomes in all trialarms.

start_probs

numeric vector, allocation probabilities for each arm atthe beginning of the trial. The default (NULL) automatically generatesequal randomisation probabilities for each arm.

fixed_probs

numeric vector, fixed allocation probabilities for eacharm. Must be either a numeric vector withNA for arms without fixedprobabilities and values between0 and1 for the other arms orNULL(default), if adaptive randomisation is used for all arms or if one of thespecial settings ("sqrt-based","sqrt-based start","sqrt-based fixed", or"match") is specified forcontrol_prob_fixed(described below).

min_probs

numeric vector, lower threshold for adaptive allocationprobabilities; lower probabilities will be rounded up to these values. MustbeNA (default for all arms) if no lower threshold is wanted and for armsusing fixed allocation probabilities.

max_probs

numeric vector, upper threshold for adaptive allocationprobabilities; higher probabilities will be rounded down to these values.Must beNA (default for all arms) if no threshold is wanted and for armsusing fixed allocation probabilities.

rescale_probs

NULL (default) or one of either"fixed","limits",or"both". Rescalesfixed_probs (if"fixed" or"both") andmin_probs/max_probs (if"limits" or"both") after arm dropping intrial specifications with>2 arms using arescale_factor defined asinitial number of arms/number of active arms."fixed_probs andmin_probs are rescaled asinitial value * rescale factor, except forfixed_probs controlled by thecontrol_prob_fixed argument, which arenever rescaled.max_probs are rescaled as1 - ( (1 - initial value) * rescale_factor).
Must beNULL if there are only2 arms or ifcontrol_prob_fixed is"sqrt-based fixed". If notNULL, one or more valid non-NA values mustbe specified for eithermin_probs/max_probs orfixed_probs (notcounting a fixed value for the originalcontrol ifcontrol_prob_fixedis"sqrt-based"/"sqrt-based start"/"sqrt-based fixed").
Note: using this argument and specific combinations of values inthe other arguments may lead to invalid combined (total) allocationprobabilities after arm dropping, in which case all probabilities willultimately be rescaled to sum to1. It is the responsibility of the userto ensure that rescaling fixed allocation probabilities and minimum/maximumallocation probability limits will not lead to invalid or unexpectedallocation probabilities after arm dropping.
Finally, any initial values that are overwritten by thecontrol_prob_fixed argument after arm dropping will not be rescaled.

data_looks

vector of increasing integers, specifies when to conductadaptive analyses (= the total number of patients with available outcomedata at each adaptive analysis). The last number in the vector representsthe final adaptive analysis, i.e., the final analysis where superiority,inferiority, practical equivalence, or futility can be claimed.Instead of specifyingdata_looks, themax_n andlook_after_everyarguments can be used in combination (in which casedata_looks must beNULL, the default value).

max_n

single integer, number of patients with available outcome dataat the last possible adaptive analysis (defaults toNULL).Must only be specified ifdata_looks isNULL. Requires specification ofthelook_after_every argument.

look_after_every

single integer, specified together withmax_n.Adaptive analyses will be conducted after everylook_after_everypatients have available outcome data, and at the total sample size asspecified bymax_n (max_n does not need to be a multiple oflook_after_every). If specified,data_looks must beNULL (default).

randomised_at_looks

vector of increasing integers orNULL,specifying the number of patients randomised at the time of each adaptiveanalysis, with new patients randomised using the current allocationprobabilities at said analysis.IfNULL (the default), the number of patients randomised at each analysiswill match the number of patients with available outcome data at saidanalysis, as specified bydata_looks ormax_n andlook_after_every,i.e., outcome data will be available immediately after randomisation forall patients.
If notNULL, the vector must be of the same length as the number ofadaptive analyses specified bydata_looks ormax_n andlook_after_every, and all values must be larger than or equal to thenumber of patients with available outcome data at each analysis.

control

single character string, name of one of thearms orNULL(default). If specified, this arm will serve as a common control arm, towhich all other arms will be compared and theinferiority/superiority/equivalence thresholds (see below) will be forthose comparisons. Seesetup_trial()Details for information onbehaviour with respect to these comparisons.

control_prob_fixed

if a commoncontrol arm is specified, this canbe setNULL (the default), in which case the control arm allocationprobability will not be fixed if control arms change (the allocationprobability for the first control arm may still be fixed usingfixed_probs, but will not be 'reused' for the new control arm).
If notNULL, a vector of probabilities of either length1 ornumber of arms - 1 can be provided, or one of the special arguments"sqrt-based","sqrt-based start","sqrt-based fixed" or"match".
Seesetup_trial()Details for details on how this affectstrial behaviour.

inferiority

single numeric value or vector of numeric values of thesame length as the maximum number of possible adaptive analyses, specifyingthe probability threshold(s) for inferiority (default is0.01). Allvalues must be>= 0 and<= 1, and if multiple values are supplied, novalues may be lower than the preceding value. If a commoncontrolis notused, all values must be< 1 / number of arms. An arm will be consideredinferior and dropped if the probability that it is best (when comparing allarms) or better than the control arm (when a commoncontrol is used)drops below the inferiority threshold at an adaptive analysis.

superiority

single numeric value or vector of numeric values of thesame length as the maximum number of possible adaptive analyses, specifyingthe probability threshold(s) for superiority (default is0.99). Allvalues must be>= 0 and<= 1, and if multiple values are supplied, novalues may be higher than the preceding value. If the probability that anarm is best (when comparing all arms) or better than the control arm (whena commoncontrol is used) exceeds the superiority threshold at anadaptive analysis, said arm will be declared the winner and the trial willbe stopped (if no commoncontrol is used or if the last comparator isdropped in a design with a common control)or become the new control andthe trial will continue (if a common control is specified).

equivalence_prob

single numeric value, vector of numeric values of thesame length as the maximum number of possible adaptive analyses orNULL(default, corresponding to no equivalence assessment), specifying theprobability threshold(s) for equivalence. If notNULL, all values must be> 0 and<= 1, and if multiple values are supplied, no value may behigher than the preceding value. If notNULL, arms will be dropped forequivalence if the probability of either(a) equivalence compared to acommoncontrol or(b) equivalence between all arms remaining (designswithout a commoncontrol) exceeds the equivalence threshold at anadaptive analysis. Requires specification ofequivalence_diff andequivalence_only_first.

equivalence_diff

single numeric value (> 0) orNULL (default,corresponding to no equivalence assessment). If a numeric value isspecified, estimated absolute differences smaller than this threshold willbe considered equivalent. For designs with a commoncontrol arm, thedifferences between each non-control arm and thecontrol arm is used, andfor trials without a commoncontrol arm, the difference between thehighest and lowest estimated outcome rates are used and the trial is onlystopped for equivalence if all remaining arms are equivalent.

equivalence_only_first

single logical in trial specifications whereequivalence_prob andequivalence_diff are specified and a commoncontrol arm is included, otherwiseNULL (default). If a commoncontrol arm is used, this specifies whether equivalence will only beassessed for the first control (ifTRUE) or also for subsequentcontrolarms (ifFALSE) if one arm is superior to the first control and becomesthe new control.

futility_prob

single numeric value, vector of numeric values of thesame length as the maximum number of possible adaptive analyses orNULL(default, corresponding to no futility assessment), specifying theprobability threshold(s) for futility. All values must be> 0 and<= 1,and if multiple values are supplied, no value may be higher than thepreceding value. If notNULL, arms will be dropped for futility ifthe probability for futility compared to the commoncontrol exceeds thefutility threshold at an adaptive analysis. Requires a commoncontrolarm (otherwise this argument must beNULL), specification offutility_diff, andfutility_only_first.

futility_diff

single numeric value (> 0) orNULL (default,corresponding to no futility assessment). If a numeric value is specified,estimated differences below this threshold in thebeneficial direction(as specified inhighest_is_best) will be considered futile whenassessing futility in designs with a commoncontrol arm. If only 1 armremains after dropping arms for futility, the trial will be stopped withoutdeclaring the last arm superior.

futility_only_first

single logical in trial specifications designswherefutility_prob andfutility_diff are specified, otherwiseNULL(default and required in designs without a commoncontrol arm).Specifies whether futility will only be assessed against the firstcontrol (ifTRUE) or also for subsequent control arms (ifFALSE) ifone arm is superior to the first control and becomes the new control.

highest_is_best

single logical, specifies whether larger estimates ofthe outcome are favourable or not; defaults toFALSE, corresponding to,e.g., an undesirable binary outcomes (e.g., mortality) or a continuousoutcome where lower numbers are preferred (e.g., hospital length of stay).

soften_power

either a single numeric value or a numeric vector ofexactly the same length as the maximum number of looks/adaptive analyses.Values must be between0 and1 (default); if< 1, then re-allocatednon-fixed allocation probabilities are all raised to this power (followedby rescaling to sum to1) to make adaptive allocation probabilitiesless extreme, in turn used to redistribute remaining probability whilerespecting limits when defined bymin_probs and/ormax_probs. If1,then nosoftening is applied.

cri_width

single numeric>= 0 and< 1, the width of thepercentile-based credible intervals used when summarising individual trialresults. Defaults to0.95, corresponding to 95% credible intervals.

n_draws

single integer, the number of draws from the posteriordistributions for each arm used when running the trial. Defaults to5000; can be reduced for a speed gain (at the potential loss of stabilityof results if too low) or increased for increased precision (increasingsimulation time). Values< 100 are not allowed and values< 1000 arenot recommended and warned against.

robust

single logical, ifTRUE (default) the medians and medianabsolute deviations (scaled to be comparable to the standard deviation fornormal distributions; MAD_SDs, seestats::mad()) are used to summarisethe posterior distributions; ifFALSE, the means and standard deviations(SDs) are used instead (slightly faster, but may be less appropriate forposteriors skewed on the natural scale).

description

character string, default is"generic binomially distributed outcome trial". See arguments ofsetup_trial().

Value

Atrial_spec object used to run simulations byrun_trial() orrun_trials(). The output is essentially a list containing the inputvalues (some combined in adata.frame calledtrial_arms), but its classsignals that these inputs have been validated and inappropriatecombinations and settings have been ruled out. Also containsbest_arm,holding the arm(s) with the best value(s) intrue_ys. Usestr() toperuse the actual content of the returned object.

Examples

# Setup a trial specification using a binary, binomially# distributed, undesirable outcomebinom_trial<-setup_trial_binom(  arms=c("Arm A","Arm B","Arm C"),  true_ys=c(0.25,0.20,0.30),# Minimum allocation of 15% in all arms  min_probs=rep(0.15,3),  data_looks=seq(from=300, to=2000, by=100),# Stop for equivalence if > 90% probability of# absolute differences < 5 percentage points  equivalence_prob=0.9,  equivalence_diff=0.05,  soften_power=0.5# Limit extreme allocation ratios)# Print using 3 digits for probabilitiesprint(binom_trial, prob_digits=3)#> Trial specification: generic binomially distributed outcome trial#> * Undesirable outcome#> * No common control arm#> * Best arm: Arm B#>#> Arms, true outcomes, starting allocation probabilities#> and allocation probability limits:#>   arms true_ys start_probs fixed_probs min_probs max_probs#>  Arm A    0.25       0.333          NA      0.15        NA#>  Arm B    0.20       0.333          NA      0.15        NA#>  Arm C    0.30       0.333          NA      0.15        NA#>#> Maximum sample size: 2000#> Maximum number of data looks: 18#> Planned data looks after:  300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000 patients have reached follow-up#> Number of patients randomised at each look:  300, 400, 500, 600, 700, 800, 900, 1000, 1100, 1200, 1300, 1400, 1500, 1600, 1700, 1800, 1900, 2000#>#> Superiority threshold: 0.99 (all analyses)#> Inferiority threshold: 0.01 (all analyses)#> Equivalence threshold: 0.9 (all analyses) (no common control)#> Absolute equivalence difference: 0.05#> No futility threshold (not relevant - no common control)#> Soften power for all analyses: 0.5