Repository Mirror for your Cloud Server and Webhosting

Type:

Package

Title:

Optimal Two-Stage Designs for Ordered Categorical Outcomes

Version:

1.0.3

Date:

2026-08-26

Description:

Functions to design and simulate optimal two-stage randomized controlled trials (RCTs) with ordered categorical outcomes, supporting rank-based tests and group-sequential decision rules. Methods build on classical and modern rank tests and two-stage/Group-Sequential designs, e.g., Park (2025) <doi:10.1371/journal.pone.0318211>. The functions 'rule()', 'op()' and 'design_table()' provide a single entry point for constructing designs, evaluating their operating characteristics, and tabulating several designs at once. The earlier functions, one for each combination of test statistic and stopping rule, are retained and still return the same values, but they are deprecated: each warns and names its replacement, and they will be removed in the next version. Please see the package reference manual and the vignette for details.

License:

GPL-3

Encoding:

UTF-8

Depends:

R (≥ 4.0)

Imports:

stats

Suggests:

knitr, rmarkdown

VignetteBuilder:

knitr

RoxygenNote:

7.3.2

NeedsCompilation:

Author:

Yeonhee Park [aut, cre], Yudi Wang [aut], Zhanpeng Xu [aut]

Maintainer:

Yeonhee Park <yeonheepark@skku.edu>

Packaged:

2026-08-31 02:32:03 UTC; ypark56

Repository:

CRAN

Date/Publication:

2026-08-31 18:20:02 UTC

Optimal Two-Stage Designs for Ordered Categorical Outcomes

Description

Functions to design and simulate optimal two-stage randomized controlled trials (RCTs) with ordered categorical outcomes, supporting rank-based tests and group-sequential decision rules. Methods build on classical and modern rank tests and two-stage/Group-Sequential designs, e.g., Park (2025) <doi: 10.1371/journal.pone.0318211>. The functions 'rule()', 'op()' and 'design_table()' provide a single entry point for constructing designs, evaluating their operating characteristics, and tabulating several designs at once. The earlier functions, one for each combination of test statistic and stopping rule, are retained and still return the same values, but they are deprecated: each warns and names its replacement, and they will be removed in the next version. Please see the package reference manual and the vignette for details.

Details

There are several main functions. Decision_rule_S_1stage, Decision_rule_M_1stage, Decision_rule_W_1stage, ruleF, and ruleFS determine the decision rule for clinical trials. op.1stage, op.F, and op.FS calculate the operating characteristics for clinical trial designs, including type I error, power, and expected sample size, to investigate the performance of the designs.

Author(s)

Yeonhee Park [aut, cre], Yudi Wang [aut], Zhanpeng Xu [aut]

Maintainer: Yeonhee Park <yeonheepark@skku.edu>

References

Park, Y. (2025). Optimal two-stage group sequential designs based on Mann-Whitney-Wilcoxon test. PloS one, 20(2), e0318211.

Decision rule for the F design based on the Mann-Whitney-Wilcoxon test with specified values of alpha1 and beta1

Description

This is to determine the decision rule for a two-stage design based on the Mann-Whitney-Wilcoxon test with the specified values of alpha1 and beta1.

Usage

Decision_rule_M.F(p1, p2, alpha1, beta1, alpha, beta, lambda = 1)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

alpha1

The parameter used to define futility monitoring. Under the null hypothesis, 1 - alpha1 corresponds to the probability of stopping for futility at the interim analysis.

beta1

The probability of stopping for futility at the interim analysis when the alternative hypothesis is true.

alpha

Target type I error rate.

beta

Target type II error rate.

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

n1

The total sample size of the control and experimental groups required at the 1st analysis.

t1

The threshold of the test statistic at the 1st analysis.

n2

The cumulative total sample size of the control and experimental groups required at the 2nd analysis.

t2

The threshold of the test statistic at the 2nd analysis.

Note

This function is deprecated as of OptOTrials 1.0.3 and will be removed in version 1.1.0. It still returns exactly what it always returned, but it now warns. Use rule instead; help("OptOTrials-deprecated") tabulates every replacement.

References

Park, Y. (2025). Optimal two-stage group sequential designs based on Mann-Whitney-Wilcoxon test. PloS one, 20(2), e0318211.

Examples

