Package 'BATSS' reference manual

Title:	Bayesian Adaptive Trial Simulator Software (BATSS) for Generalised Linear Models
Description:	Defines operating characteristics of Bayesian Adaptive Trials considering a generalised linear model response via Monte Carlo simulations of Bayesian GLM fitted via integrated Laplace approximations (INLA).
Authors:	Dominique-Laurent Couturier [aut, cre] , Liz Ryan [aut] , Rainer Puhr [aut], Thomas Jaki [aut] , Stephane Heritier [aut]
Maintainer:	Dominique-Laurent Couturier <[email protected]>
License:	GPL-2
Version:	1.0.0
Built:	2024-11-01 06:10:42 UTC
Source:	https://github.com/batss-dev/batss

Balanced allocation function

Description

alloc.balanced first allocates the largest possible number of units to the different groups given their exact target probabilities and then assigns randomly the remaining units to the different groups according to multinomial draws. This method leads to observed allocation probabilities matching the target ones when m*prob is an integer for each group and to observed allocation probabilities (on average) closer to the target ones compared to alloc.simple.

Usage

alloc.balanced(m, prob)
alloc.balanced(m, prob)

Arguments

`m`	the 'BATSS' ingredient '`m`', a scalar corresponding to the number of participants to be allocated.
`prob`	the 'BATSS' ingredient '`prob`', a named vector of allocation ratios or probabilities.

Value

alloc.balanced returns an object of class factor of length 'm' with levels matching the names of the vector 'prob'.

Examples

alloc.balanced(100, prob = c(A=.4,B=.6))
table(alloc.balanced(100, prob = c(A=.4,B=.6)))
table(alloc.balanced(100, prob = c(A=.4,B=.6)))
alloc.balanced(100, prob = c(A=.4,B=.6))
table(alloc.balanced(100, prob = c(A=.4,B=.6)))
table(alloc.balanced(100, prob = c(A=.4,B=.6)))

Simple allocation function

Description

alloc.simple independently randomises each unit to a group (i.e., flips a coin for each unit) so that the observed allocation probabilities may be far from the target ones. This strategy is often considered to be a poor choice.

Usage

alloc.simple(m, prob)
alloc.simple(m, prob)

Arguments

`m`	the 'BATSS' ingredient '`m`', a scalar corresponding to the number of participants to be allocated.
`prob`	the 'BATSS' ingredient '`prob`', a named vector of allocation ratios or probabilities.

Value

alloc.simple returns an object of class factor of length 'm' with levels matching the names of the vector 'prob'.

Examples

alloc.simple(100, prob = c(A=.4,B=.6))
table(alloc.simple(100, prob = c(A=.4,B=.6)))
table(alloc.simple(100, prob = c(A=.4,B=.6)))
alloc.simple(100, prob = c(A=.4,B=.6))
table(alloc.simple(100, prob = c(A=.4,B=.6)))
table(alloc.simple(100, prob = c(A=.4,B=.6)))

BATSS

Description

BATSS

Combines outputs generated by batss.glm

Description

Combines different evaluations of batss.glm considering the same trial design but different sets of seeds. This function is useful when the evaluation of Monte Carlo samples generated by different seeds was split in sets computed by different nodes/cpus. The output of this function is of class 'batss' meaning that the usual generic functions (print, summary, plot) can be used.

Usage

batss.combine(paths, force = FALSE)
batss.combine(paths, force = FALSE)

Arguments

paths

Vector indicating the paths to the rdata files containing the outputs of the function batss.glm considering the same trial design but different set of seeds. This requires the argument 'extended' of the function batss.glm to be > 0.

force

a logical with default force=FALSE. Among other checks, batss.glm controls that the calls of the Monte Carlo trials to be combined are identical and stops if they are not (Note that this check is not bullet proof: such a check, for example, would be able to note that two sets of Monte Carlo trials used a eff.arm function named the same way and considered the same optional parameters but would be blind to the fact that they could correspond to two different functions). force=TRUE forces batss.glm to ignore this check. This could be useful if the calls differ due to the batss objects to be combined being generated using different versions of batss.glm.

Value

an object of class 'batss'. Refer to the section 'Value' in batss.glm for details about this object structure.

Bayesian adaptive trial simulations for generalised linear models

Description

