Package 'artcatr'

Sample size / power for a randomized trial with an ordered categorical outcome, analysed by the proportional-odds model

Description

Implements the methods of White et al (2023), including their new ologit method (which allows a non-proportional-odds anticipated effect via pe, is more accurate for large effects, and supports non-inferiority / substantial-superiority trials via margin), and Whitehead's (1993) original method for comparison.

Usage

artcatr(
  pc,
  cumulative = FALSE,
  pe = NULL,
  or = NULL,
  rr = NULL,
  margin = 1,
  favourable = NULL,
  power = NULL,
  n = NULL,
  aratio = c(1, 1),
  alpha = 0.05,
  onesided = FALSE,
  method = c("ologit", "whitehead"),
  variance = c("NA", "NN", "AA"),
  quiet = FALSE
)

Arguments

pc	Numeric vector. Anticipated probabilities (or cumulative probabilities, if cumulative = TRUE) in the control arm, one per outcome level, including the right-most level (probabilities must sum to 1, or cumulative probabilities must reach 1).
cumulative	Logical. Are pc/pe cumulative probabilities?
pe	Numeric vector. Anticipated (cumulative) probabilities in the experimental arm, specified like pc. Exactly one of pe, or, rr must be given (or none, if margin != 1, in which case or = 1 is assumed).
or	Numeric scalar. Anticipated common odds ratio applied to the control-arm cumulative probabilities (assumes proportional odds). An odds ratio below 1 shifts probability towards the right-most level.
rr	Numeric scalar. Anticipated common risk ratio (applied to every level except the right-most).
margin	Numeric scalar odds ratio defining the null hypothesis. margin = 1 (default) gives a superiority trial; otherwise a non-inferiority or substantial-superiority trial (see favourable).
favourable	Logical or NULL. Is the left-most outcome level the most favourable outcome? If NULL (default), inferred from the anticipated average odds ratio vs margin.
power	Numeric scalar in (0, 1). Power to achieve; sample size is calculated. Default 0.8 if neither power nor n given.
n	Numeric scalar. Total sample size; power is calculated.
aratio	Length-2 numeric vector, allocation ratio control:experimental (e.g. c(1, 2) means 2 experimental participants per 1 control).
alpha	Numeric scalar significance level. Default 0.05.
onesided	Logical. Is alpha one-sided? Default FALSE (two-sided).
method	One of "ologit" (default, the new method) or "whitehead".
variance	For method = "ologit", one of "NA" (default, recommended by White et al 2023), "NN" (equivalent to Whitehead's method), or "AA". "NA" uses the null-hypothesis SE for the alpha term and the alternative-hypothesis SE for the beta (power) term; "NN"/"AA" use one SE for both.
quiet	Logical. Suppress the printed summary?

Value

A list with the computed sample size or power, per-group sample sizes, the anticipated probability table, and other design parameters (mirroring the Stata command's stored results).

References

White IR, Marley-Zagar E, Morris TP, Parmar MKB, Royston P, Babiker AG (2023). artcat: Sample-size calculation for an ordered categorical outcome. Stata Journal 23(1):3-23. https://doi.org/10.1177/1536867X231161934

Whitehead J (1993). Sample size calculations for ordered categorical data. Statistics in Medicine 12:2257-2271.

Examples

# FLU-IVIG trial (Davey et al 2019), reproducing White et al (2023) sec 4:
# default (new) ologit method
artcatr(pc = c(.018, .036, .156, .141, .39, .259), or = 1 / 1.77, power = .8,
       favourable = FALSE)

# Whitehead method, for comparison
artcatr(pc = c(.018, .036, .156, .141, .39, .259), or = 1 / 1.77, power = .8,
       favourable = FALSE, method = "whitehead")

# Non-inferiority trial (margin expressed as an odds ratio)
artcatr(pc = c(.010, .021, .099, .103, .384, .383), or = 1, margin = 1.33,
       power = .8, favourable = FALSE)

---

Print an artcatr object

Description

Print an artcatr object

Usage

## S3 method for class 'artcatr'
print(x, digits = 3, probtable = TRUE, ...)

Arguments

x	An object returned by artcatr().
digits	Number of significant digits to round probabilities to.
probtable	Logical; include the table of anticipated probabilities?
...	Not used.

Value

x, invisibly.

---

Print a summary.artcatr object

Description

Print a summary.artcatr object

Usage

## S3 method for class 'summary.artcatr'
print(x, ...)

Arguments

x	An object returned by summary.artcatr().
...	Not used.

Value

x, invisibly.

---

Tidy summary table of anticipated probabilities from an artcatr object

Description

Tidy summary table of anticipated probabilities from an artcatr object

Usage

## S3 method for class 'artcatr'
summary(object, digits = 3, ...)

Arguments

object	An object returned by artcatr().
digits	Number of significant digits to round probabilities to.
...	Not used.

Value

A data frame with columns level, description (favourable/ unfavourable labels for the extreme levels), control, experimental, and (for non-inferiority/substantial-superiority designs) experimental_null.

---