alpha = 0.05; beta = 0.2; 
p1 = c(0.2, 0.5, 0.2, 0.1)
p2 = c(0.4, 0.3, 0.2, 0.1)
alpha1 <- 0.2
beta1 <- 0.1
Decision_rule_M.F(p1, p2, alpha1, beta1, alpha, beta, lambda = 1)

Decision rule for the FS design based on the Mann-Whitney-Wilcoxon test with the specified values of alpha1, alpha2, and beta1

Description

This is the function to determine the decision rule for the FS design based on the Mann-Whitney-Wilcoxon test with the specified values of alpha1, alpha2, and beta1.

Usage

Decision_rule_M.FS(p1, p2, alpha1, alpha2, beta1, alpha, beta, lambda = 1)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

alpha1

The parameter used to define futility monitoring. Under the null hypothesis, 1 - alpha1 corresponds to the probability of stopping for futility at the interim analysis.

alpha2

The probability of stopping for superiority at the interim analysis when the null hypothesis is true.

beta1

The probability of stopping for futility at the interim analysis when the alternative hypothesis is true.

alpha

Target type I error rate.

beta

Target type II error rate.

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

n1

The total sample size of the control and experimental groups required at the 1st analysis.

t1l

The lower threshold of the test statistic at the 1st analysis.

t1u

The upper threshold of the test statistic at the 1st analysis.

n2

The cumulative total sample size of the control and experimental groups required at the 2nd analysis.

t2

The threshold of the test statistic at the 2nd analysis.

beta2

Under the null hypothesis, 1 - beta2 denotes the probability of stopping for superiority at the interim analysis.

Note

References

Park, Y. (2025). Optimal two-stage group sequential designs based on Mann-Whitney-Wilcoxon test. PloS one, 20(2), e0318211.

Examples

alpha = 0.05; beta = 0.2; 
p1 = c(0.2, 0.5, 0.2, 0.1)
p2 = c(0.4, 0.3, 0.2, 0.1)
alpha1 <- 0.2
alpha2 <- 0.025
beta1 <- 0.1
Decision_rule_M.FS(p1, p2, alpha1, alpha2, beta1, alpha, beta, lambda = 1)

One-stage clinical trial design based on the Mann-Whitney-Wilcoxon test

Description

This is the function to determine the decision rule for a one-stage clinical trial designs based on the Mann-Whitney-Wilcoxon test.

Usage

Decision_rule_M_1stage(p1, p2, alpha, beta, lambda = 1)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

alpha

Target type I error rate.

beta

Target type II error rate.

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

n2

The total sample size at the final analysis including both the control and experimental groups.

t2

The threshold of the test statistic at the analysis.

Note

References

Park, Y. (2025). Optimal two-stage group sequential designs based on Mann-Whitney-Wilcoxon test. PloS one, 20(2), e0318211.

Examples

alpha = 0.05; beta = 0.2; 
p1 = c(0.2, 0.5, 0.2, 0.1)
p2 = c(0.4, 0.3, 0.2, 0.1)
Decision_rule_M_1stage(p1, p2, alpha, beta, lambda = 1)

Decision rule for the F design based on the score test with the specified values of alpha1 and beta1

Description

This is to determine the decision rule for a two-stage design based on the score test with the specified values of alpha1 and beta1.

Usage

Decision_rule_S.F(p1, p2, alpha1, beta1, alpha, beta, lambda = 1)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

alpha1

The parameter used to define futility monitoring. Under the null hypothesis, 1 - alpha1 corresponds to the probability of stopping for futility at the interim analysis.

beta1

The probability of stopping for futility at the interim analysis when the alternative hypothesis is true.

alpha

Target type I error rate.

beta

Target type II error rate.

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

n1

The total sample size of the control and experimental groups required at the 1st analysis.

t1

The threshold of the test statistic at the 1st analysis.

n2

The cumulative total sample size of the control and experimental groups required at the 2nd analysis.

t2

The threshold of the test statistic at the 2nd analysis.

Note

Examples

alpha = 0.05; beta = 0.2; or = 3.06
p1 = c(0.075, 0.182, 0.319, 0.243, 0.015, 0.166)  # control prob
p2 = p2_fun(p1, log(or))  # experimental prob
p2
alpha1 <- 0.2
beta1 <- 0.1
Decision_rule_S.F(p1, p2, alpha1, beta1, alpha, beta, lambda = 1)