Simulation of Bayesian adaptive trials with GLM endpoint using Integrated Nested Laplace Approximation (INLA).

Usage

batss.glm(
  model,
  var,
  var.control = NULL,
  family = "gaussian",
  link = "identity",
  beta,
  which,
  alternative = "greater",
  R = 10000,
  N,
  interim,
  prob0,
  delta.eff = 0,
  delta.fut = delta.eff,
  delta.RAR = 0,
  eff.arm,
  eff.arm.control = NULL,
  eff.trial = NULL,
  eff.trial.control = NULL,
  fut.arm,
  fut.arm.control = NULL,
  fut.trial = NULL,
  fut.trial.control = NULL,
  RAR = NULL,
  RAR.control = NULL,
  H0 = TRUE,
  computation = "parallel",
  mc.cores = getOption("mc.cores", 3L),
  extended = 0,
  ...
)
batss.glm(
  model,
  var,
  var.control = NULL,
  family = "gaussian",
  link = "identity",
  beta,
  which,
  alternative = "greater",
  R = 10000,
  N,
  interim,
  prob0,
  delta.eff = 0,
  delta.fut = delta.eff,
  delta.RAR = 0,
  eff.arm,
  eff.arm.control = NULL,
  eff.trial = NULL,
  eff.trial.control = NULL,
  fut.arm,
  fut.arm.control = NULL,
  fut.trial = NULL,
  fut.trial.control = NULL,
  RAR = NULL,
  RAR.control = NULL,
  H0 = TRUE,
  computation = "parallel",
  mc.cores = getOption("mc.cores", 3L),
  extended = 0,
  ...
)

Arguments

