# Design a single-stage multi-arm clinical trial for a Poisson distributed primary outcome

Source: `R/des_ss_pois.R`
`des_ss_pois.Rd`

`des_ss_pois()` determines single-stage multi-arm clinical trial designs assuming the primary outcome variable is Poisson distributed. It supports a variety of multiple comparison corrections, along with the determination of A-, D-, and E-optimal allocation ratios. In all instances, `des_ss_pois()` computes the required sample size in each arm, and returns information on key operating characteristics.

    des_ss_pois(
      K = 2,
      alpha = 0.025,
      beta = 0.1,
      lambda0 = 5,
      delta1 = 1,
      delta0 = 0,
      ratio = rep(1, K),
      correction = "dunnett",
      power = "marginal",
      integer = FALSE,
      ratio_scenario = "HG",
      summary = FALSE
    )

## Arguments

K | A `numeric` indicating the chosen value for K, the number of experimental treatment arms. Defaults to `2`.
alpha | A `numeric` indicating the chosen value for α, the significance level. Defaults to `0.025`.
beta | A `numeric` indicating the chosen value for β, used in the definition of the desired power. Defaults to `0.1`.
lambda0 | A `numeric` indicating the chosen value for λ0, the event rate in the control arm. Defaults to `5`.
delta1 | A `numeric` indicating the chosen value for δ1, the 'interesting' treatment effect. Defaults to `1`.
delta0 | A `numeric` indicating the chosen value for δ0, the 'uninteresting' treatment effect. Defaults to `0`.
ratio | Either a `numeric` vector or a `character` string indicating the chosen value for r, the vector of allocation ratios to the experimental arms. Can be specified explicitly as a `numeric` vector, or can be specified as `"A"`, `"D"`, or `"E"` to instruct `des_ss_pois()` to compute the A-, D-, or E-optimal value for r. Defaults to `rep(1, K)`.
correction | A `character` string indicating the chosen multiple comparison correction. Can be any of `"benjamini_hochberg"`, `"benjamini_yekutieli"`, `"bonferroni"`, `"dunnett"`, `"hochberg"`, `"holm_bonferroni"`, `"holm_sidak"`, `"none"`, `"sidak"`, and `"step_down_dunnett"`. Defaults to `"dunnett"`.
power | A `character` string indicating the chosen type of power to design the trial for. Can be one of `"conjunctive"`, `"disjunctive"`, and `"marginal"`. Defaults to `"marginal"`.
integer | A `logical` variable indicating whether the computed values in n, the vector of sample sizes required in each arm, should be forced to be whole numbers. Defaults to `FALSE`.
ratio_scenario | Only used if `ratio` is a `character` string. A `character` string indicating the chosen event rate scenario for which to optimise the allocation ratios. Can be one of `"HG"` and `"HA"`. Defaults to `"HG"`.
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` of class `"multiarm_des_ss_pois"` containing the following elements

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

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

- A `numeric` vector in the slot `$n` specifying n, the vector of sample sizes required in each arm.

- A `numeric` in the slot `$gamma` specifying the critical threshold for p-values, γ, below which null hypotheses would be rejected. Will be `NA` if `correction` is not a single-step testing procedure.

- A `numeric` vector in the slot `$gammaO` specifying the critical thresholds for ordered p-values, γ, to use with the chosen step-wise testing procedure. Will be `NA` if `correction` is not a step-wise testing procedure.

- Each of the input variables.

## See also

`build_ss_pois`, `gui`, `opchar_ss_pois`, `plot.multiarm_des_ss_pois`, `sim_ss_pois`.

## Examples

    # The design for the default parameters
    des        <- des_ss_pois()
    # An A-optimal design
    des_A      <- des_ss_pois(ratio = "A")
    # Using the root-K allocation rule, modifying the desired type of power, and
    # choosing an alternative multiple comparison correction
    des_root_K <- des_ss_pois(ratio      = rep(1/sqrt(2), 2),
                              correction = "holm_bonferroni",
                              power      = "disjunctive")