Decision rule of the FS design based on the score test with the specified values of alpha1, alpha2, and beta1

Description

This is the function to determine the decision rule for the FS design based on the score test with the specified values of alpha1, alpha2, and beta1.

Usage

Decision_rule_S.FS(p1, p2, alpha1, alpha2, beta1, alpha, beta, lambda = 1)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

alpha1

The parameter used to define futility monitoring. Under the null hypothesis, 1 - alpha1 corresponds to the probability of stopping for futility at the interim analysis.

alpha2

The probability of stopping for superiority at the interim analysis when the null hypothesis is true.

beta1

The probability of stopping for futility at the interim analysis when the alternative hypothesis is true.

alpha

Target type I error rate.

beta

Target type II error rate.

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

n1

The total sample size of the control and experimental groups required at the 1st analysis.

t1l

The lower threshold of the test statistic at the 1st analysis.

t1u

The upper threshold of the test statistic at the 1st analysis.

n2

The cumulative total sample size of the control and experimental groups required at the 2nd analysis.

t2

The threshold of the test statistic at the 2nd analysis.

beta2

Under the null hypothesis, 1 - beta2 denotes the probability of stopping for superiority at the interim analysis.

Note

Examples

alpha = 0.05; beta = 0.2; or = 3.06
p1 = c(0.075, 0.182, 0.319, 0.243, 0.015, 0.166)  # control prob
p2 = p2_fun(p1, log(or))  # experimental prob
p2
alpha1 <- 0.2
alpha2 <- 0.025
beta1 <- 0.1
Decision_rule_S.FS(p1, p2, alpha1, alpha2, beta1, alpha, beta, lambda = 1)

One-stage clinical trial design based on the score test

Description

This is the function to determine the decision rule for a one-stage clinical trial designs based on the score test.

Usage

Decision_rule_S_1stage(p1, p2, alpha, beta, lambda = 1)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

alpha

Target type I error rate.

beta

Target type II error rate.

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

n2

The total sample size at the final analysis including both the control and experimental groups.

t2

The threshold of the test statistic at the analysis.

Note

References

Park, Y. (2025). Optimal two-stage group sequential designs based on Mann-Whitney-Wilcoxon test. PloS one, 20(2), e0318211.

Examples

alpha = 0.05; beta = 0.2; or = 3.06
p1 = c(0.075, 0.182, 0.319, 0.243, 0.015, 0.166)  # control prob
p2 = p2_fun(p1, log(or))  # experimental prob
p2
Decision_rule_S_1stage(p1, p2, alpha, beta, lambda = 1)

Decision rule of the F design based on the Win Odds test with the specified values of alpha1 and beta1

Description

This is to determine the decision rule for a two-stage design based on the Win Odds test with the specified values of alpha1 and beta1.

Usage

Decision_rule_W.F(p1, p2, alpha1, beta1, alpha, beta, lambda = 1)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

alpha1

The parameter used to define futility monitoring. Under the null hypothesis, 1 - alpha1 corresponds to the probability of stopping for futility at the interim analysis.

beta1

The probability of stopping for futility at the interim analysis when the alternative hypothesis is true.

alpha

Target type I error rate.

beta

Target type II error rate.

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

n1

The total sample size of the control and experimental groups required at the 1st analysis.

t1

The threshold of the test statistic at the 1st analysis.

n2

The cumulative total sample size of the control and experimental groups required at the 2nd analysis.

t2

The threshold of the test statistic at the 2nd analysis.

Note

Examples

alpha = 0.05; beta = 0.2; 
p1 = c(0.2, 0.5, 0.2, 0.1)
p2 = c(0.4, 0.3, 0.2, 0.1)
alpha1 <- 0.2
beta1 <- 0.1
Decision_rule_W.F(p1, p2, alpha1, beta1, alpha, beta, lambda = 1)

Decision rule of the FS design based on the Win Odds test with the specified values of alpha1, alpha2, and beta1

Description

This is the function to determine the decision rule for the FS design based on the Win Odds test with the specified values of alpha1, alpha2, and beta1.

Usage

Decision_rule_W.FS(p1, p2, alpha1, alpha2, beta1, alpha, beta, lambda = 1)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

alpha1

The parameter used to define futility monitoring. Under the null hypothesis, 1 - alpha1 corresponds to the probability of stopping for futility at the interim analysis.