`model`	an object of class 'formula' indicating a symbolic description of the model to be fitted (as in the lm and glm functions).
`var`	A list. Each entry corresponds to a variable described under '`model`' and indicates the name of a function allowing to generate variates (like rnorm and rexp, for example). The list names have to match the variable names unded in '`model`' and its first element should correspond to the model outcome. The grouping variable corresponding to the target parameters has to be of class 'factor' with levels corresponding to the names indicated in argument `prob0` (see below).
`var.control`	An optional list of control parameters for the functions indicated in '`var`'. The names of the list items need to correspond to the names used in '`var`'. Each element is another list with names of the elements corresponding to the parameter names of the functions specified in '`var`'.
`family`	A character string indicating the name of the conditional distribution as described in the package INLA (check inla.list.models). Default set to '`gaussian`'.
`link`	A character string describing the link function to be used in the model to relate the outcome to the set of predictors: 'identity', 'log', 'logit', 'probit', 'robit', 'cauchit', 'loglog' and 'cloglog' are the currently available options. Default set to 'identity'.
`beta`	A numerical vector of parameter values for the linear predictor. Its length has to match the number of column of the X matrix induced by the formula indicated under '`model`' (check model.matrix).
`which`	A numerical vector indicating the position of the target `beta` parameters.
`alternative`	A vector of strings providing the one-sided direction of the alternative hypothesis corresponding to each target parameter indicated under '`which`' (in the same order). Possibilities are 'greater' (default) or 'less'. If the vector is of length 1, the same direction will be used for all target parameter tests.
`R`	a vector of natural numbers to be used as seeds (check set.seed) for the different Monte Carlo trials (the vector length will thus correspond to the number of Monte Carlo trials). When `R` is a scalar, seeds `1` to `R` are used, where `R` corresponds to the number of Monte Carlo trials.
`N`	A scalar indicating the maximum sample size.
`interim`	A list of parameters related to interim analyses. Currently, only '`recruited`' is available. It consists in a vector of integers indicating the number of completed observations at each look, last excluded, in increasing order.
`prob0`	A named vector with initial allocation probabilities. Names need to correspond to the levels of the grouping variable. If `RAR = NULL`, these probabilities/ratios will be used throughout (fixed allocation probabilities).
`delta.eff`	A vector (of length equal to the number of looks (i.e., number of interims + 1)) of clinically meaningful treatment effect values (on the linear predictor scale) to be used to define the efficacy-related posterior probabilities for each target parameter at each look. If a scalar is provided, the same value is used at each look. The default is `delta.eff = 0`.
`delta.fut`	A vector (of length equal to the number of looks (i.e., number of interims + 1)) of clinically meaningful treatment effect values (on the linear predictor scale) to be used to define the futility-related posterior probabilities for each target parameter at each look. If a scalar is provided, the same value is used at each look. The default is `delta.fut = delta.eff`.
`delta.RAR`	A vector (of length equal to the number of looks (i.e., number of interims + 1)) of clinically meaningful treatment effect values (on the linear predictor scale) to be used to define the RAR-related posterior probabilities for each target parameter at each look. If a scalar is provided, the same value is used at each interim analysis. The default is `delta.RAR = 0`. Note that, when a vector is provided, its last value is ignored as no randomisation is made at the last look.
`eff.arm`	A function defining if efficacy has been achieved at a given look given the information available at that stage a given target parameter. The output of this function must be a logical (of length 1). Arguments of this function will typically consider 'BATSS' ingredients. Check eff.arm.simple and eff.arm.infofract for examples.
`eff.arm.control`	An optional list of parameters for the function indicated in '`eff.arm`'.
`eff.trial`	A function defining if the trial can be stopped for efficacy given the output of the function indicated in '`eff.arm`'. The output of this function must be a logical of length one. Arguments of this function will typically only consider the 'BATSS' ingredient `eff.target`. Check eff.trial.all and eff.trial.any for examples. When `eff.trial = NULL` (default), the trial stops for efficacy when all target parameters are found to be effective (like in eff.trial.all).
`eff.trial.control`	An optional list of parameters for the function indicated in '`eff.trial`'.
`fut.arm`	A function defining if futility has been achieved at a given look given the information available at that stage for each target parameter. The output of this function must be a logical (of length 1). Arguments of this function will typically consider 'BATSS' ingredients. Check fut.arm.simple to see an example of such a function.
`fut.arm.control`	An optional list of parameters for the function indicated in '`fut.arm`'.
`fut.trial`	A function defining if the trial can be stopped for futility given the output of the function indicated in '`fut.arm`'. The output of this function must be a logical of length one. Arguments of this function will typically only consider the 'BATSS' ingredient `fut.target`. Check fut.trial.all for an example of such a function. When `fut.trial = NULL` (default), the trial stops for futility when all target parameters are found to be futile (like in fut.trial.all).
`fut.trial.control`	An optional list of parameters for the function indicated in '`fut.trial`'.
`RAR`	A function defining the response-adaptive randomisation probabilities of each group - reference group included - with the same group names and ordering as used in '`prob0`'. Arguments of this function will typically consider 'BATSS' ingredients. Check RAR.trippa and RAR.optimal for examples. If `RAR = NULL` (default), the probabilities/ratios indicated under `prob0` will be used throughout (fixed allocation probabilities).
`RAR.control`	An optional list of control parameters for the function provided in '`RAR`'.
`H0`	A logical indicating whether the simulation should also consider the case with all target parameters set to 0 to check the probability of rejecting the hypothesis that the target parameter value is equal to 0 individually (pairwise type I error) or globally (family-wise error rate). Default set to `H0=TRUE`.
`computation`	A character string indicating how the computation should be performed. Possibilities are 'parallel' or 'sequential' with default `computation="parallel"` meaning that the computation is split between `mc.cores`.
`mc.cores`	An integer indicating the number of CPUs to be used when `computation="parallel"` (Default to 3 if no global '`mc.cores`' global option is available via getOption).
`extended`	an integer indicating the type of results to be returned. 0 (default) provides summary statistics, 1 adds the results of each Monte Carlo trial and 2 additionally returns each Monte Carlo dataset. batss.combine requires extended > 0 as the function needs to merge results of different sets of seeds.
`...`	Additional arguments to control fitting in inla.

Value

The function batss.glm returns an S3 object of class 'batss' with available print/summary/plot functions

beta - A data frame providing information related to the beta parameter vector, like parameter names and values, for example.
look - A data frame providing information related to looks, like sample size of a given interim (m) and cumulative sample size at a given interim (n), for example.
par - A list providing different information, like the used seeds (seed) and the groups (group), for example.
H1 - A list providing trial results under the alternative, like the estimates per target parameter when the corresponding arm was stopped (estimate), the efficacy and futility probabilites per target parameter and overall (target, efficacy and futility), the sample size per group and trial (sample), the probabilities associated to each combination of efficacy and futility per group (scenario), the detailed results per trial (trial), for example.
H0 - A list providing trial results under the global null hypothesis (same structure as H1).
call - The matched call.
type - The type of 'BATSS' analysis (only 'glm' is currently available).

