# Design a two-stage two-arm randomised clinical trial assuming a Bernoulli distributed primary outcome variable

Source: `R/des_two_stage.R`
`des_two_stage.Rd`

`des_two_stage` determines two-stage two-arm randomised clinical trial designs, assuming the primary outcome variable is Bernoulli distributed. It supports a flexible framework for specifying which scenarios to control the type-I and type-II error-rates for, and allows for design determination assuming a variety of test statistics. In all instances, `des_two_stage` computes the optimal required sample size in each arm in each stage, the associated optimal stopping boundaries, and returns information on key operating characteristics.

    des_two_stage(
      type = "binomial",
      alpha = 0.1,
      beta = 0.2,
      delta = 0.2,
      ratio = 1,
      Pi0 = 0.1,
      Pi1 = Pi0[1],
      nCmax = 50L,
      equal = T,
      w = c(1, 0, 0, 0, 0),
      piO = Pi0[1],
      efficacy = FALSE,
      futility = TRUE,
      efficacy_type = 0L,
      efficacy_param = NULL,
      futility_type = 1L,
      futility_param = 0L,
      summary = FALSE
    )

## Arguments

type | A `character` string indicating the chosen design framework/test statistic to assume. Must be one of `"barnard"`, `"binomial"`, `"fisher"`, or `"sat"`. Defaults to `"binomial"`.
alpha | A `numeric` indicating the chosen value for α, the significance level (i.e., the type-I error-rate). Defaults to `0.1`.
beta | A `numeric` indicating the chosen value for β, used in the definition of the desired power (i.e., the type-II error-rate). Defaults to `0.2`.
delta | A `numeric` indicating the chosen value for δ, the treatment effect assumed in the power calculation. Defaults to `0.2`.
ratio | A `numeric` indicating the chosen value for r, the allocation ratio to the experimental arm, relative to the control arm. Defaults to `1`.
Pi0 | A `numeric` `vector` indicating the chosen values of the control arm response rate to control the type-I error-rate to level α for. Must either be of `length` one, indicating a single point, or of `length` two. In this case, the elements indicate the range of possible response rates to allow for. Defaults to `0.1`.
Pi1 | A `numeric` `vector` indicating the chosen values of the control arm response rate to allow for in the power calculations. Must either be of `length` one, indicating a single point, or of `length` two. In this case, the elements indicate the range of possible response rates to allow for. Defaults to `Pi0[1]`.
nCmax | A `numeric` indicating the maximum value of the sample size in the control arm (across both stages) to consider in the search procedure. Defaults to `50L`.
equal | A `logical` variable indicating whether the sample size of the two stages should be equal. Defaults to `TRUE`.
w | A `numeric` `vector` indicating the weights to use in the optimality criteria. Must be of `length` five, with all elements greater than or equal to zero, and at least one of the first four elements strictly positive. Defaults to `c(1, 0, 0, 0, 0)`.
piO | A `numeric` indicating the value of the control arm response rate to assume in the optimality criteria. Defaults to `Pi0[1]`.
efficacy | Only used if `type` is one of `"barnard"`, `"binomial"`, or `"sat"`. Then, it is a `logical` variable indicating whether to include early stopping for efficacy in the design. Defaults to `FALSE`.
futility | Only used if `type` is one of `"barnard"`, `"binomial"`, or `"sat"`. Then, it is a `logical` variable indicating whether to include early stopping for futility in the design. Defaults to `TRUE`.
efficacy_type | Only used if `type` is `"fisher"`. Then, it is a `numeric` indicating whether, and which type of, early stopping for efficacy to include in the design. See the vignette for details. Defaults to `0L`.
efficacy_param | Only used if `type` is `"fisher"` and `efficacy_type` is not equal to `0L`. Then, it is a `numeric` that influences the precise way in which an efficacy boundary is specified. See the vignette for details. Defaults to `NULL`.
futility_type | Only used if `type` is `"fisher"`. Then, it is a `numeric` indicating whether, and which type of, early stopping for futility to include in the design. See the vignette for details. Defaults to `1L`.
futility_param | Only used if `type` is `"fisher"` and `futility_type` is not equal to `0L`. Then, it is a `numeric` that influences the precise way in which a futility boundary is specified. See the vignette for details. Defaults to `1L`.
summary | A `logical` variable indicating whether a summary of the function's progress should be printed to the console. Defaults to `FALSE`.

## Value

A `list` with additional class `"ph2rand_des"`, containing each of the input parameters along with several additional variables, including

- A `list` in the slot `$boundaries` giving the rejection boundaries of the optimal design. The names of these elements depends on the value of `type`.

- A `tibble` in the slot `$feasible` summarising the operating characteristics of the feasible designs.

- A `numeric` `vector` in the slot `$nC` giving the sample sizes in the control arm in each stage for the optimal design.

- A `numeric` `vector` in the slot `$nE` giving the sample sizes in the experimental arm in each stage for the optimal design.

- A `tibble` in the slot `$opchar` summarising the operating characteristics of the optimal design.

## See also

`des_one_stage`, `opchar`, `pmf`, `terminal`, `plot.ph2rand_des`, `summary.ph2rand_des`.

## Examples

    # The design for the default parameters
    des       <- des_two_stage()
    # Controlling the type-I/II error-rates over a range of possible response
    # rates
    des_range <- des_two_stage(Pi0 = c(0, 1),
                               Pi1 = c(0, 0.8))