Package 'adoptr'

Description

The adoptr package provides functionality to explore custom optimal two-stage designs for one- or two-arm superiority tests. For more details on the theoretical background see doi:10.1002/sim.8291 and doi:10.18637/jss.v098.i09. adoptr makes heavy use of the S4 class system. A good place to start learning about it can be found here.

Quickstart

For a sample workflow and a quick demo of the capabilities, see here.

A more detailed description of the background and the usage of adoptr can be found here or here doi:10.18637/jss.v098.i09 .

A variety of examples is presented in the validation report hosted here.

Designs

adoptr currently supports TwoStageDesign, GroupSequentialDesign, and OneStageDesign.

Data distributions

The implemented data distributions are Normal, Binomial, Student, Survival, ChiSquared (including Pearson2xK and ZSquared) and ANOVA.

Priors

Both ContinuousPrior and PointMassPrior are supported for the single parameter of a DataDistribution.

Scores

See Scores for information on the basic system of representing scores. Available scores are ConditionalPower, ConditionalSampleSize, Power, and ExpectedSampleSize.

Author(s)

Maintainer: Maximilian Pilz [email protected] (ORCID)

Authors:

• Kevin Kunzmann [email protected] (ORCID) [copyright holder]

• Jan Meis [email protected] (ORCID)

• Nico Bruder [email protected] (ORCID)

See Also

Useful links:

• https://github.com/optad/adoptr

• https://optad.github.io/adoptr/

• Report bugs at https://github.com/optad/adoptr/issues

Description

ANOVA is used to test whether there is a significant difference between the means of groups. The sample size which adoptr returns is the group wise sample size. The function get_tau_ANOVA is used to obtain a parameter $\tau$, which is used in the same way as $\theta$ to describe the difference of means between the groups.

Usage

ANOVA(n_groups)

get_tau_ANOVA(means, common_sd = 1)

Arguments

See Also

see probability_density_function and cumulative_distribution_function to evaluate the pdf and the cdf, respectively. Use NestedModels to get insights in the implementation of ANOVA.

Examples

model <- ANOVA(3L)

H1 <- PointMassPrior(get_tau_ANOVA(c(0.4, 0.8, 0.5)), 1)

Description

Implements the L1-norm of the design's stage-two sample size function. The average of the stage-two sample size without weighting with the data distribution is computed. This can be interpreted as integration over a unifrom prior on the continuation region.

Usage

AverageN2(label = NA_character_)

## S4 method for signature 'AverageN2,TwoStageDesign'
evaluate(s, design, optimization = FALSE, subdivisions = 10000L, ...)

Arguments

Value

an object of class AverageN2

See Also

N1 for penalizing n1 values

Examples

avn2 <- AverageN2()

evaluate(
   AverageN2(),
   TwoStageDesign(100, 0.5, 1.5, 60.0, 1.96, order = 5L)
) # 60

Description

Implements the normal approximation for a test on rates. The reponse rate in the control group, r_C, has to be specified by rate_control. The null hypothesis is: r_E ≤ r_C, where r_E denotes the response rate in the invervention group. It is tested against the alternative r_E > r_C. The test statistic is given as X₁ = √n (r_E - r_C) / √(2 r₀ (1-r₀)), where r₀ denotes the mean between r_E and r_C in the two-armed case, and r_E in the one-armed case.#' All priors have to be defined for the rate difference r_E - r_C.

Usage

Binomial(rate_control, two_armed = TRUE)

## S4 method for signature 'Binomial'
quantile(x, probs, n, theta, ...)

## S4 method for signature 'Binomial,numeric'
simulate(object, nsim, n, theta, seed = NULL, ...)

Arguments

Details

Note that simulate for class Binomial simulates the normal approximation of the test statistic.

Slots

rate_control

cf. parameter 'rate_control'

See Also

see probability_density_function and cumulative_distribution_function to evaluate the pdf and the cdf, respectively.

Examples

datadist <- Binomial(rate_control = 0.2, two_armed = FALSE)

Description

bounds() returns the range of the support of a prior or data distribution.

Usage

bounds(dist, ...)

## S4 method for signature 'ContinuousPrior'
bounds(dist, ...)

## S4 method for signature 'PointMassPrior'
bounds(dist, ...)

Arguments

Value

numeric of length two, c(lower, upper)

Examples

bounds(ContinuousPrior(function(x) dunif(x, .2, .4), c(.2, .4)))
# > 0.2 0.4

bounds(PointMassPrior(c(0, .5), c(.3, .7)))
# > 0.3 0.7

Description

Methods to access the stage-two critical values of a TwoStageDesign. c2 returns the stage-two critical value conditional on the stage-one test statistic.

Usage

c2(d, x1, ...)

## S4 method for signature 'TwoStageDesign,numeric'
c2(d, x1, ...)

## S4 method for signature 'OneStageDesign,numeric'
c2(d, x1, ...)

Arguments

Value

the critical value function c2 of design d at position x1

See Also

TwoStageDesign, see n for accessing the sample size of a design

Examples

design <- TwoStageDesign(
  n1    = 25,
  c1f   = 0,
  c1e   = 2.5,
  n2    = 50,
  c2    = 1.96,
  order = 7L
)

c2(design, 2.2) # 1.96
c2(design, 3.0) # -Inf
c2(design, -1.0) # Inf

design <- TwoStageDesign(
   n1    = 25,
   c1f   = 0,
   c1e   = 2.5,
   n2    = 50,
   c2    = 1.96,
   order = 7L
)

c2(design, 2.2) # 1.96
c2(design, 3.0) # -Inf
c2(design, -1.0) # Inf

Description