alpha2

The probability of stopping for superiority at the interim analysis when the null hypothesis is true.

beta1

The probability of stopping for futility at the interim analysis when the alternative hypothesis is true.

alpha

Target type I error rate.

beta

Target type II error rate.

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

n1

The total sample size of the control and experimental groups required at the 1st analysis.

t1l

The lower threshold of the test statistic at the 1st analysis.

t1u

The upper threshold of the test statistic at the 1st analysis.

n2

The cumulative total sample size of the control and experimental groups required at the 2nd analysis.

t2

The threshold of the test statistic at the 2nd analysis.

beta2

Under the null hypothesis, 1 - beta2 denotes the probability of stopping for superiority at the interim analysis.

Note

Examples

alpha = 0.05; beta = 0.2; 
p1 = c(0.2, 0.5, 0.2, 0.1)
p2 = c(0.4, 0.3, 0.2, 0.1)
alpha1 <- 0.2
alpha2 <- 0.025
beta1 <- 0.1
Decision_rule_W.FS(p1, p2, alpha1, alpha2, beta1, alpha, beta, lambda = 1)

One-stage clinical trial design based on the Win Odds test

Description

This is the function to determine the decision rule for a one-stage clinical trial designs based on the Win Odds test.

Usage

Decision_rule_W_1stage(p1, p2, alpha, beta, lambda = 1)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

alpha

Target type I error rate.

beta

Target type II error rate.

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

n2

The total sample size at the final analysis including both the control and experimental groups.

t2

The threshold of the test statistic at the analysis.

Note

Examples

alpha = 0.05; beta = 0.2; 
p1 = c(0.2, 0.5, 0.2, 0.1)
p2 = c(0.4, 0.3, 0.2, 0.1)
Decision_rule_W_1stage(p1, p2, alpha, beta, lambda = 1)

Functions deprecated in OptOTrials 1.0.3

Description

Version 1.0.3 introduces rule and op, which replace the separate function provided for each combination of test statistic and stopping rule. The earlier functions still work and still return exactly what they always returned, but they warn, and they will be removed in version 1.1.0.

Details

Deprecated	Replacement
`ruleF`, `ruleFS`	`rule(..., stopping = "F"/"FS")`
`Decision_rule_{S,M,W}.F`	`rule(..., test = ..., stopping = "F")`
`Decision_rule_{S,M,W}.FS`	`rule(..., test = ..., stopping = "FS")`
`Decision_rule_{S,M,W}_1stage`	`rule(..., test = ..., stopping = "none")`
`op.F`, `op.FS`, `op.1stage`	`op(design, nsim, seed)`

Checking proportional odds assumption

Description

This is the function to check the proportional odds assumption for the score test.

Usage

Proportional_odds_assumption(p1, p2, verbose = TRUE)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

verbose

Logical. If TRUE (the default) an explanatory message is printed stating whether the assumption holds and, if so, the implied common odds ratio.

Value

Indicates whether the proportional odds assumption holds. If the assumption holds, the function returns the log-odds ratio from the score test. If the assumption does not hold, the function returns NA and additionally emits a message and a warning explaining that the score test is not advisable and suggesting the Mann-Whitney-Wilcoxon or win odds test, so that the condition is not missed in scripted use.

Calculation of Q or R

Description

This is the function to compute Q or R, which is required for the Mann-Whitney-Wilcoxon test.

Usage

QR_fun(p1, p2)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

Value

The value of Q or R.

Calculation of V

Description

This is the function to compute the value of V over n_{..k}, which is required for the score test, where n_{..k} denotes the total sample size at the kth analysis.

Usage

V_S.over.nk(p1, p2, lambda = 1)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

The value of V over n_{..k}.

Calculation of W

Description

This is the function to compute W, which is required for the Win Odds test.

Usage

W_W(p1, p2, lambda = 1)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

The value of W.

Table of designs and operating characteristics

Description

Builds a data frame of decision rules and simulated operating characteristics over a set of tests and optimality criteria, replacing the expand.grid() and apply() idiom that required positional indexing of returned vectors. The random number generator is re-seeded for every row, so each row is reproducible on its own.

Usage

design_table(alpha, beta, p1, p2, tests, criteria,
             stopping = c("F", "FS"), lambda = 1, nsim = 10000,
             seed = 1234, on_degenerate = c("fallback", "warn", "error", "none"),
             digits = NULL)

