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

Source: `R/build_gs_norm.R`
`build_gs_norm.Rd`

`build_gs_norm()` builds a multi-stage group-sequential multi-arm clinical trial design object assuming the primary outcome variable is normally distributed, like those returned by `des_gs_norm`.

    build_gs_norm(
      n1 = 162,
      n10 = 54,
      e = c(2.42, 2.42),
      f = c(-2.42, 2.42),
      K = 2,
      alpha = 0.025,
      beta = 0.1,
      delta1 = 0.5,
      delta0 = 0,
      sigma = 1,
      ratio = 1,
      power = "marginal",
      stopping = "simultaneous",
      type = "variable",
      summary = FALSE
    )

## Arguments

n1 | A `numeric` indicating the chosen value for n1, the total sample size required in stage one of the trial. Defaults to `162`.
n10 | A `numeric` indicating the chosen value for n10, the sample size required in the control arm in stage one of the trial. Defaults to `54`.
e | A `numeric` `vector` indicating the chosen value for e, the efficacy (upper) stopping boundaries. Defaults to `c(2.42, 2.42)`.
f | A `numeric` `vector` indicating the chosen value for f, the futility (lower) stopping boundaries. Defaults to `c(-2.42, 2.42)`.
K | A `numeric` indicating the chosen value for K, the (initial) number of experimental treatment arms. 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"`.
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` 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.

- Each of the input variables.

## See also

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

## Examples

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