Implements a chi-squared distribution. The classes Pearson2xk and ZSquared are subclasses, used in two different situations. Pearson2xK is used when testing k groups for homogeneity in response rates. The null hypothesis is r₁=...=r_k, and the alternative is that there exists a pair of groups with differing rates. ZSquared implements the square of a normally distributed random variable with mean $\mu$ and standard deviation $\sigma^2$.

Usage

ChiSquared(df)

## S4 method for signature 'ChiSquared'
quantile(x, probs, n, theta, ...)

## S4 method for signature 'ChiSquared,numeric'
simulate(object, nsim, n, theta, seed = NULL, ...)

Arguments

See Also

see probability_density_function and cumulative_distribution_function to evaluate the pdf and the cdf, respectively.

Examples

datadist <- ChiSquared(df=4)

Description

composite defines new composite scores by point-wise evaluation of scores in any valid numerical expression.

Usage

composite(expr, label = NA_character_)

## S4 method for signature 'CompositeScore,TwoStageDesign'
evaluate(s, design, ...)

Arguments

Value

an object of class CompositeConditionalScore or CompositeUnconditionalScore depending on the class of the scores used in expr

See Also

Scores

Examples

ess   <- ExpectedSampleSize(Normal(), PointMassPrior(.4, 1))
power <- Power(Normal(), PointMassPrior(.4, 1))

# linear combination:
composite({ess - 50*power})

# control flow (e.g. for and while loops)
composite({
  res <- 0
  for (i in 1:3) {
     res <- res + ess
  }
  res
})

# functional composition
composite({log(ess)})
cp <- ConditionalPower(Normal(), PointMassPrior(.4, 1))
composite({3*cp})

Description

Restrict an object of class Prior to a sub-interval and re-normalize the PDF.

Usage

condition(dist, interval, ...)

## S4 method for signature 'ContinuousPrior,numeric'
condition(dist, interval, ...)

## S4 method for signature 'PointMassPrior,numeric'
condition(dist, interval, ...)

Arguments

Value

conditional Prior on given interval

Examples

tmp <- condition(
    ContinuousPrior(function(x) dunif(x, .2, .4), c(.2, .4)),
    c(.3, .5)
)
bounds(tmp) # c(.3, .4)

tmp <- condition(PointMassPrior(c(0, .5), c(.3, .7)), c(-1, .25))
expectation(tmp, identity) # 0

Description

This score evaluates P[X₂ > c2(design, X₁) | X₁ = x₁]. Note that the distribution of X₂ is the posterior predictive after observing X₁ = x₁.

Usage

ConditionalPower(dist, prior, label = "Pr[x2>=c2(x1)|x1]")

Power(dist, prior, label = "Pr[x2>=c2(x1)]")

## S4 method for signature 'ConditionalPower,TwoStageDesign'
evaluate(s, design, x1, optimization = FALSE, ...)

Arguments

See Also

Scores

Examples

prior <- PointMassPrior(.4, 1)
cp <- ConditionalPower(Normal(), prior)
evaluate(
   cp,
   TwoStageDesign(50, .0, 2.0, 50, 2.0, order = 5L),
   x1 = 1
)
# these two are equivalent:
expected(cp, Normal(), prior)
Power(Normal(), prior)

Description

This score simply evaluates n(d, x1) for a design d and the first-stage outcome x1. The data distribution and prior are only relevant when it is integrated.

Usage

ConditionalSampleSize(label = "n(x1)")

ExpectedSampleSize(dist, prior, label = "E[n(x1)]")

ExpectedNumberOfEvents(dist, prior, label = "E[n(x1)]")

## S4 method for signature 'ConditionalSampleSize,TwoStageDesign'
evaluate(s, design, x1, optimization = FALSE, ...)

Arguments

See Also

Scores

Examples

design <- TwoStageDesign(50, .0, 2.0, 50, 2.0, order = 5L)
prior  <- PointMassPrior(.4, 1)

css   <- ConditionalSampleSize()
evaluate(css, design, c(0, .5, 3))

ess   <- ExpectedSampleSize(Normal(), prior)
ene <- ExpectedNumberOfEvents(Survival(0.7), PointMassPrior(1.7, 1))

# those two are equivalent
evaluate(ess, design)
evaluate(expected(css, Normal(), prior), design)

Description

Conceptually, constraints work very similar to scores (any score can be put in a constraint). Currently, constraints of the form 'score <=/>= x', 'x <=/>= score' and 'score <=/>= score' are admissible.

Usage

## S4 method for signature 'Constraint,TwoStageDesign'
evaluate(s, design, optimization = FALSE, ...)

## S4 method for signature 'ConditionalScore,numeric'
e1 <= e2

## S4 method for signature 'ConditionalScore,numeric'
e1 >= e2

## S4 method for signature 'numeric,ConditionalScore'
e1 <= e2

## S4 method for signature 'numeric,ConditionalScore'
e1 >= e2

## S4 method for signature 'ConditionalScore,ConditionalScore'
e1 <= e2

## S4 method for signature 'ConditionalScore,ConditionalScore'
e1 >= e2

## S4 method for signature 'UnconditionalScore,numeric'
e1 <= e2

## S4 method for signature 'UnconditionalScore,numeric'
e1 >= e2

## S4 method for signature 'numeric,UnconditionalScore'
e1 <= e2

## S4 method for signature 'numeric,UnconditionalScore'
e1 >= e2

## S4 method for signature 'UnconditionalScore,UnconditionalScore'
e1 <= e2

## S4 method for signature 'UnconditionalScore,UnconditionalScore'
e1 >= e2

Arguments

Value

an object of class Constraint

See Also

minimize

Examples

design <- OneStageDesign(50, 1.96)

cp     <- ConditionalPower(Normal(), PointMassPrior(0.4, 1))
pow    <- Power(Normal(), PointMassPrior(0.4, 1))