Arguments

alpha, beta, p1, p2, lambda

As in rule.

tests

Character vector of tests, a subset of c("S", "M", "W").

criteria

Numeric vector of optimality criteria, a subset of 1 to 5.

stopping

"F" or "FS".

nsim

Number of simulation replicates per row.

seed

Seed applied before each scenario of each row.

on_degenerate

Passed to rule, with the same default, "fallback": a degenerate optimum is replaced by the corresponding single-stage design and the substitution is reported. Set to "none" to report the raw optimum instead, in which case the degenerate column flags the affected rows and their operating characteristics are returned as NA, because a stage-1 total below two patients cannot be allocated to two arms and so cannot be simulated. That is the only case in which the operating characteristics are omitted; any other error from op is passed on.

digits

Optional number of digits for rounding the estimated probabilities. When supplied, EN0 and ENa are rounded to two decimals and EN is recomputed from the rounded values, so that a reader checking EN = (EN0 + ENa)/2 against the printed table reproduces the printed EN exactly. The default NULL returns full precision.

Value

A data frame with one row per (test, criterion) combination, containing the decision rule, the estimated type I error rate and power with Monte Carlo standard errors, the futility and superiority stopping probabilities under each hypothesis, the expected sample sizes, and a degenerate flag.

Examples

p1 <- c(1/3, 1/3, 1/3)
p2 <- c(1/2, 1/3, 1/6)
design_table(0.05, 0.2, p1, p2, tests = "M", criteria = 1,
             stopping = "FS", nsim = 500)

Operating characteristics of a design

Description

Estimates the operating characteristics of a design produced by rule by Monte Carlo simulation. Both hypotheses are evaluated in a single call, and every returned quantity is named, so the meaning of the output does not depend on how the function was called.

Usage

op(design, nsim = 10000, seed = NULL, p1 = NULL, p2 = NULL,
   allow_degenerate = FALSE)

Arguments

design

An object returned by rule.

nsim

Number of simulation replicates (default 10000).

seed

Optional integer. If supplied, the random number generator is seeded immediately before each scenario, so the result is reproducible independently of the state of the stream when op() is reached.

p1, p2

Optional category probabilities overriding those stored in design, for evaluating a design under a scenario other than the one it was built for.

allow_degenerate

Logical. A degenerate two-stage optimum that has not been replaced by its single-stage substitute cannot be simulated meaningfully, because its stage-1 size is too small to allocate patients to both arms; such a design is refused by default. Set to TRUE to override the check.

Value

An object of class "OptOTrialsOC" containing alpha and power with their Monte Carlo standard errors se_alpha and se_power, the expected sample sizes EN0, ENa and EN, and a data frame table reporting, under each hypothesis, the rejection probability, the probability of stopping early for futility, the probability of stopping early for superiority, the probability of continuing to the second stage, and the expected sample size. Futility and superiority stopping are reported separately rather than pooled.

Examples

p1 <- c(0.075, 0.182, 0.319, 0.243, 0.015, 0.166)
p2 <- p2_fun(p1, log(3.06))
d <- rule(0.05, 0.2, p1, p2, test = "M", stopping = "F", criterion = 1)
op(d, nsim = 1000, seed = 1234)

Performance evaluation of a one-stage design

Description

This is the function to calculate the operating characteristics for a one-stage design, including type I error, power, and expected sample size.

Usage

op.1stage(alpha, beta, p1, p2, method, n2, t2, nsim = 10000, lambda = 1)

Arguments

alpha

Target type I error rate.

beta

Target type II error rate.

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

method

"S", "M" or "W", denotes score test, Mann-Whitney-Wilcoxon test and wi n odds test respectively.

n2

The cumulative total sample size of the control and experimental groups required at the 2nd analysis.

t2

The threshold of the test statistic at the 2nd analysis.

nsim

The number of simulations. nsim = 10000 by default

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

A numeric vector of length 2. The first element is the probability of rejecting the null hypothesis: this is the type I error rate when the simulation is run under the null (i.e. when p2 is set equal to p1) and the power when it is run under the alternative. The second element is the corresponding expected total sample size. Note that this is a rejection probability, not a probability of an incorrect decision.

