% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/getDesignMeans.R
\name{getDesignWilcoxon}
\alias{getDesignWilcoxon}
\title{Group Sequential Design for Two-Sample Wilcoxon Test}
\usage{
getDesignWilcoxon(
  beta = NA_real_,
  n = NA_real_,
  pLarger = 0.6,
  allocationRatioPlanned = 1,
  rounding = TRUE,
  kMax = 1L,
  informationRates = NA_real_,
  efficacyStopping = NA_integer_,
  futilityStopping = NA_integer_,
  criticalValues = NA_real_,
  alpha = 0.025,
  typeAlphaSpending = "sfOF",
  parameterAlphaSpending = NA_real_,
  userAlphaSpending = NA_real_,
  futilityBounds = NA_real_,
  futilityCP = NA_real_,
  futilitypLarger = NA_real_,
  typeBetaSpending = "none",
  parameterBetaSpending = NA_real_,
  userBetaSpending = NA_real_,
  spendingTime = NA_real_
)
}
\arguments{
\item{beta}{The type II error.}

\item{n}{The total sample size.}

\item{pLarger}{The probability that a randomly chosen sample from
the treatment group is larger than a randomly chosen sample from the
control group under the alternative hypothesis.}

\item{allocationRatioPlanned}{Allocation ratio for the active treatment
versus control. Defaults to 1 for equal randomization.}

\item{rounding}{Whether to round up sample size. Defaults to 1 for
sample size rounding.}

\item{kMax}{The maximum number of stages.}

\item{informationRates}{The information rates. Fixed prior to the trial.
Defaults to \code{(1:kMax) / kMax} if left unspecified.}

\item{efficacyStopping}{Indicators of whether efficacy stopping is allowed
at each stage. Defaults to \code{TRUE} if left unspecified.}

\item{futilityStopping}{Indicators of whether futility stopping is allowed
at each stage. Defaults to \code{TRUE} if left unspecified.}

\item{criticalValues}{Upper boundaries on the z-test statistic scale
for stopping for efficacy.}

\item{alpha}{The significance level. Defaults to 0.025.}

\item{typeAlphaSpending}{The type of alpha spending. One of the following:
\code{"OF"} for O'Brien-Fleming boundaries,
\code{"P"} for Pocock boundaries,
\code{"WT"} for Wang & Tsiatis boundaries,
\code{"sfOF"} for O'Brien-Fleming type spending function,
\code{"sfP"} for Pocock type spending function,
\code{"sfKD"} for Kim & DeMets spending function,
\code{"sfHSD"} for Hwang, Shi & DeCani spending function,
\code{"user"} for user defined spending, and
\code{"none"} for no early efficacy stopping.
Defaults to \code{"sfOF"}.}

\item{parameterAlphaSpending}{The parameter value for the alpha spending.
Corresponds to \eqn{\Delta} for \code{"WT"}, \eqn{\rho} for \code{"sfKD"},
and \eqn{\gamma} for \code{"sfHSD"}.}

\item{userAlphaSpending}{The user defined alpha spending. Cumulative alpha
spent up to each stage.}

\item{futilityBounds}{Lower boundaries on the z-test statistic scale
for stopping for futility at stages \code{1, ..., kMax-1}. Defaults to
\code{rep(-8, kMax-1)} if left unspecified. The futility bounds are
non-binding for the calculation of critical values.}

\item{futilityCP}{The futility bounds on the conditional power scale.}

\item{futilitypLarger}{The futility bounds on the pLarger scale.}

\item{typeBetaSpending}{The type of beta spending. One of the following:
\code{"sfOF"} for O'Brien-Fleming type spending function,
\code{"sfP"} for Pocock type spending function,
\code{"sfKD"} for Kim & DeMets spending function,
\code{"sfHSD"} for Hwang, Shi & DeCani spending function,
\code{"user"} for user defined spending, and
\code{"none"} for no early futility stopping.
Defaults to \code{"none"}.}

\item{parameterBetaSpending}{The parameter value for the beta spending.
Corresponds to \eqn{\rho} for \code{"sfKD"}, and
\eqn{\gamma} for \code{"sfHSD"}.}

\item{userBetaSpending}{The user defined beta spending. Cumulative beta
spent up to each stage.}

\item{spendingTime}{A vector of length \code{kMax} for the error spending
time at each analysis. Defaults to missing, in which case, it is the
same as \code{informationRates}.}
}
\value{
An S3 class \code{designWilcoxon} object with three
components:
\itemize{
\item \code{overallResults}: A data frame containing the following variables:
\itemize{
\item \code{overallReject}: The overall rejection probability.
\item \code{alpha}: The overall significance level.
\item \code{attainedAlpha}: The attained significance level, which is
different from the overall significance level in the presence of
futility stopping..
\item \code{kMax}: The number of stages.
\item \code{theta}: The parameter value.
\item \code{information}: The maximum information.
\item \code{expectedInformationH1}: The expected information under H1.
\item \code{expectedInformationH0}: The expected information under H0.
\item \code{drift}: The drift parameter, equal to
\code{theta*sqrt(information)}.
\item \code{inflationFactor}: The inflation factor (relative to the
fixed design).
\item \code{numberOfSubjects}: The maximum number of subjects.
\item \code{expectedNumberOfSubjectsH1}: The expected number of subjects
under H1.
\item \code{expectedNumberOfSubjectsH0}: The expected number of subjects
under H0.
\item \code{pLarger}: The probability that a randomly chosen sample from
the treatment group is larger than a randomly chosen sample from the
control group under the alternative hypothesis.
}
\item \code{byStageResults}: A data frame containing the following variables:
\itemize{
\item \code{informationRates}: The information rates.
\item \code{efficacyBounds}: The efficacy boundaries on the Z-scale.
\item \code{futilityBounds}: The futility boundaries on the Z-scale.
\item \code{rejectPerStage}: The probability for efficacy stopping.
\item \code{futilityPerStage}: The probability for futility stopping.
\item \code{cumulativeRejection}: The cumulative probability for efficacy
stopping.
\item \code{cumulativeFutility}: The cumulative probability for futility
stopping.
\item \code{cumulativeAlphaSpent}: The cumulative alpha spent.
\item \code{efficacyP}: The efficacy boundaries on the p-value scale.
\item \code{futilityP}: The futility boundaries on the p-value scale.
\item \code{information}: The cumulative information.
\item \code{efficacyStopping}: Whether to allow efficacy stopping.
\item \code{futilityStopping}: Whether to allow futility stopping.
\item \code{rejectPerStageH0}: The probability for efficacy stopping
under H0.
\item \code{futilityPerStageH0}: The probability for futility stopping
under H0.
\item \code{cumulativeRejectionH0}: The cumulative probability for
efficacy stopping under H0.
\item \code{cumulativeFutilityH0}: The cumulative probability for futility
stopping under H0.
\item \code{efficacyPLarger}: The efficacy boundaries on the proportion
of pairs of samples from the two treatment groups with the sample
from the treatment group greater than that from the control group.
\item \code{futilityPLarger}: The futility boundaries on the proportion
of pairs of samples from the two treatment groups with the sample
from the treatment group greater than that from the control group.
\item \code{numberOfSubjects}: The number of subjects.
}
\item \code{settings}: A list containing the following input parameters:
\itemize{
\item \code{typeAlphaSpending}: The type of alpha spending.
\item \code{parameterAlphaSpending}: The parameter value for alpha
spending.
\item \code{userAlphaSpending}: The user defined alpha spending.
\item \code{typeBetaSpending}: The type of beta spending.
\item \code{parameterBetaSpending}: The parameter value for beta spending.
\item \code{userBetaSpending}: The user defined beta spending.
\item \code{spendingTime}: The error spending time at each analysis.
\item \code{allocationRatioPlanned}: Allocation ratio for the active
treatment versus control.
\item \code{rounding}: Whether to round up sample size.
}
}
}
\description{
Obtains the power given sample size or obtains the sample
size given power for a group sequential design for two-sample
Wilcoxon test.
}
\details{
The Mann-Whitney U test is a non-parametric test for the
difference in location between two independent groups. It is
also known as the Wilcoxon rank-sum test. The test is based on
the ranks of the data rather than the actual values, making it
robust to outliers and non-normal distributions.
The test statistic is the number of times a randomly
chosen sample from the treatment group is larger than a
randomly chosen sample from the control group, i.e.,
\deqn{W_{XY} = \sum_{i=1}^{n_1}\sum_{j=1}^{n_2} I(X_i > Y_j)}
where \eqn{X_i} and \eqn{Y_j} are the samples from the
treatment and control groups, respectively.
The test is often used when the data
do not meet the assumptions of the t-test, such as
non-normality or unequal variances.
The test is also applicable to ordinal data.
The test is one-sided, meaning that it only tests
whether the treatment group is larger than the control group.
Asymptotically,
\deqn{\frac{W_{XY} - n_1 n_2/2}{\sqrt{n_1 n_2 (n+1)/12}} \sim N(0,1)
\quad \text{under} H_0}
where \eqn{n_1} and \eqn{n_2} are the sample sizes of the treatment
and control groups, respectively, and \eqn{n=n_1+n_2}.
Let \eqn{\theta = P(X > Y)}, and
\eqn{\hat{\theta} = \frac{1}{nm}W_{XY}}. It follows that
\deqn{\sqrt{n}(\hat{\theta} - 1/2) \sim
N\left(0, \frac{1}{12 r(1-r)}\right) \quad \text{under} H_0}
where \eqn{r = n_1/(n_1+n_2)} is the randomization probability
for the active treatment group.
This formulation allows for group sequential testing with
futility stopping and efficacy stopping.
}
\examples{

# Example 1: fixed design
(design1 <- getDesignWilcoxon(
  beta = 0.1, n = NA,
  pLarger = pnorm((8 - 2)/sqrt(2*25^2)), alpha = 0.025))

# Example 2: group sequential design
(design2 <- getDesignWilcoxon(
  beta = 0.1, n = NA,
  pLarger = pnorm((8 - 2)/sqrt(2*25^2)), alpha = 0.025,
  kMax = 3, typeAlphaSpending = "sfOF"))

}
\author{
Kaifeng Lu, \email{kaifenglu@gmail.com}
}