# unconditional power constraint
constraint1 <- pow >= 0.8
evaluate(constraint1, design)

# conditional power constraint
constraint2 <- cp  >= 0.7
evaluate(constraint2, design, .5)
constraint3 <- 0.7 <= cp # same as constraint2
evaluate(constraint3, design, .5)

Description

ContinuousPrior is a sub-class of Prior implementing a generic representation of continuous prior distributions over a compact interval on the real line.

Usage

ContinuousPrior(
  pdf,
  support,
  order = 10,
  label = NA_character_,
  tighten_support = FALSE,
  check_normalization = TRUE
)

Arguments

Slots

pdf

cf. parameter 'pdf'

support

cf. parameter 'support'

pivots

normalized pivots for integration rule (in [-1, 1]) the actual pivots are scaled to the support of the prior

weights

weights of of integration rule at pivots for approximating integrals over delta

See Also

Discrete priors are supported via PointMassPrior

Examples

ContinuousPrior(function(x) 2*x, c(0, 1))

Description

cumulative_distribution_function evaluates the cumulative distribution function of a specific distribution dist at a point x.

Usage

cumulative_distribution_function(dist, x, n, theta, ...)

## S4 method for signature 'Binomial,numeric,numeric,numeric'
cumulative_distribution_function(dist, x, n, theta, ...)

## S4 method for signature 'ChiSquared,numeric,numeric,numeric'
cumulative_distribution_function(dist, x, n, theta, ...)

## S4 method for signature 'NestedModels,numeric,numeric,numeric'
cumulative_distribution_function(dist, x, n, theta, ...)

## S4 method for signature 'Normal,numeric,numeric,numeric'
cumulative_distribution_function(dist, x, n, theta, ...)

## S4 method for signature 'Student,numeric,numeric,numeric'
cumulative_distribution_function(dist, x, n, theta, ...)

## S4 method for signature 'Survival,numeric,numeric,numeric'
cumulative_distribution_function(dist, x, n, theta, ...)

Arguments

Details

If the distribution is Binomial, theta denotes the rate difference between intervention and control group. Then, the mean is assumed to be √ n theta.

If the distribution is Normal, then the mean is assumed to be √ n theta.

Value

value of the cumulative distribution function at point x.

Examples

cumulative_distribution_function(Binomial(.1, TRUE), 1, 50, .3)

cumulative_distribution_function(Pearson2xK(3), 1, 30, get_tau_Pearson2xK(c(0.3,0.4,0.7,0.2)))
cumulative_distribution_function(ZSquared(TRUE), 1, 35, get_tau_ZSquared(0.4, 1))


cumulative_distribution_function(ANOVA(3), 1, 30, get_tau_ANOVA(c(0.3, 0.4, 0.7, 0.2)))

cumulative_distribution_function(Normal(), 1, 50, .3)

cumulative_distribution_function(Student(two_armed = FALSE), .75, 50, .9)

cumulative_distribution_function(Survival(0.6,TRUE),0.75,50,0.9)

Description

DataDistribution is an abstract class used to represent the distribution of a sufficient statistic x given a sample size n and a single parameter value theta.

Arguments

Details

This abstraction layer allows the representation of t-distributions (unknown variance), normal distribution (known variance), and normal approximation of a binary endpoint. Currently, the two implemented versions are Normal-class and Binomial-class.

The logical option two_armed allows to decide whether a one-arm or a two-arm (the default) design should be computed. In the case of a two-arm design all sample sizes are per group.

Slots

two_armed

Logical that indicates if a two-arm design is assumed.

Examples

normaldist   <- Normal(two_armed = FALSE)
binomialdist <- Binomial(rate_control = .25, two_armed = TRUE)

Description

Computes the expected value of a vectorized, univariate function f with respect to a distribution dist. I.e., E[f(X)].

Usage

expectation(dist, f, ...)

## S4 method for signature 'ContinuousPrior,function'
expectation(dist, f, ...)

## S4 method for signature 'PointMassPrior,function'
expectation(dist, f, ...)

Arguments

Value

numeric, expected value of f with respect to dist

Examples

expectation(
    ContinuousPrior(function(x) dunif(x, .2, .4), c(.2, .4)),
    identity
)
# > 0.3

expectation(PointMassPrior(c(0, .5), c(.3, .7)), identity)
# > .35

Description

The optimization method minimize requires an initial design for optimization. This function provides a variety of possibilities to hand-craft designs that fulfill type I error and type II error constraints which may be used as initial designs.

Usage

get_initial_design(
  theta,
  alpha,
  beta,
  type_design = c("two-stage", "group-sequential", "one-stage"),
  type_c2 = c("linear_decreasing", "constant"),
  type_n2 = c("optimal", "constant", "linear_decreasing", "linear_increasing"),
  dist = Normal(),
  cf,
  ce,
  info_ratio = 0.5,
  slope,
  weight = sqrt(info_ratio),
  order = 7L,
  ...
)

Arguments

Details

The distribution of the test statistic is specified by dist. The default assumes a two-armed z-test. The first stage efficacy boundary and the $c2$ boundary are chosen as Pocock-boundaries, so either $c_e=c_2$ if $c_2$ is constant or $c_e=c$, where the null hypothesis is rejected if $w_1 Z_1+w_2 Z_2>c$. By specifying $ce$, it's clear that the boundaries are not Pocock-boundaries anymore, so the type I error constraint may not be fulfilled. IMPORTANT: When using the t-distribution or ANOVA, the design does probably not keep the type I and type II error, only approximate designs are returned.

Value

An object of class TwoStageDesign.

Examples