For named, self-describing output that reports both hypotheses in a single call together with Monte Carlo standard errors and separate futility and superiority stopping probabilities, use op instead.

Note

This function is deprecated as of OptOTrials 1.0.3 and will be removed in version 1.1.0. It still returns exactly what it always returned, but it now warns. Use op instead; help("OptOTrials-deprecated") tabulates every replacement.

Examples

set.seed(1234)
alpha = 0.05; beta = 0.2; 
p1 = c(0.2, 0.5, 0.2, 0.1)
p2 = c(0.4, 0.3, 0.2, 0.1)
out <- Decision_rule_W_1stage(p1, p2, alpha, beta, lambda = 1)
# report the power and EN_a
op.1stage(alpha, beta, p1, p2, method="W", n2=out[1], t2=out[2], nsim = 1000, lambda = 1)
# report the overall type I error rate and EN_0
op.1stage(alpha, beta, p1, p1, method="W", n2=out[1], t2=out[2], nsim = 1000, lambda = 1)

Performance evaluation of the F design

Description

This is the function to calculate the operating characteristics for the F design, including type I error, power, and expected sample size.

Usage

op.F(alpha, beta, p1, p2, method, n1, t1, n2, t2, nsim = 10000, lambda = 1)

Arguments

alpha

Target type I error rate.

beta

Target type II error rate.

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

method

"S", "M" or "W", denotes score test, Mann-Whitney-Wilcoxon test and wi n odds test respectively.

n1

The total sample size of the control and experimental groups required at the 1st analysis.

t1

The threshold of the test statistic at the 1st analysis.

n2

The cumulative total sample size of the control and experimental groups required at the 2nd analysis.

t2

The threshold of the test statistic at the 2nd analysis.

nsim

The number of simulations. nsim = 10000 by default

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

Note

Examples

set.seed(1234)	
alpha = 0.05; beta = 0.2; 
p1 = c(0.2, 0.5, 0.2, 0.1)
p2 = c(0.4, 0.3, 0.2, 0.1)
alpha1 <- 0.2
beta1 <- 0.1
out <- Decision_rule_W.F(p1, p2, alpha1, beta1, alpha, beta, lambda = 1)


	# heavier example for illustration (skipped on CRAN timing checks)
# report the power and EN_a
op.F(alpha, beta, p1, p2, method="W", n1=out[1], t1=out[2], n2=out[3],
 t2=out[4], nsim = 10000, lambda = 1)
# report the overall type I error rate and EN_0
op.F(alpha, beta, p1, p1, method="W", n1=out[1], t1=out[2], n2=out[3],
 t2=out[4], nsim = 10000, lambda = 1)

Performance evaluation of the FS design

Description

This is the function to calculate the operating characteristics for the FS design, including type I error, power, and expected sample size.

Usage

op.FS(alpha, beta, p1, p2, method, n1, t1l, t1u, n2, t2, nsim = 10000, lambda = 1)

Arguments

alpha

Target type I error rate.

beta

Target type II error rate.

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

method

"S", "M" or "W", denotes score test, Mann-Whitney-Wilcoxon test and win odds test respectively.

n1

The total sample size of the control and experimental groups required at the 1st analysis.

t1l

The lower threshold of the test statistic at the 1st analysis.

t1u

The upper threshold of the test statistic at the 1st analysis.

n2

The cumulative total sample size of the control and experimental groups required at the 2nd analysis.

t2

The threshold of the test statistic at the 2nd analysis.

nsim

The number of simulations. nsim = 10000 by default

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

Note

Examples

set.seed(1234)	
alpha = 0.05; beta = 0.2; 
p1 = c(0.2, 0.5, 0.2, 0.1)
p2 = c(0.4, 0.3, 0.2, 0.1)
alpha1 <- 0.2
alpha2 <- 0.025
beta1 <- 0.1
out <- Decision_rule_W.FS(p1, p2, alpha1, alpha2, beta1, alpha, beta, lambda = 1)


	# heavier example for illustration (skipped on CRAN timing checks)
# report the power and EN_a
op.FS(alpha, beta, p1, p2, method="W", n1=out[1], t1l=out[2], 
	t1u=out[3], n2=out[4], t2=out[5], nsim = 10000, lambda = 1)
# report the overall type I error rate and EN_0
op.FS(alpha, beta, p1, p1, method="W", n1=out[1], t1l=out[2], 
	t1u=out[3], n2=out[4], t2=out[5], nsim = 10000, lambda = 1)