Examples


# Example: 
# * Gaussian conditional distribution with sigma = 5
# * 3 groups with group means 'C' = 1 (ref), 'T1' = 2, 'T2' = 3,
#     where higher means correspond to better outcomes 
# * 5 interim analyses occurring when n = 100, 120, 140, 160, and 180
# * fixed and equal allocation probabilities per arm (i.e., no RAR)
# * max sample size = 200 
# * efficacy stop per arm when the prob of the corresponding parameter 
#     being greater than 0 is greater than 0.975 (?eff.arm.simple)
# * futility stop per arm when the prob of the corresponding parameter 
#     being greater than 0 is smaller than 0.05 (?fut.arm.simple) 
# * trial stop once all arms have stopped (?eff.trial.all and ?fut.trial.all)
#     or the max sample size was reached 

sim = batss.glm(model            = y ~ group,   
                var              = list(y     = rnorm,
                                        group = alloc.balanced),
                var.control      = list(y = list(sd = 5)),
                beta             = c(1, 1, 2),
                which            = c(2:3),
                alternative      = "greater",
                R                = 20,
                N                = 200,
                interim          = list(recruited = seq(100, 180, 20)),
                prob0            = c(C = 1/3, T1 = 1/3, T2 = 1/3),
                eff.arm          = eff.arm.simple,
                eff.arm.control  = list(b = 0.975),
                fut.arm          = fut.arm.simple,
                fut.arm.control  = list(b = 0.05),
                computation      = "parallel",
                H0               = TRUE,
                mc.cores         = 2)# better: parallel::detectCores()-1

# Example: 
# * Gaussian conditional distribution with sigma = 5
# * 3 groups with group means 'C' = 1 (ref), 'T1' = 2, 'T2' = 3,
#     where higher means correspond to better outcomes 
# * 5 interim analyses occurring when n = 100, 120, 140, 160, and 180
# * fixed and equal allocation probabilities per arm (i.e., no RAR)
# * max sample size = 200 
# * efficacy stop per arm when the prob of the corresponding parameter 
#     being greater than 0 is greater than 0.975 (?eff.arm.simple)
# * futility stop per arm when the prob of the corresponding parameter 
#     being greater than 0 is smaller than 0.05 (?fut.arm.simple) 
# * trial stop once all arms have stopped (?eff.trial.all and ?fut.trial.all)
#     or the max sample size was reached 

sim = batss.glm(model            = y ~ group,   
                var              = list(y     = rnorm,
                                        group = alloc.balanced),
                var.control      = list(y = list(sd = 5)),
                beta             = c(1, 1, 2),
                which            = c(2:3),
                alternative      = "greater",
                R                = 20,
                N                = 200,
                interim          = list(recruited = seq(100, 180, 20)),
                prob0            = c(C = 1/3, T1 = 1/3, T2 = 1/3),
                eff.arm          = eff.arm.simple,
                eff.arm.control  = list(b = 0.975),
                fut.arm          = fut.arm.simple,
                fut.arm.control  = list(b = 0.05),
                computation      = "parallel",
                H0               = TRUE,
                mc.cores         = 2)# better: parallel::detectCores()-1

information-fraction based arm efficacy stop

Description

allows stopping an arm for efficacy at a given look when the probability of the corresponding target parameter being greater or smaller (depending on the argument 'alternative' of batss.glm) than delta.eff is greater than a function of the information fraction at that look.

Usage

eff.arm.infofract(posterior, b, n, N, p)
eff.arm.infofract(posterior, b, n, N, p)

Arguments

`posterior`	the 'BATSS' ingredient '`posterior`' corresponding, in this context, to the (posterior) probability of the target parameter being greater or smaller (depending on the argument `'alternative'` of batss.glm) than '`delta.eff`'.
`b`	a tuning parameter (to be defined in `eff.arm.control`).
`n`	the 'BATSS' ingredient '`n`' corresponding to the vector of number of recruited participants per arm including the control group.
`N`	the 'BATSS' ingredient '‘N’ corresponding to the maximum (planned) sample size.
`p`	a tuning parameter (to be defined in `eff.arm.control`).

Value