init <- get_initial_design(
   theta = 0.3,
   alpha = 0.025,
   beta  = 0.2,
   type_design="two-stage",
   type_c2="linear_decreasing",
   type_n2="linear_increasing",
   dist=Normal(),
   cf=0.7,
   info_ratio=0.5,
   slope=23,
   weight = 1/sqrt(3)
)

Description

The optimization method minimize is based on the package nloptr. This requires upper and lower boundaries for optimization. Such boundaries can be computed via lower_boundary_design respectively upper_boundary_design. They are implemented by default in minimize. Note that minimize allows the user to define its own boundary designs, too.

Usage

get_lower_boundary_design(initial_design, ...)

get_upper_boundary_design(initial_design, ...)

## S4 method for signature 'OneStageDesign'
get_lower_boundary_design(initial_design, n1 = 1, c1_buffer = 2, ...)

## S4 method for signature 'GroupSequentialDesign'
get_lower_boundary_design(
  initial_design,
  n1 = 1,
  n2_pivots = 1,
  c1_buffer = 2,
  c2_buffer = 2,
  ...
)

## S4 method for signature 'TwoStageDesign'
get_lower_boundary_design(
  initial_design,
  n1 = 1,
  n2_pivots = 1,
  c1_buffer = 2,
  c2_buffer = 2,
  ...
)

## S4 method for signature 'OneStageDesign'
get_upper_boundary_design(
  initial_design,
  n1 = 5 * initial_design@n1,
  c1_buffer = 2,
  ...
)

## S4 method for signature 'GroupSequentialDesign'
get_upper_boundary_design(
  initial_design,
  n1 = 5 * initial_design@n1,
  n2_pivots = 5 * initial_design@n2_pivots,
  c1_buffer = 2,
  c2_buffer = 2,
  ...
)

## S4 method for signature 'TwoStageDesign'
get_upper_boundary_design(
  initial_design,
  n1 = 5 * initial_design@n1,
  n2_pivots = 5 * initial_design@n2_pivots,
  c1_buffer = 2,
  c2_buffer = 2,
  ...
)

Arguments

Value

An object of class TwoStageDesign.

Examples

initial_design <- TwoStageDesign(
  n1    = 25,
  c1f   = 0,
  c1e   = 2.5,
  n2    = 50,
  c2    = 1.96,
  order = 7L
  )
get_lower_boundary_design(initial_design)

Description

Group-sequential designs are a sub-class of the TwoStageDesign class with constant stage-two sample size. See TwoStageDesign for slot details. Any group-sequential design can be converted to a fully flexible TwoStageDesign (see examples section).

Usage

GroupSequentialDesign(n1, ...)

## S4 method for signature 'numeric'
GroupSequentialDesign(
  n1,
  c1f,
  c1e,
  n2_pivots,
  c2_pivots,
  order = NULL,
  event_rate,
  ...
)

## S4 method for signature 'GroupSequentialDesign'
TwoStageDesign(n1, event_rate, ...)

## S4 method for signature 'GroupSequentialDesignSurvival'
TwoStageDesign(n1, ...)

Arguments

See Also

TwoStageDesign for superclass and inherited methods

Examples

design <- GroupSequentialDesign(25, 0, 2, 25, c(1, 1.5, 2.5))
summary(design)

design_survival <- GroupSequentialDesign(25, 0, 2, 25, c(1, 1.5, 2.5), event_rate = 0.7)

TwoStageDesign(design)

TwoStageDesign(design_survival)

Description

Group-sequential designs for time-to-event-endpoints are a subclass of both TwoStageDesignSurvival and GroupSequentialDesign.

See Also

TwoStageDesignSurvival-class and GroupSequentialDesign-class for superclasses and inherited methods.

Description

The methods make_fixed and make_tunable can be used to modify the 'tunability' status of parameters in a TwoStageDesign object. Tunable parameters are optimized over, non-tunable ('fixed') parameters are considered given and not altered during optimization.

Usage

make_tunable(x, ...)

## S4 method for signature 'TwoStageDesign'
make_tunable(x, ...)

make_fixed(x, ...)

## S4 method for signature 'TwoStageDesign'
make_fixed(x, ...)

Arguments

Value

an updated object of class TwoStageDesign

See Also

TwoStageDesign, tunable_parameters for converting tunable parameters of a design object to a numeric vector (and back), and minimize for the actual minimzation procedure

Examples

design <- TwoStageDesign(25, 0, 2, 25, 2, order = 5)
# default: all parameters are tunable (except integration pivots,
# weights and tunability status itself)
design@tunable

# make n1 and the pivots of n2 fixed (not changed during optimization)
design <- make_fixed(design, n1, n2_pivots)
design@tunable

# make them tunable again
design <- make_tunable(design, n1, n2_pivots)
design@tunable

Description

This score evaluates max(n(d)) for a design d.

Usage

MaximumSampleSize(label = "max(n(x1))")

## S4 method for signature 'MaximumSampleSize,TwoStageDesign'
evaluate(s, design, optimization = FALSE, ...)

Arguments

See Also

Scores for general scores and ConditionalSampleSize for evaluating the sample size point-wise.

Examples

design <- TwoStageDesign(50, .0, 2.0, 50, 2.0, order = 5L)
mss    <- MaximumSampleSize()
evaluate(mss, design)

Description

minimize takes an unconditional score and a constraint set (or no constraint) and solves the corresponding minimization problem using nloptr (using COBYLA by default). An initial design has to be defined. It is also possible to define lower- and upper-boundary designs. If this is not done, the boundaries are determined automatically heuristically.

Usage

minimize(
  objective,
  subject_to,
  initial_design,
  lower_boundary_design = get_lower_boundary_design(initial_design),
  upper_boundary_design = get_upper_boundary_design(initial_design),
  c2_decreasing = FALSE,
  check_constraints = TRUE,
  opts = list(algorithm = "NLOPT_LN_COBYLA", xtol_rel = 1e-05, maxeval = 10000),
  ...
)