p2

Description

This is the function to calculate the probability p2 when p1 and odds ratio are given.

Usage

p2_fun(p1, theta)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

theta

The log odds ratio according to expected effect of the experimental treatment.

Value

A numeric vector representing the expected probability distribution of outcomes across levels for the experimental group.

p_minus

Description

This is the function to compute p-, which is required for the Mann-Whitney-Wilcoxon test.

Usage

p_minus(p1, p2)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

Value

The value of p-.

p_plus

Description

This is the function to compute p+, which is required for the Mann-Whitney-Wilcoxon test.

Usage

p_plus(p1, p2)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

Value

The value of p+.

Calculation of pq

Description

This is the function to compute p_{jk} and q_{ik}, which are required for the Win Odds test.

Usage

pq_fun(p1, p2)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

Value

The value of p_{jk} and q_{ik}.

Optimal design for a trial with an ordered categorical outcome

Description

Constructs the decision rule for a one- or two-stage randomised trial with an ordered categorical outcome. This is the recommended entry point to the package: the test statistic and the monitoring scheme are selected by argument, so a single function replaces the eleven separate decision-rule functions provided up to version 1.0.2.

Usage

rule(alpha, beta, p1, p2, test = c("S", "M", "W"),
     stopping = c("F", "FS", "none"), criterion = 1, lambda = 1,
     on_degenerate = c("fallback", "warn", "error", "none"), min_n1 = 10)

Arguments

alpha

Target type I error rate.

beta

Target type II error rate; power is 1 - beta.

p1

Numeric vector of outcome category probabilities for the control group. Must be non-negative and sum to 1.

p2

Numeric vector of outcome category probabilities for the experimental group. Must be the same length as p1, non-negative, and sum to 1.

test

Test statistic: "S" the score test under the proportional odds model, "M" the Mann-Whitney-Wilcoxon test, "W" the win odds test.

stopping

Monitoring scheme: "F" allows early stopping for futility only, "FS" for futility and superiority, "none" gives a single-stage design.

criterion

Optimality criterion, 1 to 5. 1: minimise the expected total sample size under the null; 2: under the alternative; 3: assuming Pr(H0) = Pr(Ha); 4: balance the two stages prioritising EN0; 5: balance the two stages prioritising the maximum sample size. Ignored when stopping = "none".

lambda

Ratio of experimental to control sample sizes (default 1).

on_degenerate

How to handle a degenerate optimum (see Details). "fallback" (default) warns and returns the single-stage design; "warn" warns and returns the degenerate design; "error" raises an error; "none" returns the raw optimum silently.

min_n1

Smallest stage-1 sample size regarded as usable when detecting degeneracy (default 10).

Details

Minimising the expected sample size under the alternative (criterion = 2) can drive the optimum to a design with a stage-1 sample size of 1 and an interim boundary so far into the lower tail that the interim analysis cannot change any decision: the design is then two-stage in name only. Intuitively, the criterion rewards designs under which continuation to the final analysis is almost certain when the treatment works, so the optimiser commits essentially all information to the final analysis. rule() detects this and, by default, substitutes the corresponding single-stage design, recording the substitution in the returned object rather than making it silently.

Value

An object of class "OptOTrialsRule": a list with components test, stopping, criterion, alpha, beta, lambda, p1, p2, the stage-1 size n1, the interim futility and superiority boundaries t1f and t1s, the maximum size n2, the final boundary t2, a data frame effect giving each boundary on a clinically interpretable effect-size scale (odds ratio for the score test, win odds for the rank-based tests), and the flags degenerate, degenerate_reason and substituted. A print method displays these with labels.

Note

The name rule is also used by the cli package, which MAMS and several other packages attach. If cli is attached after OptOTrials, cli::rule masks this function for the rest of the session. Attach OptOTrials last, or call OptOTrials::rule() explicitly.

Examples

p1 <- c(0.075, 0.182, 0.319, 0.243, 0.015, 0.166)
p2 <- p2_fun(p1, log(3.06))
rule(0.05, 0.2, p1, p2, test = "M", stopping = "F", criterion = 1)

Decision rule of the F design

Description

This is the function to determine the decision rule for the F design.

Usage

ruleF(alpha, beta, p1, p2, method, criterion, lambda = 1)