eff.arm.infofract returns a logical constant.

Simple arm efficacy stop

Description

Usage

eff.arm.simple(posterior, b)
eff.arm.simple(posterior, b)

Arguments

`posterior`	the 'BATSS' ingredient '`posterior`' corresponding, in this context, to the (posterior) probability of the target parameter being greater or smaller (depending on the argument `'alternative'` of batss.glm) than '`delta.eff`'.
`b`	the cut-off value used to declare efficacy (to be defined in `eff.arm.control`).

Value

eff.arm.simple returns a logical constant.

trial efficacy stop

Description

allows stopping the trial for efficacy if all target parameters reached efficacy at the look of interest or before.

Usage

eff.trial.all(eff.target)
eff.trial.all(eff.target)

Arguments

eff.target

the 'BATSS' ingredient 'eff.target' corresponding to a logical vector of the same length as argument which (i.e., the number of target parameters) indicating if efficacy was reached for each target parameter at that stage or at a previous stage.

Value

eff.trial.all returns a logical constant.

trial efficacy stop

Description

allows stopping the trial for efficacy if at least one target parameter reached efficacy at the look of interest.

Usage

eff.trial.any(eff.target)
eff.trial.any(eff.target)

Arguments

eff.target

Value

eff.trial.any returns a logical constant.

arm futility stop

Description

allows stopping an arm for futility when the probability of the corresponding target parameter being greater or smaller (depending on the argument 'alternative' of batss.glm) than 'delta.fut' is smaller than a fixed value 'b'

Usage

fut.arm.simple(posterior, b)
fut.arm.simple(posterior, b)

Arguments

`posterior`	the 'BATSS' ingredient '`posterior`' corresponding, in this context, to the (posterior) probability of the target parameter being greater or smaller (depending on the argument `'alternative'` of batss.glm) than '`delta.fut`'.
`b`	the cut-off value used to declare futility (to be defined in `fut.arm.control`).

Value

fut.arm.simple returns a logical constant.

trial futility stop

Description

allows stopping the trial for efficacy if all active treatment reached futility at the look of interest or before.

Usage

fut.trial.all(fut.target)
fut.trial.all(fut.target)

Arguments

fut.target

the 'BATSS' ingredient 'fut.target' corresponding to a logical vector of the same length as argument which (i.e., the number of target parameters) indicating if futility was declared for each target parameter at that stage or at a previous stage.

Value

fut.trial.all returns a logical constant.

Plot function for 'BATSS' outputs

Description

Plot for objects of class 'batss'

Usage

## S3 method for class 'batss'
plot(
  x,
  type = "size",
  hypothesis = "H1",
  title = TRUE,
  legend = TRUE,
  col = c("#008B0040", "#8B3A3A40", "#8B897040", "#FF990075", "blue"),
  ...
)
## S3 method for class 'batss'
plot(
  x,
  type = "size",
  hypothesis = "H1",
  title = TRUE,
  legend = TRUE,
  col = c("#008B0040", "#8B3A3A40", "#8B897040", "#FF990075", "blue"),
  ...
)

Arguments

`x`	An object of class 'batss' (i.e., output of the function batss.glm).
`type`	A character string indicating the type of plot with options 'size' (default) to display the total and per group sample size observed in the Monte Carlo trials, and 'estimates' to display the Monte Carlo trial target estimates as a function of the sample size.
`hypothesis`	A character string indicating which alternative hypothesis to use for analyses considering both "H0" and "H1", with options "H1" (default) and "H0".
`title`	Either a logical indicating if a title should be added or a string (of class character) indicating the title to be added. If `title` equals `TRUE` (default), the title 'Under 'H1' or 'Under 'H0' (depending on the argument `hypothesis`) is added to the outer margin of the plot. No outer margin space is added if `title = FALSE`.
`legend`	a logical (with default set to `TRUE`) indicating if, when '`type = estimates`', a legend should be added at the bottom of the plot.
`col`	a vector of length 5 specifiying the colour respectively assigned to i/ efficacy, ii/ futility, iii/ neither or iv/ both when color-coding trials when `type = "estimates"`. The 5th colour is used for lines. Default to c("#8B897040","#008B0040","#8B3A3A40","#FF990075","blue") where the 2 last digits of the long hexadecimal strings of colours 1 to 4 specify the level of transluency. Refer to the Section 'colour specification' in par for details. If the length of `col` equals 1, the same colour is used for all cases. When `type = "size"`, the 3rd and 5th colours of the vector `col` are used to display boxplots and lines.
`...`	Additional arguments affecting the plot produced, like ylim and ylab.