Arguments

Value

a list with elements:

Examples

# Define Type one error rate
toer <- Power(Normal(), PointMassPrior(0.0, 1))

# Define Power at delta = 0.4
pow <- Power(Normal(), PointMassPrior(0.4, 1))

# Define expected sample size at delta = 0.4
ess <- ExpectedSampleSize(Normal(), PointMassPrior(0.4, 1))

# Compute design minimizing ess subject to power and toer constraints

minimize(

   ess,

   subject_to(
      toer <= 0.025,
      pow  >= 0.9
   ),

   initial_design = TwoStageDesign(50, .0, 2.0, 60.0, 2.0, 5L)

)

Description

Methods to access the stage-one, stage-two, or overall sample size of a TwoStageDesign. n1 returns the first-stage sample size of a design, n2 the stage-two sample size conditional on the stage-one test statistic and n the overall sample size n1 + n2. Internally, objects of the class TwoStageDesign allow non-natural, real sample sizes to allow smooth optimization (cf. minimize for details). The optional argument round allows to switch between the internal real representation and a rounded version (rounding to the next positive integer).

Usage

n1(d, ...)

## S4 method for signature 'TwoStageDesign'
n1(d, round = TRUE, ...)

n2(d, x1, ...)

## S4 method for signature 'TwoStageDesign,numeric'
n2(d, x1, round = TRUE, ...)

n(d, x1, ...)

## S4 method for signature 'TwoStageDesign,numeric'
n(d, x1, round = TRUE, ...)

## S4 method for signature 'OneStageDesign,numeric'
n2(d, x1, ...)

## S4 method for signature 'GroupSequentialDesign,numeric'
n2(d, x1, round = TRUE, ...)

Arguments

Value

sample size value of design d at point x1

See Also

TwoStageDesign, see c2 for accessing the critical values

Examples

design <- TwoStageDesign(
   n1    = 25,
   c1f   = 0,
   c1e   = 2.5,
   n2    = 50,
   c2    = 1.96,
   order = 7L
)

n1(design) # 25
design@n1 # 25

n(design, x1 = 2.2) # 75

Description

N1 is a class that computes the n1 value of a design. This can be used as a score in minimize.

Usage

N1(label = NA_character_)

## S4 method for signature 'N1,TwoStageDesign'
evaluate(s, design, optimization = FALSE, ...)

Arguments

Value

an object of class N1

See Also

See AverageN2 for a regularization of the second-stage sample size.

Examples

n1_score <- N1()

evaluate(
   N1(),
   TwoStageDesign(70, 0, 2, rep(60, 6), rep(1.7, 6))
) # 70

Description

Implements the F-distribution used for an ANOVA or for the comparison of the fit of two nested regression models. In both cases, the test statistic follows a F-distribution. NestedModel is used to compare the fit of two regression models, where one model contains the independent variables of the smaller model as a subset. Then, one can use ANOVA to determine whether more variance can be explained by adding more independent variables. In the class ANOVA, the number of independent variables of the smaller model is set to $1$ in order to match the degrees of freedom and we obtain a one-way ANOVA.

Usage

NestedModels(p_inner, p_outer)

## S4 method for signature 'NestedModels'
quantile(x, probs, n, theta, ...)

## S4 method for signature 'NestedModels,numeric'
simulate(object, nsim, n, theta, seed = NULL, ...)

Arguments

Slots

p_inner

number of parameters in smaller model

p_outer

number of parameters in bigger model

See Also

See probability_density_function and cumulative_distribution_function to evaluate the pdf and the cdf, respectively. Use ANOVA for detailed information of ANOVA.

Examples

model <- NestedModels(2, 4)

Description

Implements a normal data distribution for z-values given an observed z-value and stage size. Standard deviation is 1 and mean θ √n where θ is the standardized effect size. The option two_armed can be set to decide whether a one-arm or a two-arm design should be computed.

Usage

Normal(two_armed = TRUE)

## S4 method for signature 'Normal'
quantile(x, probs, n, theta, ...)

## S4 method for signature 'Normal,numeric'
simulate(object, nsim, n, theta, seed = NULL, ...)

Arguments

Details

See DataDistribution-class for more details.

See Also

see probability_density_function and cumulative_distribution_function to evaluate the pdf and the cdf, respectively.

Examples

datadist <- Normal(two_armed = TRUE)

Description

OneStageDesign implements a one-stage design as special case of a two-stage design, i.e. as sub-class of TwoStageDesign. This is possible by defining n₂ = 0, c = c₁^f = c₁^e, c₂(x₁) = ifelse(x₁< c, Inf, -Inf). No integration pivots etc are required (set to NaN).

Usage

OneStageDesign(n, ...)

## S4 method for signature 'numeric'
OneStageDesign(n, c, event_rate)

## S4 method for signature 'OneStageDesign'
TwoStageDesign(n1, event_rate, order = 5L, eps = 0.01, ...)

## S4 method for signature 'OneStageDesignSurvival'
TwoStageDesign(n1, order = 5L, eps = 0.01, ...)

## S4 method for signature 'OneStageDesign'
plot(x, y, ...)

Arguments

Details

Note that the default plot,TwoStageDesign-method method is not supported for OneStageDesign objects.

See Also

TwoStageDesign, GroupSequentialDesign-class

Examples

design <- OneStageDesign(30, 1.96)
summary(design)
design_twostage <- TwoStageDesign(design)
summary(design_twostage)
design_survival <- OneStageDesign(30, 1.96, 0.7)

TwoStageDesign(design_survival)

Description

OneStageDesignSurvival is a subclass of both OneStageDesign and TwoStageDesignSurvival.

See Also

