# Design a multi-stage group-sequential multi-arm clinical trial for a normally distributed primary outcome

Source: `R/des_gs_norm.R`
`des_gs_norm.Rd`

`des_gs_norm()` determines multi-stage group-sequential multi-arm clinical trial designs assuming the primary outcome variable is normally distributed. It computes required design components and returns information on key operating characteristics.

    des_gs_norm(
      K = 2,
      J = 2,
      alpha = 0.025,
      beta = 0.1,
      delta1 = 0.5,
      delta0 = 0,
      sigma = 1,
      ratio = 1,
      power = "marginal",
      stopping = "simultaneous",
      type = "variable",
      fshape = "pocock",
      eshape = "pocock",
      ffix = -3,
      efix = 3,
      integer = FALSE,
      summary = FALSE
    )

## Arguments

K | A `numeric` indicating the chosen value for K, the (initial) number of experimental treatment arms. Defaults to `2`.
J | A `numeric` indicating the chosen value for J, the (maximum) number of allowed stages. Defaults to `2`.
alpha | A `numeric` indicating the chosen value for α, the significance level (family-wise error-rate). Defaults to `0.025`.
beta | A `numeric` indicating the chosen value for β, used in the definition of the desired power. Defaults to `0.1`.
delta1 | A `numeric` indicating the chosen value for δ1, the 'interesting' treatment effect. Defaults to `0.5`.
delta0 | A `numeric` indicating the chosen value for δ0, the 'uninteresting' treatment effect. Defaults to `0`.
sigma | A `numeric` `vector` indicating the chosen values for σ0 and σ1, the standard deviations of the responses in the control and experimental arms. Must be of `length` 1 or 2. If of `length` 1, it is assumed that σ0 =σ1. Defaults to `1`.
ratio | A `numeric` indicating the chosen value for r, the stage-wise allocation ratio to present experimental arms. Defaults to `1`.
power | A `character` string indicating the chosen type of power to design the trial for. Can be `"disjunctive"` or `"marginal"`. Defaults to `"marginal"`.
stopping | A `character` string indicating the chosen type of stopping rule. Can be `"separate"` or `"simultaneous"`. Defaults to `"simultaneous"`.
type | A `character` string indicating the choice for the stage-wise sample size. Can be `"variable"` or `"fixed"`. Defaults to `"variable"`.
fshape | A `character` string indicating the choice for the futility (lower) stopping boundaries. Can be any of `"fixed"`, `"obf"`, `"pocock"`, and `"triangular"`. Defaults to `"pocock"`.
eshape | A `character` string indicating the choice for the efficacy (upper) stopping boundaries. Can be any of `"fixed"`, `"obf"`, `"pocock"`, and `"triangular"`. Defaults to `"pocock"`.
ffix | A `numeric` indicating the chosen value for the fixed interim futility bounds. Only used when `fshape = "fixed"`. Defaults to `"-3"`.
efix | A `numeric` indicating the chosen value for the fixed interim efficacy bounds. Only used when `eshape = "fixed"`. Defaults to `"3"`.
integer | A `logical` variable indicating whether the computed possible sample sizes required in each arm in each stage should be forced to be whole numbers. Defaults to `FALSE`. WARNING: If you set `integer = TRUE` and `ratio != 1`, obscure results can occur due to difficulties in identifying a suitable whole number sample size that meets the allocation ratio requirement.
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 `"multiarm_des_gs_norm"`, containing the following elements:

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

- A `tibble` in the slot `$pmf_N` summarising the probability mass function of the random required sample size under key scenarios.

- A `numeric` `vector` in the slot `$e` specifying e, the trial's efficacy (upper) stopping boundaries.

- A `numeric` `vector` in the slot `$f` specifying f, the trial's futility (lower) stopping boundaries.

- A `numeric` in the slot `$maxN` specifying max N, the trial's maximum required sample size.

- A `numeric` in the slot `$n_factor`, for internal use in other functions.

- A `numeric` in the slot `$n1` specifying n1, the total sample size required in stage one of the trial.

- A `numeric` in the slot `$n10` specifying n10, the sample size required in the control arm in stage one of the trial.

- Each of the input variables.

## See also

`build_gs_norm`, `gui`, `opchar_gs_norm`, `plot.multiarm_des_gs_norm`, `sim_gs_norm`.

## Examples

    # The design for the default parameters
    des <- des_gs_norm()