Value

Generates graphical displays of results for objects of class 'batss'.

Print function for BATSS outputs

Description

Print method function for objects of class 'batss' (i.e., output of the function batss.glm).

Usage

## S3 method for class 'batss'
print(x, ...)
## S3 method for class 'batss'
print(x, ...)

Arguments

`x`	An object of class 'batss'.
`...`	Additional arguments affecting the print produced.

Value

Prints information for objects of class 'batss'.

'Optimal' control allocation

Description

technically not response adaptive but keeps allocation ratio to control at the square root of active intervention arms

Usage

RAR.optimal(active)
RAR.optimal(active)

Arguments

active

the 'BATSS' ingredient 'active' corresponding to a logical vector of the same length and order as 'prob0' (i.e., number of arms initially included in the study including the reference group)) and indicating if each arm is active at the look of interest.

Value

RAR.optimal returns a vector of probabilities with length of active.

RAR of Trippa et al. (2012)

Description

define the group allocation probabilities based on the response adaptive randomisation rule of Trippa et al. (2012)

Usage

RAR.trippa(posterior, n, N, ref, active, gamma, eta, nu)
RAR.trippa(posterior, n, N, ref, active, gamma, eta, nu)

Arguments

`posterior`	the 'BATSS' ingredient '`posterior`' corresponding, in this context, to the (posterior) probability of the active target parameters being greater or smaller (depending on the argument `'alternative'` of batss.glm) than '`delta.RAR`'.
`n`	the 'BATSS' ingredient '`n`' corresponding to the vector of number of recruited participants per arm including the control group at the look of interest.
`N`	the 'BATSS' ingredient '‘N’ corresponding to the maximum (planned) sample size.
`ref`	the 'BATSS' ingredient '`ref`' corresponding to a logical vector of the same length and order as `'prob0'` (i.e., number of arms initially included in the study including the reference group)) and indicating which group is the reference one.
`active`	the 'BATSS' ingredient '`active`' corresponding to a logical vector of the same length and order as `'prob0'` (i.e., number of arms initially included in the study including the reference group)) and indicating if each arm is active at the look of interest.
`gamma`	a scaling factor (to be defined in `RAR.arm.control`).
`eta`	a scaling factor (to be defined in `RAR.arm.control`).
`nu`	a scaling factor (to be defined in `RAR.arm.control`).

Value

RAR.trippa returns a vector of probabilities with length of active.

Summary function for 'BATSS' outputs

Description

Summary method function for objects of class 'batss'.

Usage

## S3 method for class 'batss'
summary(object, full = FALSE, ...)
## S3 method for class 'batss'
summary(object, full = FALSE, ...)

Arguments

`object`	An object of class 'batss' (i.e., output of the function batss.glm).
`full`	A logical indicating if a standard (full = FALSE, default) or extended output (full = TRUE) should be returned.
`...`	Additional arguments affecting the summary produced.

Value

Prints a summary for objects of class 'batss'.

Package 'BATSS'

Help Index

Balanced allocation function

Description

Usage

Arguments

Value

See Also

Examples

Simple allocation function

Description

Usage

Arguments

Value

See Also

Examples

BATSS

Description

Combines outputs generated by batss.glm

Description

Usage

Arguments

Value

See Also

Bayesian adaptive trial simulations for generalised linear models

Description

Usage

Arguments

Value

See Also

Examples

information-fraction based arm efficacy stop

Description

Usage

Arguments

Value

Simple arm efficacy stop

Description

Usage

Arguments

Value

trial efficacy stop

Description

Usage

Arguments

Value

trial efficacy stop

Description

Usage

Arguments

Value

arm futility stop

Description

Usage

Arguments

Value

trial futility stop

Description

Usage

Arguments

Value

Plot function for 'BATSS' outputs

Description

Usage

Arguments

Value

See Also

Print function for BATSS outputs

Description

Usage

Arguments

Value

See Also

'Optimal' control allocation

Description

Usage

Arguments

Value

RAR of Trippa et al. (2012)

Description