TwoStageDesignSurvival-class and OneStageDesign-class for superclasses and inherited methods.

Description

When we test for homogeneity of rates in a k-armed trial with binary endpoints, the test statistic is chi-squared distributed with $k-1$ degrees of freedom under the null. Under the alternative, the statistic is chi-squared distributed with a non-centrality parameter $\lambda$. The function get_tau_Pearson2xk then computes $\tau$, such that $\lambda$ is given as $n \cdot \tau$, where $n$ is the number of subjects per group. In adoptr, $\tau$ is used in the same way as $\theta$ in the case of the normally distributed test statistic.

Usage

Pearson2xK(n_groups)

get_tau_Pearson2xK(p_vector)

Arguments

Examples

pearson <- Pearson2xK(3)


H1 <- PointMassPrior(get_tau_Pearson2xK(c(.3, .25, .4)), 1)

Description

This method allows to plot the stage-two sample size and decision boundary functions of a chosen design.

Usage

## S4 method for signature 'TwoStageDesign'
plot(x, y = NULL, ..., rounded = TRUE, k = 100)

Arguments

Details

TwoStageDesign and user-defined elements of the class ConditionalScore.

Value

a plot of the two-stage design

See Also

TwoStageDesign

Examples

design <- TwoStageDesign(50, 0, 2, 50, 2, 5)
cp     <- ConditionalPower(dist = Normal(), prior = PointMassPrior(.4, 1))
plot(design, "Conditional Power" = cp, cex.axis = 2)

Description

PointMassPrior is a sub-class of Prior representing a univariate prior over a discrete set of points with positive probability mass.

Usage

PointMassPrior(theta, mass, label = NA_character_)

Arguments

Value

an object of class PointMassPrior, theta is automatically sorted in ascending order

Slots

theta

cf. parameter 'theta'

mass

cf. parameter 'mass'

See Also

To represent continuous prior distributions use ContinuousPrior.

Examples

PointMassPrior(c(0, .5), c(.3, .7))

Description

Return posterior distribution given observing stage-one outcome.

Usage

posterior(dist, prior, x1, n1, ...)

## S4 method for signature 'DataDistribution,ContinuousPrior,numeric'
posterior(dist, prior, x1, n1, ...)

## S4 method for signature 'DataDistribution,PointMassPrior,numeric'
posterior(dist, prior, x1, n1, ...)

Arguments

Value

Object of class Prior

Examples

tmp <- ContinuousPrior(function(x) dunif(x, .2, .4), c(.2, .4))
posterior(Normal(), tmp, 2, 20)

posterior(Normal(), PointMassPrior(0, 1), 2, 20)

Description

predictive_cdf() evaluates the predictive CDF of the model specified by a DataDistribution dist and Prior at the given stage-one outcome.

Usage

predictive_cdf(dist, prior, x1, n1, ...)

## S4 method for signature 'DataDistribution,ContinuousPrior,numeric'
predictive_cdf(
  dist,
  prior,
  x1,
  n1,
  k = 10 * (prior@support[2] - prior@support[1]) + 1,
  ...
)

## S4 method for signature 'DataDistribution,PointMassPrior,numeric'
predictive_cdf(dist, prior, x1, n1, ...)

Arguments

Value

numeric, value of the predictive CDF

Examples

tmp <- ContinuousPrior(function(x) dunif(x, .2, .4), c(.2, .4))
predictive_cdf(Normal(), tmp, 2, 20)

predictive_cdf(Normal(), PointMassPrior(.0, 1), 0, 20) # .5

Description

predictive_pdf() evaluates the predictive PDF of the model specified by a DataDistribution dist and Prior at the given stage-one outcome.

Usage

predictive_pdf(dist, prior, x1, n1, ...)

## S4 method for signature 'DataDistribution,ContinuousPrior,numeric'
predictive_pdf(
  dist,
  prior,
  x1,
  n1,
  k = 10 * (prior@support[2] - prior@support[1]) + 1,
  ...
)

## S4 method for signature 'DataDistribution,PointMassPrior,numeric'
predictive_pdf(dist, prior, x1, n1, ...)

Arguments

Value

numeric, value of the predictive PDF

Examples

tmp <- ContinuousPrior(function(x) dunif(x, .2, .4), c(.2, .4))
predictive_pdf(Normal(), tmp, 2, 20)

predictive_pdf(Normal(), PointMassPrior(.3, 1), 1.5, 20) # ~.343

Description

Printing an optimization result

Usage

print(x, ...)

Arguments

Description

A Prior object represents a prior distribution on the single model parameter of a DataDistribution class object. Together a prior and data-distribution specify the class of the joint distribution of the test statisic, X, and its parameter, theta. Currently, adoptr only allows simple models with a single parameter. Implementations for PointMassPrior and ContinuousPrior are available.

Details

For an example on working with priors, see here.

See Also

For the available methods, see bounds, expectation, condition, predictive_pdf, predictive_cdf, posterior

Examples

disc_prior <- PointMassPrior(c(0.1, 0.25), c(0.4, 0.6))

cont_prior <- ContinuousPrior(
  pdf     = function(x) dnorm(x, mean = 0.3, sd = 0.2),
  support = c(-2, 3)
)

Description

probability_density_function evaluates the probability density function of a specific distribution dist at a point x.

Usage

probability_density_function(dist, x, n, theta, ...)

## S4 method for signature 'Binomial,numeric,numeric,numeric'
probability_density_function(dist, x, n, theta, ...)

## S4 method for signature 'ChiSquared,numeric,numeric,numeric'
probability_density_function(dist, x, n, theta, ...)

## S4 method for signature 'NestedModels,numeric,numeric,numeric'
probability_density_function(dist, x, n, theta, ...)