Arguments

alpha

Target type I error rate.

beta

Target type II error rate.

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

method

"S", "M" or "W", denotes score test, Mann-Whitney-Wilcoxon test and win odds test respectively.

criterion

1: minimizing the expected total sample size under the null hypothesis, 2: minimizing the expected total sample size under the alternative hypothesis, 3: minimizing the expected total sample size assuming that Pr(H0) = Pr(Ha), 4: balancing sample sizes of the two stages prioritizing EN0, 5: balancing sample sizes of the two stages prioritizing maximum sample size n2.

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

method

Statistical test chosen.

criterion

Criterion chosen.

n1

The total sample size of the control and experimental groups required at the 1st analysis.

t1

The threshold of the test statistic at the 1st analysis.

n2

The cumulative total sample size of the control and experimental groups required at the 2nd analysis.

t2

The threshold of the test statistic at the 2nd analysis.

Note

Examples

alpha = 0.05; beta = 0.2; 
p1 = c(0.2, 0.5, 0.2, 0.1)
p2 = c(0.4, 0.3, 0.2, 0.1)
ruleF(alpha, beta, p1, p2, method="M", criterion="1", lambda = 1)

Decision rule of the FS design

Description

This is the function to determine the decision rule for the FS design.

Usage

ruleFS(alpha, beta, p1, p2, method, criterion, lambda = 1)

Arguments

alpha

Target type I error rate.

beta

Target type II error rate.

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

method

"S", "M" or "W", denotes score test, Mann-Whitney-Wilcoxon test and win odds test respectively.

criterion

lambda

The ratio of sample sizes between the experimental and control groups, defined as sample size (experimental): sample size (control) = lambda:1. The default value is 1.

Value

method

Statistical test chosen.

criterion

Criterion chosen.

n1

The total sample size of the control and experimental groups required at the 1st analysis.

t1l

The lower threshold of the test statistic at the 1st analysis.

t1u

The upper threshold of the test statistic at the 1st analysis.

n2

The cumulative total sample size of the control and experimental groups required at the 2nd analysis.

t2

The threshold of the test statistic at the 2nd analysis.

Note

Examples

alpha = 0.05; beta = 0.2; 
p1 = c(0.2, 0.5, 0.2, 0.1)
p2 = c(0.4, 0.3, 0.2, 0.1)
ruleFS(alpha, beta, p1, p2, method="M", criterion="1", lambda = 1)

Calculation of theta

Description

This is the function to compute theta (i.e., the expectation of T), which is required for the Win Odds test.

Usage

theta(p1, p2)

Arguments

p1

A vector containing the probabilities of the outcome falling into each level of the control arm.

p2

A vector containing the probabilities of the outcome falling into each level of the experimental arm.

Value

The value of theta

Package {OptOTrials}

Optimal Two-Stage Designs for Ordered Categorical Outcomes

Description

Details

Author(s)

References

Decision rule for the F design based on the Mann-Whitney-Wilcoxon test with specified values of alpha1 and beta1

Description

Usage

Arguments

Value

Note

References

Examples

Decision rule for the FS design based on the Mann-Whitney-Wilcoxon test with the specified values of alpha1, alpha2, and beta1

Description

Usage

Arguments

Value

Note

References

Examples

One-stage clinical trial design based on the Mann-Whitney-Wilcoxon test

Description

Usage

Arguments

Value

Note

References

Examples

Decision rule for the F design based on the score test with the specified values of alpha1 and beta1

Description

Usage

Arguments

Value

Note

Examples

Decision rule of the FS design based on the score test with the specified values of alpha1, alpha2, and beta1

Description

Usage

Arguments

Value

Note

Examples

One-stage clinical trial design based on the score test

Description

Usage

Arguments

Value

Note

References

Examples

Decision rule of the F design based on the Win Odds test with the specified values of alpha1 and beta1

Description

Usage

Arguments

Value

Note

Examples

Decision rule of the FS design based on the Win Odds test with the specified values of alpha1, alpha2, and beta1

Description

Usage

Arguments

Value

Note

Examples

One-stage clinical trial design based on the Win Odds test

Description

Usage

Arguments

Value

Note

Examples

Functions deprecated in OptOTrials 1.0.3

Description

Details

See Also

Checking proportional odds assumption

Description

Usage