## S4 method for signature 'Normal,numeric,numeric,numeric'
probability_density_function(dist, x, n, theta, ...)

## S4 method for signature 'Student,numeric,numeric,numeric'
probability_density_function(dist, x, n, theta, ...)

## S4 method for signature 'Survival,numeric,numeric,numeric'
probability_density_function(dist, x, n, theta, ...)

Arguments

Details

If the distribution is Binomial, theta denotes the rate difference between intervention and control group. Then, the mean is assumed to be √ n theta.

If the distribution is Normal, then the mean is assumed to be √ n theta.

Value

value of the probability density function at point x.

Examples

probability_density_function(Binomial(.2, FALSE), 1, 50, .3)

probability_density_function(Pearson2xK(3), 1, 30, get_tau_Pearson2xK(c(0.3, 0.4, 0.7, 0.2)))
probability_density_function(ZSquared(TRUE), 1, 35, get_tau_ZSquared(0.4, 1))


probability_density_function(ANOVA(3), 1, 30, get_tau_ANOVA(c(0.3, 0.4, 0.7, 0.2)))

probability_density_function(Normal(), 1, 50, .3)

probability_density_function(Student(TRUE), 1, 40, 1.1)

probability_density_function(Survival(0.6,TRUE),0.75,50,0.9)

Description

In adoptr scores are used to assess the performance of a design. This can be done either conditionally on the observed stage-one outcome or unconditionally. Consequently, score objects are either of class ConditionalScore or UnconditionalScore.

Usage

expected(s, data_distribution, prior, ...)

## S4 method for signature 'ConditionalScore'
expected(s, data_distribution, prior, label = NA_character_, ...)

evaluate(s, design, ...)

## S4 method for signature 'IntegralScore,TwoStageDesign'
evaluate(s, design, optimization = FALSE, subdivisions = 10000L, ...)

Arguments

Details

All scores can be evaluated on a design using the evaluate method. Note that evaluate requires a third argument x1 for conditional scores (observed stage-one outcome). Any ConditionalScore can be converted to a UnconditionalScore by forming its expected value using expected. The returned unconditional score is of class IntegralScore.

Value

No return value. Generic description of class Score.

See Also

ConditionalPower, ConditionalSampleSize, composite

Examples

design <- TwoStageDesign(
  n1    = 25,
  c1f   = 0,
  c1e   = 2.5,
  n2    = 50,
  c2    = 1.96,
  order = 7L
)
prior <- PointMassPrior(.3, 1)

# conditional
cp <- ConditionalPower(Normal(), prior)
expected(cp, Normal(), prior)
evaluate(cp, design, x1 = .5)

# unconditional
power <- Power(Normal(), prior)
evaluate(power, design)
evaluate(power, design, optimization = TRUE) # use non-adaptive quadrature

Description

simulate allows to draw samples from a given TwoStageDesign.

Usage

## S4 method for signature 'TwoStageDesign,numeric'
simulate(object, nsim, dist, theta, seed = NULL, ...)

Arguments

Value

simulate() returns a data.frame with nsim rows and for each row (each simulation run) the following columns

• theta: The effect size

• n1: First-stage sample size

• c1f: Stopping for futility boundary

• c1e: Stopping for efficacy boundary

• x1: First-stage outcome

• n2: Resulting second-stage sample size after observing x1

• c2: Resulting second-stage decision-boundary after observing x1

• x2: Second-stage outcome

• reject: Decision whether the null hypothesis is rejected or not

See Also

TwoStageDesign

Examples

design <- TwoStageDesign(25, 0, 2, 25, 2, order = 5)
# draw samples assuming two-armed design
simulate(design, 10, Normal(), .3, 42)

Description

Implements exact t-distributions instead of a normal approximation

Usage

Student(two_armed = TRUE)

## S4 method for signature 'Student'
quantile(x, probs, n, theta, ...)

## S4 method for signature 'Student,numeric'
simulate(object, nsim, n, theta, seed = NULL, ...)

Arguments

See Also

see probability_density_function and cumulative_distribution_function to evaluate the pdf and the cdf, respectively.

Examples

datadist <- Student(two_armed = TRUE)

Description

subject_to(...) can be used to generate an object of class ConstraintsCollection from an arbitrary number of (un)conditional constraints.

Usage

subject_to(...)

## S4 method for signature 'ConstraintsCollection,TwoStageDesign'
evaluate(s, design, optimization = FALSE, ...)

Arguments

Value

an object of class ConstraintsCollection

See Also

subject_to is intended to be used for constraint specification the constraints in minimize.

Examples

# define type one error rate and power
toer  <- Power(Normal(), PointMassPrior(0.0, 1))
power <- Power(Normal(), PointMassPrior(0.4, 1))

# create constrain collection
subject_to(
  toer  <= 0.025,
  power >= 0.9
)

Description

Implements the normal approximation of the log-rank test statistic.

Usage

Survival(event_rate, two_armed = TRUE)

## S4 method for signature 'Survival'
quantile(x, probs, n, theta, ...)

## S4 method for signature 'Survival,numeric'
simulate(object, nsim, n, theta, seed = NULL, ...)

Arguments

Slots

event_rate

cf. parameter 'event_rate'

See Also

see probability_density_function and cumulative_distribution_function to evaluate the pdf and the cdf, respectively.

Examples

datadist <- Survival(event_rate=0.6, two_armed=TRUE)

Description

SurvivalDesign is a function that converts an arbitrary design to a survival design.

Usage

SurvivalDesign(design, event_rate)

## S4 method for signature 'TwoStageDesign'
SurvivalDesign(design, event_rate)

## S4 method for signature 'TwoStageDesign'
TwoStageDesign(n1, event_rate)

## S4 method for signature 'OneStageDesign'
OneStageDesign(n, event_rate)

## S4 method for signature 'OneStageDesign'
SurvivalDesign(design, event_rate)

## S4 method for signature 'GroupSequentialDesign'
GroupSequentialDesign(n1, event_rate)

## S4 method for signature 'GroupSequentialDesign'
SurvivalDesign(design, event_rate)

Arguments

Value

Converts any type of design to a survival design

Examples

design <- get_initial_design(0.4, 0.025, 0.1)
SurvivalDesign(design, 0.8)

design_os <- get_initial_design(0.4, 0.025, 0.1, type_design = "one-stage")
design_gs <- get_initial_design(0.4, 0.025, 0.1, type_design = "group-sequential")

OneStageDesign(design_os, 0.7)

GroupSequentialDesign(design_gs, 0.8)

Description

Get tunable parameters of a design as numeric vector via tunable_parameters or update a design object with a suitable vector of values for its tunable parameters.

Usage

tunable_parameters(object, ...)

## S4 method for signature 'TwoStageDesign'
tunable_parameters(object, ...)

## S4 method for signature 'TwoStageDesign'
update(object, params, ...)

## S4 method for signature 'OneStageDesign'
update(object, params, ...)

Arguments

Details

The tunable slot of a TwoStageDesign stores information about the set of design parameters which are considered fixed (not changed during optimization) or tunable (changed during optimization). For details on how to fix certain parameters or how to make them tunable again, see make_fixed and make_tunable.

Value

tunable_parameters returns the numerical values of all tunable parameters as a vector. update returns the updated design.

See Also

TwoStageDesign

Examples

design  <- TwoStageDesign(25, 0, 2, 25, 2, order = 5)
tunable_parameters(design)
design2 <- update(design, tunable_parameters(design) + 1)
tunable_parameters(design2)

Description

TwoStageDesign is the fundamental design class of the adoptr package. Formally, we represent a generic two-stage design as a five-tuple (n₁, c₁^f, c₁^e, n₂(·), c₂(·)). Here, n₁ is the first-stage sample size (per group), c₁^f and c₁^e are boundaries for early stopping for futility and efficacy, respectively. Since the trial design is a two-stage design, the elements n₂(·) (stage-two sample size) and c₂(·) (stage-two critical value) are functions of the first-stage outcome X₁=x₁. X₁ denotes the first-stage test statistic. A brief description on this definition of two-stage designs can be read here. For available methods, see the 'See Also' section at the end of this page.

Usage

TwoStageDesign(n1, ...)

## S4 method for signature 'numeric'
TwoStageDesign(
  n1,
  c1f,
  c1e,
  n2_pivots,
  c2_pivots,
  order = NULL,
  event_rate,
  ...
)

## S4 method for signature 'TwoStageDesign'
summary(object, ..., rounded = TRUE)

Arguments

Details

summary can be used to quickly compute and display basic facts about a TwoStageDesign. An arbitrary number of names UnconditionalScore objects can be provided via the optional arguments ... and are included in the summary displayed using print.

Slots

n1

cf. parameter 'n1'

c1f

cf. parameter 'c1f'

c1e

cf. parameter 'c1e'

n2_pivots

vector of length 'order' giving the values of n2 at the pivot points of the numeric integration rule

c2_pivots

vector of length order giving the values of c2 at the pivot points of the numeric integration rule

x1_norm_pivots

normalized pivots for integration rule (in [-1, 1]) the actual pivots are scaled to the interval [c1f, c1e] and can be obtained by the internal method
adoptr:::scaled_integration_pivots(design)

weights

weights of of integration rule at x1_norm_pivots for approximating integrals over x1

tunable

named logical vector indicating whether corresponding slot is considered a tunable parameter (i.e. whether it can be changed during optimization via minimize or not; cf.
make_fixed)

See Also

For accessing sample sizes and critical values safely, see methods in n and c2; for modifying behaviour during optimizaton see make_tunable; to convert between S4 class represenation and numeric vector, see tunable_parameters; for simulating from a given design, see simulate; for plotting see plot,TwoStageDesign-method. Both group-sequential and one-stage designs (!) are implemented as subclasses of TwoStageDesign.

Examples

design <- TwoStageDesign(50, 0, 2, 50.0, 2.0, 5)
pow    <- Power(Normal(), PointMassPrior(.4, 1))
summary(design, "Power" = pow)

Description

When conducting a study with time-to-event endpoints, the main interest is not the sample size, but the number of overall necessary events. Thus, adoptr does not use the sample size for calculating the design. Instead, it uses the number of events directly. In the framework of adoptr, all the calculations are done group-wise, where both of the groups are equal-sized. This means, that the number of events adoptr has computed is only half of the overall number of necessary events. In order to facilitate this issue, the look of the summary and show functions have been changed in the survival analysis setting. The sample size is implicitly determined by dividing the number of events by the event rate. Survival objects are only created, when the argument event_rate is not missing.

Slots

event_rate

probability that a subject in either group will eventually have an event

See Also

TwoStageDesign for superclass and inherited methods

Description

Implementation of $Z^2$, where $Z$ is normally distributed with mean $\mu$ and variance $\sigma^2$. $Z^2$ is chi-squared distributed with $1$ degree of freedom and non-centrality parameter $(\mu/\sigma)^2$. The function get_tau_ZSquared computes the factor $\tau=(\mu/\sigma)^2$, such that $\tau$ is the equivalent of $\theta$ in the normally distributed case. The square of a normal distribution $Z^2$ can be used for two-sided hypothesis testing.

Usage

ZSquared(two_armed = TRUE)

get_tau_ZSquared(mu, sigma)

Arguments

Examples

zsquared <- ZSquared(FALSE)


H1 <- PointMassPrior(get_tau_ZSquared(0.4, 1), 1)