Package 'bbssr'

Description

Lowers the nominal significance level of a two-arm trial with a binary endpoint and blinded sample size re-estimation (BSSR) until the largest type I error rate over the common response probability, or over the pooled response probability on the boundary of a non-inferiority hypothesis, does not exceed the target level alpha, and returns the adjusted level together with that of the fixed-sample design.

Usage

BinaryAlphaAdjBSSR(
  Delta.A,
  N1,
  N2,
  omega = NULL,
  r,
  alpha,
  tar.power,
  Test,
  restricted = FALSE,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  tsmethod = c("minlike", "central", "blaker"),
  n.grid = 100,
  bb.gamma = 0,
  effect = c("RD", "RR", "OR"),
  ss.method = c("exact", "standard", "null.variance", "alternative.variance"),
  ss.Test = Test,
  ss.alpha = alpha,
  rounding = c("group", "friede-kieser", "total", "nearest"),
  search = c("crossing", "smallest", "stable"),
  search.limit = c(2, 50),
  N.min = NULL,
  N.max = NULL,
  n.interim = NULL,
  theta = seq(0, 1, by = 0.005),
  maximize = c("certified", "refined", "grid"),
  adjust = c("test", "both"),
  tol = 1e-08,
  step = 1e-05,
  margin = 0,
  ref.pvalue = FALSE,
  margin.scale = c("RD", "RR")
)

Arguments

Details

Following Kieser and Friede (2000) and Friede and Kieser (2004), the nominal level of the final analysis is lowered until the largest type I error rate over the common response probability, evaluated as in BinaryTypeIErrorBSSR, does not exceed alpha.

With adjust = 'test' the final sample sizes do not depend on the nominal level, and the rejection regions shrink as the level decreases, so the largest type I error rate is a non-decreasing step function of the level. The bisection locates, to within tol * alpha, the level above which the largest rate exceeds alpha. The package rejects a p-value at a level when it is below the level by more than a tolerance of about 1.49e-8, so every level between the largest p-value rejected at the level found plus this tolerance and the smallest p-value not rejected gives the same rejection regions, also when a p-value is rejected if it is below the level or at most equal to it. The reported alpha.adj is the largest value with at most six significant digits in this range, or with more digits if there is none, so the printed value can be used as it is. The same applies to the fixed-sample design.

With adjust = 'both' the re-estimated sample sizes change with the level as well, so the type I error rate need not be monotone in the level. The level is then lowered from alpha in steps of step until the type I error rate is controlled. The result is the first level among alpha - step, alpha - 2 * step, and so on, at which the type I error rate is controlled, and it can change with step. The levels that control the type I error rate need not form an interval, so a level below the result can fail, and a level above it that is not on this grid can pass. This search re-estimates the sample size at every step and can take much longer than the bisection. The fixed-sample design always uses the bisection, since its sample size does not depend on the level. The script reproduce-published.R in the folder system.file('reproduce', package = 'bbssr') reproduces the published values of Section 5 of Friede and Kieser (2004) and of Example 21.1 of Kieser (2020) only when the re-estimation also uses the adjusted level, as with adjust = 'both'.

The type I error rate can also be controlled within a confidence interval for the common response probability, or for the pooled response probability on the null boundary, instead of over its whole range (Kieser, 2020, Section 22.1.3). A value gamma between 0 and alpha is fixed in advance, and the final analysis uses a level at which the largest type I error rate over the 1 - gamma confidence interval computed from the data of the completed trial does not exceed alpha - gamma. The type I error rate is then controlled at alpha. This level is found when theta spans the interval and alpha is set to alpha - gamma. The interval is known only at the end of the trial, so the re-estimation keeps the nominal level, with adjust = 'test' and ss.alpha set to the nominal level. Neither search examines levels above alpha - gamma. The script reproduce-published.R reproduces the adjusted level of Example 23.1 of Kieser (2020), which uses the Clopper-Pearson interval with gamma = 1e-4.

With maximize = 'certified' the levels are assessed on the grid with the refinement of maximize = 'refined', and the level found is then certified as in BinaryTypeIErrorBSSR: it is accepted only if the upper bound of the type I error rate over the interval from the smallest to the largest value of theta does not exceed alpha. If the bound exceeds alpha, the grid has missed a value of theta at which the level fails, or the largest rate lies within 1e-12 below alpha, and the search continues below that level. The bisection then certifies every level that passes the assessment on the grid, and the search of adjust = 'both' certifies every such level from the start. The adjusted level therefore controls the type I error rate over the whole interval. If a certification stops at its limit of 1e5 subdivisions, with a warning, the bound can exceed the largest rate by more than 1e-12, and the level found can be lower than necessary.

In both searches the type I error rate at a new level is first evaluated at the single value of theta where the largest rate of the last level that failed was found. If it exceeds alpha there, the level fails without the evaluation over the whole grid. The largest rate over theta is never below the rate at any one value, so such a level also fails on the largest rate. With maximize = 'grid' this value is a grid point, and every decision is that of the evaluation on the grid. With 'refined' and 'certified' it can lie between the grid points, where the grid can miss a rate above alpha, so a level can fail that the evaluation on the grid would accept. This can only lower the level found, and with 'certified' the level found is certified in either case.

Value

An object of class bbssr_alphaadj, a data frame with one row for the BSSR design and one for the fixed-sample design containing:

Design

'BSSR' or 'TRAD'

alpha

Target level

max.TIE

Largest type I error rate at the nominal level alpha

alpha.adj

Adjusted nominal level, see Details. It is alpha when the nominal level already controls the type I error rate, and 0, with a warning, when no level examined by the bisection does. The search of adjust = 'both' for the BSSR design stops with an error instead when it reaches 0

max.TIE.adj

Largest type I error rate at the adjusted level, 0 when alpha.adj is 0

theta.adj

Common response probability, or pooled response probability on the null boundary, at which max.TIE.adj occurs, NA when alpha.adj is 0

max.TIE.bound

Upper bound of the type I error rate at the nominal level with maximize = 'certified', otherwise NA

max.TIE.adj.bound

Upper bound of the type I error rate at the adjusted level with maximize = 'certified', otherwise NA

For alternative = 'equivalence' the largest rates are taken over both boundaries of the null hypothesis, see BinaryTypeIErrorBSSR, and the column boundary.adj gives the boundary, 'lower' or 'upper', on which max.TIE.adj occurs.

Author(s)

Gosuke Homma ([email protected])

References

Kieser M, Friede T (2000). Re-calculating the sample size in internal pilot study designs with control of the type I error rate. Statistics in Medicine, 19(7), 901-911.

Friede T, Kieser M (2004). Sample size recalculation for binary data in internal pilot study designs. Pharmaceutical Statistics, 3(4), 269-279.

Kieser M (2020). Methods and Applications of Sample Size Calculation and Recalculation in Clinical Trials. Springer, Cham.

See Also

BinaryTypeIErrorBSSR

Examples

BinaryAlphaAdjBSSR(
  Delta.A = 0.3, N1 = 39, N2 = 39, n.interim = c(20, 20), r = 1,
  alpha = 0.025, tar.power = 0.8, Test = 'Chisq', ss.method = 'standard',
  theta = seq(0.01, 0.99, by = 0.01)
)

Description

Re-estimates the sample size of an ongoing two-arm trial with a binary endpoint from the blinded data available at an interim analysis, and reports how many patients still have to be enrolled in each group during the second stage. Only the total number of patients and the total number of responders are required, so the treatment allocation remains concealed.

Usage

BinaryBSSR(
  n1,
  n2,
  S,
  Delta.A,
  r,
  alpha,
  tar.power,
  Test,
  restricted = FALSE,
  N1 = NULL,
  N2 = NULL,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  tsmethod = c("minlike", "central", "blaker"),
  n.grid = 100,
  bb.gamma = 0,
  effect = c("RD", "RR", "OR"),
  ss.method = c("exact", "standard", "null.variance", "alternative.variance"),
  ss.Test = Test,
  ss.alpha = alpha,
  rounding = c("group", "friede-kieser", "total", "nearest"),
  search = c("crossing", "smallest", "stable"),
  search.limit = c(2, 50),
  N.min = NULL,
  N.max = NULL,
  margin = 0,
  ref.pvalue = FALSE,
  margin.scale = c("RD", "RR")
)

Arguments

Details

The blinded estimate of the pooled response probability is hat.p = S / (n1 + n2). For the risk difference, group-specific proportions are recovered as hat.p1 = hat.p + Delta.A / (1 + r) and hat.p2 = hat.p - r Delta.A / (1 + r), truncated to the unit interval. For the risk ratio and the odds ratio they are the proportions with the pooled value hat.p and the ratio Delta.A. The sample size is then re-estimated as in BinarySampleSize.

Under the unrestricted rule and rounding = 'group', the final size of group 2 is the larger of the re-estimated size and what has already been observed. Under the restricted rule it is raised to the planned size first, so the trial can only grow, and N.min and N.max add a further lower and upper bound on the total. The final size of group 1 is then ceiling(r N2.final), so an imbalance already present at the interim is corrected by the remaining enrolment instead of being carried forward. Neither second-stage size is ever negative. The other rounding rules are described in BinaryPowerBSSR.

While BinaryPowerBSSR evaluates the operating characteristics of a BSSR design at the planning stage, this function is applied once, to the data of a trial that is under way.

Value

An object of class bbssr_bssr, a data frame with one row containing:

n1

Interim sample size of group 1

n2

Interim sample size of group 2

n

Total interim sample size

S

Total number of interim responders

hat.p

Blinded estimate of the pooled response probability

hat.p1

Recovered response probability of group 1

hat.p2

Recovered response probability of group 2

N1.re

Re-estimated total sample size of group 1

N2.re

Re-estimated total sample size of group 2, before the bounds; with ss.method = 'exact' at most the largest size that N.max allows

N.re

Re-estimated total sample size

n1.stage2

Number of additional patients to enrol in group 1

n2.stage2

Number of additional patients to enrol in group 2

n.stage2

Total number of additional patients to enrol

N1.final

Final sample size of group 1

N2.final

Final sample size of group 2

N.final

Final total sample size

Power

Exact power at the final sample size under the recovered proportions

The attribute search holds the search, and the attribute search.limit the limit of the size of group 2 examined by search = 'stable' (otherwise NA).

Author(s)

Gosuke Homma ([email protected])

See Also

BinaryPowerBSSR, BinarySampleSize

Examples

# Interim data: 20 patients per group, 11 responders in total
BinaryBSSR(n1 = 20, n2 = 20, S = 11, Delta.A = 0.3, r = 1,
           alpha = 0.025, tar.power = 0.8, Test = 'Chisq')


# Restricted rule with a planned sample size of 40 per group
BinaryBSSR(n1 = 20, n2 = 20, S = 11, Delta.A = 0.3, r = 1,
           alpha = 0.025, tar.power = 0.8, Test = 'Boschloo',
           restricted = TRUE, N1 = 40, N2 = 40)

Description

Computes, under the null hypothesis of equal response probabilities, the probability that a two-arm trial with a binary endpoint and blinded sample size re-estimation (BSSR) rejects the null hypothesis given the pooled number of responders at the interim analysis and in the second stage. These conditional rejection probabilities do not depend on the common response probability, and the type I error rate is their average over the binomial distribution of the two pooled counts. With theta, the type I error rate is also returned for each pooled number of interim responders.

Usage

BinaryCondRejectBSSR(
  Delta.A,
  N1,
  N2,
  omega = NULL,
  r,
  alpha,
  tar.power,
  Test,
  restricted = FALSE,
  alternative = c("greater", "less", "two.sided"),
  tsmethod = c("minlike", "central", "blaker"),
  n.grid = 100,
  bb.gamma = 0,
  effect = c("RD", "RR", "OR"),
  ss.method = c("exact", "standard", "null.variance", "alternative.variance"),
  ss.Test = Test,
  ss.alpha = alpha,
  rounding = c("group", "friede-kieser", "total", "nearest"),
  search = c("crossing", "smallest", "stable"),
  search.limit = c(2, 50),
  N.min = NULL,
  N.max = NULL,
  n.interim = NULL,
  theta = NULL,
  margin = 0,
  ref.pvalue = FALSE
)

Arguments

Details

Let n11 and n12 be the interim sample sizes of the two groups, and let n21(s) and n22(s) be the second-stage sizes reached from the pooled number s of interim responders. Under the null hypothesis both groups share the response probability theta. Given s, the number of interim responders in group 1 is hypergeometric, being the number of group 1 patients among s responders drawn from n11 + n12 patients. Given the pooled number s2 of second-stage responders, the number of second-stage responders in group 1 is an independent hypergeometric count of the same kind. CRP sums the rejection region of the final sample size over these two distributions and does not depend on theta. The type I error rate is sum_s sum_s2 b(s; n11 + n12, theta) b(s2; n21(s) + n22(s), theta) CRP(s, s2), where b is the binomial probability.

CRP.total is the conditional size of the final test given the total number of responders, with the responder count of group 1 hypergeometric among all final patients.

Only tests of superiority are covered. With a non-inferiority margin the two response probabilities differ on the boundary of the null hypothesis, and the conditional distributions of the responder counts then depend on them.

Value

An object of class bbssr_crp, a data frame with one row for every pair of pooled responder counts that the design can produce, ordered by s and then by s2, containing:

s

Pooled number of responders at the interim analysis

s2

Pooled number of responders in the second stage

N1

Final sample size of group 1 reached from s

N2

Final sample size of group 2 reached from s

CRP

Rejection probability given s and s2

CRP.total

Rejection probability given only the total number of responders s + s2, when the responder count of group 1 is treated as one hypergeometric count among all N1 + N2 patients

The attribute max is a data frame with the largest value of each of the two probabilities and the first outcome, in the order of the rows, at which it is attained up to rounding error, the attribute exceed gives the number of outcomes at which each of them exceeds alpha, and the attribute reestimation holds the final sample size for every pooled number of interim responders. When theta is supplied, the attribute by.s is a data frame with one row for each value of theta and of s, containing the probability prob.s of s, the type I error rate TIE.s given s and the contribution prob.s * TIE.s of s to the type I error rate, and the attribute TIE gives the type I error rate at each value of theta.

Author(s)

Gosuke Homma ([email protected])

See Also

BinaryTypeIErrorBSSR, BinaryPowerBSSR

Examples

crp <- BinaryCondRejectBSSR(
  Delta.A = 0.3, N1 = 12, N2 = 12, n.interim = c(6, 6), r = 1,
  alpha = 0.025, tar.power = 0.8, Test = 'Chisq', ss.method = 'standard',
  theta = c(0.3, 0.5)
)
print(crp)
attr(crp, 'TIE')


crp <- BinaryCondRejectBSSR(
  Delta.A = 0.3, N1 = 39, N2 = 39, n.interim = c(20, 20), r = 1,
  alpha = 0.025, tar.power = 0.8, Test = 'Chisq', ss.method = 'standard'
)
attr(crp, 'max')
plot(crp)

Description

Evaluates a set of designs with blinded sample size re-estimation (BSSR) for a binary endpoint over a common set of true pooled response probabilities, by calling BinaryPowerBSSR for each design, and returns the results as one data frame with a row for each design and each probability.

Usage

BinaryGridBSSR(design, p, Delta.T = NULL, type1 = FALSE, verbose = FALSE, ...)

Arguments

Details

When design has a column p.plan instead of the initial sample sizes, the planning proportions of the two groups are obtained from the pooled proportion p.plan and the assumed effect Delta.A, as in the re-estimation, and the initial sample sizes are those of BinarySampleSize with the test, the level, the target power and the allocation ratio of the design, the method ss.method of the re-estimation and the rounding rule of the design. The test Test and the level alpha of the final analysis are used even when the re-estimation uses another test ss.Test or level ss.alpha.

The quartiles and P.N.max are those of summary.bbssr_powerbssr. The p-values of each test are kept for the rest of the session, so designs that share sample sizes are evaluated faster after the first one.

Value

An object of class bbssr_grid, a data frame with one row for each design and each element of p that gives response probabilities inside the unit interval, containing the index design of the design, the columns of design (other than the sample sizes and Delta.T), and:

N1, N2

Initial sample sizes

n1.interim, n2.interim

Interim sample sizes

Delta.T

True treatment effect

p, p1, p2

True pooled response probability and those of the two groups

power.BSSR, power.TRAD

Power of the BSSR design and of the fixed-sample design with the initial sample sizes

E.N, SD.N

Expected value and standard deviation of the final total sample size

N.q25, N.q50, N.q75

Quartiles of the final total sample size

P.N.max

Probability that the final total sample size is the largest the design can reach

The attribute designs has one row per design with its index, the columns of design other than the sample sizes and Delta.T, the initial and interim sample sizes and the true effect and, with type1 = TRUE, the largest type I error rates TIE.BSSR and TIE.TRAD and the values theta.BSSR and theta.TRAD at which they occur. When a design tests equivalence, the columns boundary.BSSR and boundary.TRAD give the boundary, 'lower' or 'upper', of each largest rate, and are NA for the other designs. Warnings and errors raised while a design is evaluated are prefixed with the index of the design.

Author(s)

Gosuke Homma ([email protected])

See Also

BinaryPowerBSSR, BinaryTypeIErrorBSSR, BinarySampleSize

Examples

design <- expand.grid(Test = c('Chisq', 'Fisher'), omega = c(0.3, 0.5),
                      stringsAsFactors = FALSE)
grid <- BinaryGridBSSR(design, p = c(0.3, 0.4, 0.5), Delta.A = 0.3, N1 = 30, N2 = 30,
                       r = 1, alpha = 0.025, tar.power = 0.8, ss.method = 'standard')
summary(grid)


plot(grid, colour.by = 'Test', facet.by = 'omega')

# Initial sample sizes from a planning proportion, and the largest type I error rates
design <- data.frame(Delta.A = c(0.2, 0.3), p.plan = 0.4)
grid <- BinaryGridBSSR(design, p = c(0.3, 0.5), omega = 0.5, r = 1, alpha = 0.025,
                       tar.power = 0.8, Test = 'Chisq', ss.method = 'standard',
                       type1 = TRUE)
attr(grid, 'designs')

Description

Calculates the exact power for two-arm trials with binary endpoints. Seven tests are supported (see BinaryRR), each of which can be applied with a one-sided or a two-sided alternative, and two of them also test non-inferiority with a margin on the scale of the risk difference or the risk ratio. Vectors of response probabilities are accepted.

Usage

BinaryPower(
  p1,
  p2,
  N1,
  N2,
  alpha,
  Test,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  tsmethod = c("minlike", "central", "blaker"),
  n.grid = 100,
  bb.gamma = 0,
  margin = 0,
  ref.pvalue = FALSE,
  margin.scale = c("RD", "RR")
)

Arguments

Details

The power is obtained by summing the joint probability mass function of the two independent binomial counts over the rejection region returned by BinaryRR. The summation covers the whole rejection region rather than a row-wise tail, so it remains valid for two-sided tests, whose rejection regions are not contiguous within a row of the outcome grid.

Value

An object of class bbssr_power, a data frame with one row per element of p1 containing:

p1

True probability of responders for group 1

p2

True probability of responders for group 2

N1

Sample size for group 1

N2

Sample size for group 2

alpha

Level of significance

Test

Name of the statistical test

alternative

Direction of the alternative hypothesis

Power

Exact power

Author(s)

Gosuke Homma ([email protected])

Examples

# Power of the one-sided chi-squared test
BinaryPower(p1 = 0.5, p2 = 0.2, N1 = 5, N2 = 5, alpha = 0.025, Test = 'Chisq')


# Power over a range of response probabilities for the two-sided Boschloo test
pw <- BinaryPower(p1 = c(0.5, 0.6, 0.7, 0.8), p2 = rep(0.2, 4),
                  N1 = 20, N2 = 20, alpha = 0.05, Test = 'Boschloo',
                  alternative = 'two.sided')
print(pw)
plot(pw)

Description

Calculates the power of a two-arm trial with a binary endpoint when blinded sample size re-estimation (BSSR) is implemented, together with the power of the corresponding fixed-sample design, the expected final sample size and its distribution. Seven tests are supported (see BinaryRR), each of which can be applied with a one-sided or a two-sided alternative, under either a restricted or an unrestricted design rule.

Usage

BinaryPowerBSSR(
  p,
  Delta.A,
  Delta.T,
  N1,
  N2,
  omega = NULL,
  r,
  alpha,
  tar.power,
  Test,
  restricted = FALSE,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  tsmethod = c("minlike", "central", "blaker"),
  n.grid = 100,
  bb.gamma = 0,
  effect = c("RD", "RR", "OR"),
  ss.method = c("exact", "standard", "null.variance", "alternative.variance"),
  ss.Test = Test,
  ss.alpha = alpha,
  rounding = c("group", "friede-kieser", "total", "nearest"),
  search = c("crossing", "smallest", "stable"),
  search.limit = c(2, 50),
  N.min = NULL,
  N.max = NULL,
  n.interim = NULL,
  margin = 0,
  ref.pvalue = FALSE,
  margin.scale = c("RD", "RR")
)

Arguments

Details

At the interim analysis the pooled number of responders is observed without unblinding. The pooled proportion is combined with the assumed treatment effect Delta.A to recover group-specific proportions, from which the sample size is re-estimated. For the risk difference the recovered proportions are hat.p + Delta.A / (1 + r) and hat.p - r Delta.A / (1 + r). For the risk ratio they are the proportions with the pooled value hat.p and the ratio Delta.A, formula (21.11) of Kieser (2020), and for the odds ratio they are obtained from the quadratic equation that the odds ratio and the pooled value define. The exact search of ss.method = 'exact' uses the recovered proportions truncated to the unit interval. The normal approximation uses them before truncation, with each Bernoulli variance truncated at zero, so that the assumed effect is kept as in formula (2) of Friede and Kieser (2004). The power is then averaged over the distribution of the interim outcome.

Under rounding = 'group', both the interim and the final sample size of group 1 are obtained from the size of group 2 by a single application of ceiling(r ...), so the allocation ratio is preserved as closely as whole numbers allow and is exact whenever r is a whole number. Under rounding = 'friede-kieser', which requires a normal approximation, that is an ss.method other than 'exact', the second stage receives the rounded-up excess of the unrounded re-estimated total over the interim total, split into ceiling(n / (1 + r)) and ceiling(r n / (1 + r)) patients as in Friede and Kieser (2004). Under rounding = 'total' the unrounded total is rounded up and group 2 receives floor(N / (1 + r)) patients. Under rounding = 'nearest' the unrounded total is split in the ratio r to 1 and each group is rounded to the nearest whole number, which reproduces the computations of Friede et al. (2007). In each case the final total is kept between the interim total (or N.min, or the initial total under the restricted rule) and N.max, except that 'friede-kieser' and 'nearest' round the two groups separately and can exceed N.max by one patient. The argument N1 enters only through the fixed-sample comparator and the restricted rule, and under rounding = 'group' a warning is issued when it is not ceiling(r N2).

Recovered proportions that coincide admit no sample size. The risk ratio produces them when no interim patient responds, and the odds ratio when no interim patient or every interim patient responds. The initial sample size is kept for such interim outcomes.

Setting Delta.T to the null value (0 for the risk difference, 1 for a ratio) makes the two groups identical, so power.BSSR and power.TRAD become rejection probabilities under the null hypothesis. BinaryTypeIErrorBSSR evaluates them over the unit interval and locates the maximum.

With a non-inferiority margin, the design of Friede et al. (2007) is obtained. The assumed effect Delta.A is usually 0, which recovers the pooled proportion for both groups, the sample size is re-estimated by the formula of Farrington and Manning (ss.method = 'standard') or of Blackwelder (ss.method = 'alternative.variance'), and Delta.T = -margin (or margin for alternative = 'less') gives the rejection probability on the boundary of the null hypothesis.

With margin.scale = 'RR' the margin is a ratio R0 and the effects are risk ratios (effect = 'RR'). The assumed effect Delta.A must exceed R0 for alternative = 'greater' and fall below it for 'less', and is usually 1. The sample size is re-estimated by formula (8) of Farrington and Manning (1990) (ss.method = 'standard') or by their Method 1 (ss.method = 'alternative.variance'), and Delta.T = R0 gives the rejection probability on the boundary of the null hypothesis. The recovered proportions lie on that boundary only when no interim patient responds, and the initial sample size is kept for this interim outcome.

Value

An object of class bbssr_powerbssr, a data frame with one row per element of p containing:

p1

True probability of responders for group 1

p2

True probability of responders for group 2

p

True pooled probability of responders from both groups

power.BSSR

Power of the BSSR design

power.TRAD

Power of the fixed-sample design

E.N

Expected total sample size of the BSSR design

The interim sample sizes are stored as the attributes n1.interim and n2.interim. The attribute reestimation holds, for every pooled number of interim responders s, the recovered proportions, the final sample sizes and, in the column N2.limit, the limit of search = 'stable' (otherwise NA). The attribute N.dist holds the distribution of the final sample size for every row of the result, identified by the column scenario, and the attribute search the search. summary() reports the standard deviation and quantiles of the final sample size.

Author(s)

Gosuke Homma ([email protected])

References

Friede T, Kieser M (2004). Sample size recalculation for binary data in internal pilot study designs. Pharmaceutical Statistics, 3(4), 269-279.

Kieser M (2020). Methods and Applications of Sample Size Calculation and Recalculation in Clinical Trials. Springer, Cham.

Friede T, Mitchell C, Mueller-Velten G (2007). Blinded sample size reestimation in non-inferiority trials with binary endpoints. Biometrical Journal, 49(6), 903-916.

See Also

BinaryTypeIErrorBSSR, BinaryAlphaAdjBSSR, BinaryBSSR

Examples

# Small BSSR calculation with the chi-squared test
BinaryPowerBSSR(
  p = 0.45,
  Delta.A = 0.3, Delta.T = 0.3,
  N1 = 5, N2 = 5, omega = 0.5, r = 1,
  alpha = 0.025, tar.power = 0.8, Test = 'Chisq'
)


res <- BinaryPowerBSSR(
  p = seq(0.23, 0.47, by = 0.04),
  Delta.A = 0.3, Delta.T = 0.3,
  N1 = 39, N2 = 39, omega = 0.5, r = 1,
  alpha = 0.025, tar.power = 0.8, Test = 'Z-pool'
)
print(res)
summary(res)
plot(res)

# Re-estimation by the normal approximation with an upper bound of twice the
# initial sample size, and a final analysis with the Boschloo test
BinaryPowerBSSR(
  p = seq(0.2, 0.4, by = 0.05),
  Delta.A = 0.3, Delta.T = 0.3,
  N1 = 30, N2 = 30, n.interim = c(15, 15), r = 1,
  alpha = 0.025, tar.power = 0.8, Test = 'Boschloo',
  ss.method = 'standard', N.max = 120
)

# Non-inferiority with a margin of 0.1, as in Friede et al. (2007)
BinaryPowerBSSR(
  p = c(0.5, 0.7), Delta.A = 0, Delta.T = 0,
  N1 = 329, N2 = 329, n.interim = c(66, 66), r = 1,
  alpha = 0.025, tar.power = 0.8, Test = 'Farrington-Manning',
  ss.method = 'standard', rounding = 'nearest', margin = 0.1
)

Description

Provides a rejection region (RR) for two-arm trials with binary endpoints. Seven tests are supported. Each can be applied with a one-sided or a two-sided alternative, and two of them also test non-inferiority with a margin on the scale of the risk difference or the risk ratio.

Usage

BinaryRR(
  N1,
  N2,
  alpha,
  Test,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  tsmethod = c("minlike", "central", "blaker"),
  n.grid = 100,
  bb.gamma = 0,
  margin = 0,
  ref.pvalue = FALSE,
  margin.scale = c("RD", "RR")
)

Arguments

Details

The function supports the following seven tests:

• The Pearson chi-squared test (Chisq)

• The Fisher exact test (Fisher)

• The Fisher mid-p test (Fisher-midP)

• The Z-pooled exact unconditional test (Z-pool)

• The exact unconditional test of Boschloo (1970), which orders the outcomes by the Fisher p-value (Boschloo)

• The test of Blackwelder (1982) with the unpooled standard error (Blackwelder)

• The test of Farrington and Manning (1990) with the standard error at the restricted maximum likelihood estimates (Farrington-Manning)

For the two-sided versions of the conditional tests, 'minlike' sums the null probabilities of all tables that are no more likely than the observed table, which is the convention of stats::fisher.test, and 'central' doubles the smaller of the two one-sided tail probabilities. 'blaker' orders the tables by the smaller of their two one-sided tail probabilities and sums the null probabilities of all tables at which this is no larger than at the observed table, formula (2) of Mehrotra, Chan and Berger (2003). For the exact Fisher p-value this is the convention 'blaker' of the exact2x2 package. The exact Fisher p-value of 'blaker' never exceeds that of 'central', but its mid-p value and its Boschloo p-value can. When the two groups are of equal size the conditional distribution is symmetric, so the three conventions give the same exact Fisher p-value and hence the same Boschloo p-value, and 'minlike' and 'blaker' also give the same mid-p value. Under the mid-p correction the tables tied with the observed table in the ordering of 'minlike' or 'blaker', the observed table included, contribute half of their probability, following the definition of the mid-p value in Fay and Hunsberger (2021, Section 9). The two-sided versions of 'Chisq' and 'Z-pool' order the outcomes by the absolute value of the Z statistic.

The unconditional tests maximize the null tail probability of an ordering statistic over the common response probability, which is a nuisance parameter. Outcomes sharing the same value of the ordering statistic receive the same p-value. With a positive bb.gamma the maximization is restricted to a confidence interval for the nuisance parameter and bb.gamma is added, following Berger and Boos (1994).

The tail probability of each outcome is a polynomial in the common response probability, and its maximum over the grid of n.grid points is a lower bound of the maximum over the unit interval. A p-value computed on the grid can therefore fall below the exact p-value, and the test can then exceed its nominal level. With ref.pvalue = TRUE the grid is extended by points equally spaced on the arcsine square-root scale, which resolve the narrow local maxima near 0 and 1, and every local maximum on the extended grid is refined by a safeguarded Newton iteration between its two neighbouring grid points. The grid maximum is kept when it is larger, so a refined p-value is never smaller than the p-value on the grid. In the designs examined during development the refined p-values agreed with a certified maximum over the unit interval to within 1e-12, but the refinement is a local search and does not guarantee the maximum. It takes longer than the grid alone, by roughly an order of magnitude with 500 patients per group.

The alternative 'less' is handled by exchanging the two groups, testing the alternative 'greater' and exchanging them back. Every test considered treats the groups symmetrically apart from the direction of the alternative, so this gives the lower-tail version of each test.

The tests of Blackwelder and of Farrington and Manning refer the statistic z = (hat.p1 - hat.p2 + margin) / SE to the standard normal distribution, which tests the null hypothesis p1 - p2 <= -margin for alternative = 'greater'. The standard error of the Blackwelder test uses the observed proportions. That of the Farrington-Manning test uses the maximum likelihood estimates under p1 - p2 = -margin, formula (12) of Farrington and Manning (1990). With margin = 0 the Farrington-Manning test coincides with 'Chisq' and the Blackwelder test is the Wald test. A standard error of 0, which arises only when both observed proportions are 0 or 1, gives z = Inf or -Inf according to the sign of the numerator, and z = 0 when the numerator is 0 as well. These tests are asymptotic, and their rejection regions and power are computed exactly, as for the other tests. A margin other than 0 is available only with these two tests and a one-sided alternative.

With margin.scale = 'RR' the margin is a ratio R0, and both tests refer the statistic z = (hat.p1 - R0 hat.p2) / SE of Farrington and Manning (1990) to the standard normal distribution, which tests the null hypothesis p1 / p2 <= R0 for alternative = 'greater'. The squared standard error is p1 (1 - p1) / N1 + R0^2 p2 (1 - p2) / N2. The Blackwelder test evaluates it at the observed proportions, which is Method 1 of Farrington and Manning (1990), and the Farrington-Manning test at the maximum likelihood estimates under p1 = R0 p2, formula (13) of that article. For alternative = 'less' the groups are exchanged as for the other tests, with the ratio 1 / R0, which changes only the sign of the statistic. A margin on the scale of the risk ratio is also available only with these two tests and a one-sided alternative.

With alternative = 'equivalence' the null hypothesis p1 - p2 <= -lower or p1 - p2 >= upper (p1 / p2 <= lower or p1 / p2 >= upper on the scale of the risk ratio) is tested by two one-sided tests of the same kind, the test against 'greater' with the margin lower and the test against 'less' with the margin upper, each at the level alpha. The null hypothesis is rejected when both reject, so the rejection region is the intersection of the two one-sided regions and the p-value of an outcome is the larger of its two one-sided p-values. Tests of equivalence are available with the tests of Blackwelder and of Farrington and Manning.

The p-values are kept for the rest of the session and reused by later calls with the same sample sizes and test, see bbssr-package. They form a matrix of (N1 + 1) (N2 + 1) values, which takes about 2 GB of memory for 16,000 patients per group, so the memory and the time of the exact calculations grow with the product of the group sizes.

Value

An object of class bbssr_rr, which is a logical matrix of dimension (N1 + 1) by (N2 + 1) whose entry [i + 1, j + 1] is TRUE when the null hypothesis is rejected at i responders in group 1 and j responders in group 2. The design settings are stored as attributes

Author(s)

Gosuke Homma ([email protected])

References

Berger RL, Boos DD (1994). P values maximized over a confidence set for the nuisance parameter. Journal of the American Statistical Association, 89(427), 1012-1016.

Blackwelder WC (1982). "Proving the null hypothesis" in clinical trials. Controlled Clinical Trials, 3(4), 345-353.

Boschloo RD (1970). Raised conditional level of significance for the 2 x 2-table when testing the equality of two probabilities. Statistica Neerlandica, 24(1), 1-9.

Farrington CP, Manning G (1990). Test statistics and sample size formulae for comparative binomial trials with null hypothesis of non-zero risk difference or non-unity relative risk. Statistics in Medicine, 9(12), 1447-1454.

Fay MP, Hunsberger SA (2021). Practical valid inferences for the two-sample binomial problem. Statistics Surveys, 15, 72-110.

Mehrotra DV, Chan ISF, Berger RL (2003). A cautionary note on exact unconditional inference for a difference between two independent binomial proportions. Biometrics, 59(2), 441-450.

Examples

# Simple example with small sample sizes
RR <- BinaryRR(N1 = 5, N2 = 5, alpha = 0.025, Test = 'Chisq')
print(RR)


# Two-sided Boschloo test with the Berger-Boos procedure
RR <- BinaryRR(N1 = 20, N2 = 10, alpha = 0.05, Test = 'Boschloo',
               alternative = 'two.sided', bb.gamma = 0.0001)
print(RR)
plot(RR)

# The grid maximum can understate the p-value. Refinement removes two outcomes from the
# rejection region of the Z-pooled test with 32 patients per group
RR.grid <- BinaryRR(N1 = 32, N2 = 32, alpha = 0.025, Test = 'Z-pool')
RR.ref <- BinaryRR(N1 = 32, N2 = 32, alpha = 0.025, Test = 'Z-pool', ref.pvalue = TRUE)
sum(RR.grid) - sum(RR.ref)

# Non-inferiority with a margin of 0.1 by the test of Farrington and Manning
RR <- BinaryRR(N1 = 60, N2 = 60, alpha = 0.025, Test = 'Farrington-Manning',
               margin = 0.1)
print(RR)

# Non-inferiority with the margin 0.8 on the scale of the risk ratio
RR <- BinaryRR(N1 = 60, N2 = 60, alpha = 0.025, Test = 'Farrington-Manning',
               margin = 0.8, margin.scale = 'RR')
print(RR)

# Equivalence with the margins -0.15 and 0.15 of the risk difference
RR <- BinaryRR(N1 = 100, N2 = 100, alpha = 0.05, Test = 'Farrington-Manning',
               alternative = 'equivalence', margin = c(0.15, 0.15))
print(RR)

Description

Calculates the required sample size for two-arm trials with binary endpoints. Seven tests are supported (see BinaryRR), each of which can be applied with a one-sided or a two-sided alternative. The Blackwelder and Farrington-Manning tests also allow a non-inferiority margin and a test of equivalence. The sample size can be obtained from the exact power of the selected test or from the normal approximation.

Usage

BinarySampleSize(
  p1,
  p2,
  r,
  alpha,
  tar.power,
  Test,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  tsmethod = c("minlike", "central", "blaker"),
  n.grid = 100,
  bb.gamma = 0,
  method = c("exact", "standard", "null.variance", "alternative.variance"),
  rounding = c("group", "friede-kieser", "total", "nearest"),
  search = c("crossing", "smallest", "stable"),
  search.limit = c(2, 50),
  margin = 0,
  ref.pvalue = FALSE,
  margin.scale = c("RD", "RR")
)

Arguments

Details

With the default search = 'crossing' the calculation uses a three-step approach:

1. Calculate an initial sample size from the normal approximation to the chi-squared test

2. Evaluate the exact power at the initial sample size

3. If the exact power attains the target power, lower the size of group 2 one unit at a time as long as the power still attains it; otherwise raise it one unit at a time until the power attains it

The normal approximation of the first step uses alpha for a one-sided alternative, alpha / 2 for a two-sided alternative, and alpha for each of the two one-sided tests of equivalence. Only the starting value of the search is affected, so the returned sample size is exact in every case.

The search stops where the exact power crosses the target: the returned size of group 2 attains the target power and the size one unit smaller does not, unless the returned size is 1. The exact power is not monotone in the sample size, so a smaller size further from the normal approximation may also attain the target power, and a larger size may fall short of it.

The two other searches do not depend on where the normal approximation starts. search = 'smallest' scans the size of group 2 upwards from 1 and returns the first size that attains the target power. It visits every smaller size, which takes longer for the unconditional tests. search = 'stable' scans downwards from the limit given by search.limit and returns the smallest size from which every size up to the limit attains the target power, so that adding patients within this range does not take the power below the target. The search stops with an error if the limit itself falls short of the target power. The three searches can return different sizes because the exact power is not monotone in the sample size.

Under method = 'standard', 'null.variance' or 'alternative.variance' the steps above are replaced by the closed-form normal approximation and the rounding rule selected by rounding. The Power column still reports the exact power of Test at the resulting sample size.

With a non-zero margin, the difference p1 - p2 in the normal approximation is replaced by its distance p1 - p2 + margin from the boundary of the null hypothesis, and the variance under the null hypothesis is evaluated at the large sample values of the restricted maximum likelihood estimates of Farrington and Manning (1990). The method 'standard' then gives formula (4) of Farrington and Manning (1990), which is formula (2) of Friede et al. (2007), and 'alternative.variance' gives the formula of Blackwelder (1982), which is formula (1) of Friede et al. (2007). The exact search starts from the formula of Farrington and Manning.

With margin.scale = 'RR' and the ratio R0 = margin, the difference in the normal approximation is the distance p1 - R0 p2, or R0 p2 - p1 for alternative = 'less', and the variance of the size of group 2 is p1 (1 - p1) / r + R0^2 p2 (1 - p2), evaluated at the large sample values of the restricted maximum likelihood estimates under p1 = R0 p2 for the significance term. The method 'standard' then gives formula (8) of Farrington and Manning (1990), 'alternative.variance' gives the formula of their Method 1, and the exact search starts from formula (8).

For alternative = 'equivalence' the approximate power of each one-sided test is obtained as above for its own margin, at the level alpha, and the sample size of the normal approximation is the smallest unrounded size of group 2 at which the sum of the two approximate powers minus 1 attains the target power. The sum minus 1 is a lower bound of the approximate probability that both tests reject. The exact search starts from this size.

Value

An object of class bbssr_samplesize, a data frame with one row containing:

p1

True probability of responders for group 1

p2

True probability of responders for group 2

r

Allocation ratio to group 1

alpha

Level of significance

tar.power

Target power

Test

Name of the statistical test

alternative

Direction of the alternative hypothesis

Power

Exact power of Test at the selected sample size

N1

Required sample size of group 1

N2

Required sample size of group 2

N

Total required sample size

The attribute search holds the search, and the attribute search.limit the limit of the size of group 2 examined by search = 'stable' (otherwise NA).

Author(s)

Gosuke Homma ([email protected])

References

Friede T, Kieser M (2004). Sample size recalculation for binary data in internal pilot study designs. Pharmaceutical Statistics, 3(4), 269-279.

Kieser M (2020). Methods and Applications of Sample Size Calculation and Recalculation in Clinical Trials. Springer, Cham.

Blackwelder WC (1982). "Proving the null hypothesis" in clinical trials. Controlled Clinical Trials, 3(4), 345-353.

Farrington CP, Manning G (1990). Test statistics and sample size formulae for comparative binomial trials with null hypothesis of non-zero risk difference or non-unity relative risk. Statistics in Medicine, 9(12), 1447-1454.

Friede T, Mitchell C, Mueller-Velten G (2007). Blinded sample size reestimation in non-inferiority trials with binary endpoints. Biometrical Journal, 49(6), 903-916.

Examples

# One-sided chi-squared test
BinarySampleSize(p1 = 0.4, p2 = 0.2, r = 1, alpha = 0.025,
                 tar.power = 0.8, Test = 'Chisq')


# Two-sided Fisher exact test
BinarySampleSize(p1 = 0.5, p2 = 0.2, r = 2, alpha = 0.05,
                 tar.power = 0.9, Test = 'Fisher', alternative = 'two.sided')

# Normal approximation with the variance under the null hypothesis, two-sided test
# at level 0.05, as in Friede and Kieser (2004)
BinarySampleSize(p1 = 0.4, p2 = 0.2, r = 1, alpha = 0.05, tar.power = 0.8,
                 Test = 'Chisq', alternative = 'two.sided',
                 method = 'null.variance')

# Non-inferiority with a margin of 0.1, formula (2) of Friede et al. (2007)
BinarySampleSize(p1 = 0.7, p2 = 0.7, r = 1, alpha = 0.025, tar.power = 0.8,
                 Test = 'Farrington-Manning', method = 'standard',
                 rounding = 'friede-kieser', margin = 0.1)

# Non-inferiority on the scale of the risk ratio: the null hypothesis p1 / p2 <= 0.8
# with equal response probabilities of 0.6
BinarySampleSize(p1 = 0.6, p2 = 0.6, r = 1, alpha = 0.025, tar.power = 0.8,
                 Test = 'Farrington-Manning', margin = 0.8, margin.scale = 'RR')

Description

Evaluates the type I error rate of a two-arm trial with a binary endpoint and blinded sample size re-estimation (BSSR) over the common response probability, or over the pooled response probability on the boundary of a non-inferiority hypothesis, together with that of the corresponding fixed-sample design, and locates the largest value of each.

Usage

BinaryTypeIErrorBSSR(
  Delta.A,
  N1,
  N2,
  omega = NULL,
  r,
  alpha,
  tar.power,
  Test,
  restricted = FALSE,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  tsmethod = c("minlike", "central", "blaker"),
  n.grid = 100,
  bb.gamma = 0,
  effect = c("RD", "RR", "OR"),
  ss.method = c("exact", "standard", "null.variance", "alternative.variance"),
  ss.Test = Test,
  ss.alpha = alpha,
  rounding = c("group", "friede-kieser", "total", "nearest"),
  search = c("crossing", "smallest", "stable"),
  search.limit = c(2, 50),
  N.min = NULL,
  N.max = NULL,
  n.interim = NULL,
  theta = seq(0, 1, by = 0.005),
  maximize = c("certified", "refined", "grid"),
  margin = 0,
  ref.pvalue = FALSE,
  margin.scale = c("RD", "RR")
)

Arguments

Details

Under the null hypothesis both groups share the response probability theta. The sample size is re-estimated exactly as in BinaryPowerBSSR, from the assumed effect Delta.A, and the rejection probability is summed over every interim outcome and every outcome of the second stage.

The type I error rate is a polynomial in theta, since both response probabilities are linear in theta. With maximize = 'certified' the polynomial is expressed in the Bernstein basis over the interval from the smallest to the largest value of theta, restricted with a margin to the values at which both response probabilities lie in the unit interval. The basis polynomials are non-negative and sum to one, so on any subinterval the polynomial does not exceed its largest Bernstein coefficient there, and its first and last coefficients are its values at the two ends. The interval is halved repeatedly by the algorithm of de Casteljau, and a subinterval is set aside once its largest coefficient exceeds the largest value found by at most 1e-12. The largest coefficient of the subintervals set aside, reported as bound, is an upper bound of the type I error rate at every value of theta in the interval, up to rounding error, and TIE is within 1e-12 of it. If 1e5 subdivisions do not suffice, a warning is given; bound remains an upper bound, but TIE can then be more than 1e-12 below it. With maximize = 'refined' the three largest local maxima on the grid are refined, which usually finds the maximum when the grid is fine compared with the spacing of the local maxima but does not guarantee it, and with maximize = 'grid' the largest value on the grid is reported.

With a non-inferiority margin the null hypothesis is p1 - p2 <= -margin, or p1 - p2 >= margin for alternative = 'less', and the type I error rate is evaluated on its boundary, as in Friede et al. (2007). The boundary is parametrized by the pooled response probability theta, and the values of theta at which a response probability falls outside the unit interval are dropped. With margin.scale = 'RR' the null hypothesis is p1 / p2 <= margin, or p1 / p2 >= margin for alternative = 'less', and its boundary p1 = margin p2 is parametrized in the same way, with p2 = (1 + r) theta / (1 + r margin). Both response probabilities are again linear in theta, so the certified maximum applies on either scale.

Value

An object of class bbssr_tie, a data frame with one row per element of theta containing:

theta

Common response probability of the two groups, or the pooled response probability on the null boundary

p1

Response probability of group 1

p2

Response probability of group 2

TIE.BSSR

Type I error rate of the BSSR design

TIE.TRAD

Type I error rate of the fixed-sample design with sample sizes N1 and N2

The attribute max is a data frame with one row for each design, 'BSSR' and 'TRAD' in the column Design, holding the largest type I error rate TIE, the common response probability, or pooled response probability on the null boundary, theta at which it occurs and, with maximize = 'certified', the upper bound bound of the type I error rate over the interval given by the attribute interval (otherwise NA). The attribute reestimation holds the final sample size for every pooled number of interim responders.

For alternative = 'equivalence' the null hypothesis has two boundaries, the lower one p1 - p2 = -lower (p1 = lower p2 on the scale of the risk ratio) and the upper one p1 - p2 = upper (p1 = upper p2). The data frame then has a first column boundary, 'lower' or 'upper', and a row for each element of theta on each boundary. The rejection probability is that of the two one-sided tests together. The largest rate of each design in the attribute max is the larger of its maxima on the two boundaries, its bound the larger of the two bounds, and the column boundary of the attribute gives the boundary on which it occurs. The attribute interval is then a matrix with a row for each boundary.

Author(s)

Gosuke Homma ([email protected])

References

Friede T, Kieser M (2004). Sample size recalculation for binary data in internal pilot study designs. Pharmaceutical Statistics, 3(4), 269-279.

Kieser M (2020). Methods and Applications of Sample Size Calculation and Recalculation in Clinical Trials. Springer, Cham.

Friede T, Mitchell C, Mueller-Velten G (2007). Blinded sample size reestimation in non-inferiority trials with binary endpoints. Biometrical Journal, 49(6), 903-916.

See Also

BinaryAlphaAdjBSSR, BinaryPowerBSSR

Examples

tie <- BinaryTypeIErrorBSSR(
  Delta.A = 0.3, N1 = 20, N2 = 20, omega = 0.5, r = 1,
  alpha = 0.025, tar.power = 0.8, Test = 'Chisq', ss.method = 'standard',
  theta = seq(0.05, 0.95, by = 0.05)
)
print(tie)


tie <- BinaryTypeIErrorBSSR(
  Delta.A = 0.3, N1 = 39, N2 = 39, n.interim = c(20, 20), r = 1,
  alpha = 0.025, tar.power = 0.8, Test = 'Boschloo'
)
attr(tie, 'max')
plot(tie)

Description

Lowers the nominal significance level of a matched-pairs design with blinded sample size re-estimation until the largest type I error rate over the probability of a discordant pair on the boundary of the null hypothesis does not exceed the target level alpha, and returns the adjusted level together with that of the fixed design.

Usage

PairedAlphaAdjBSSR(
  Delta.A,
  N,
  omega = NULL,
  alpha,
  tar.power,
  Test,
  restricted = FALSE,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  n.grid = 100,
  bb.gamma = 0,
  ss.method = c("exact", "standard", "conditional.power"),
  ss.Test = Test,
  ss.alpha = alpha,
  search = c("crossing", "smallest", "stable"),
  search.limit = c(2, 50),
  N.min = NULL,
  N.max = NULL,
  n.interim = NULL,
  psi = seq(0, 1, by = 0.01),
  maximize = c("certified", "refined", "grid"),
  adjust = c("test", "both"),
  tol = 1e-08,
  step = 1e-05,
  margin = 0,
  ref.pvalue = FALSE
)

Arguments

Details

The searches are those of BinaryAlphaAdjBSSR. With adjust = 'test' the final numbers of pairs do not depend on the nominal level of the final analysis, the largest type I error rate is a non-decreasing function of the level, and the level is found by bisection to within tol * alpha; the reported level is the largest value with at most six significant digits that gives the same rejection regions. With adjust = 'both' the level is lowered from alpha in steps of step until the type I error rate is controlled. The fixed design always uses the bisection. With maximize = 'certified' a level is accepted only when the upper bound of the type I error rate over the interval, computed as in PairedTypeIErrorBSSR, does not exceed alpha.

The exact conditional McNemar test keeps its level whatever blinded rule is used (Schepers et al., 2026), so it needs no adjustment.

Value

An object of class bbssr_alphaadj, a data frame with one row for the BSSR design and one for the fixed design containing:

Design

'BSSR' or 'TRAD'

alpha

Target level

max.TIE

Largest type I error rate at the nominal level alpha

alpha.adj

Adjusted nominal level. It is alpha when the nominal level already controls the type I error rate, and 0, with a warning, when no level examined by the bisection does. The search of adjust = 'both' for the BSSR design stops with an error instead when it reaches 0

max.TIE.adj

Largest type I error rate at the adjusted level

psi.adj

Probability of a discordant pair at which max.TIE.adj occurs, NA when alpha.adj is 0

max.TIE.bound

Upper bound of the type I error rate at the nominal level with maximize = 'certified', otherwise NA

max.TIE.adj.bound

Upper bound of the type I error rate at the adjusted level with maximize = 'certified', otherwise NA

For alternative = 'equivalence' the column boundary.adj gives the boundary, 'lower' or 'upper', on which max.TIE.adj occurs.

References

Kieser M, Friede T (2000). Re-calculating the sample size in internal pilot study designs with control of the type I error rate. Statistics in Medicine, 19(7), 901-911.

Schepers M, Brannath W, Hoffmann E, Stingl J, Schmidtmann I (2026). Blinded sample size review for McNemar's test based on primary and surrogate endpoints. arXiv:2608.17784.

Examples

PairedAlphaAdjBSSR(Delta.A = 0.2, N = 40, n.interim = 20, alpha = 0.05,
                   tar.power = 0.8, Test = 'McNemar', alternative = 'two.sided',
                   ss.method = 'standard', psi = seq(0.05, 0.95, by = 0.05))

Description

Re-estimates the number of pairs of a matched-pairs trial from the number of discordant pairs observed at an interim analysis, without the direction in which they are discordant.

Usage

PairedBSSR(
  n1,
  D1,
  Delta.A,
  alpha,
  tar.power,
  Test,
  restricted = FALSE,
  N = NULL,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  n.grid = 100,
  bb.gamma = 0,
  ss.method = c("exact", "standard", "conditional.power"),
  ss.Test = Test,
  ss.alpha = alpha,
  search = c("crossing", "smallest", "stable"),
  search.limit = c(2, 50),
  N.min = NULL,
  N.max = NULL,
  margin = 0,
  ref.pvalue = FALSE
)

Arguments

Details

The re-estimation is that of PairedPowerBSSR: the blinded estimate D1 / n1 of the probability of a discordant pair, raised to |Delta.A| when it is smaller, and the assumed difference Delta.A give the planning probabilities, from which the number of pairs follows by the rule ss.method. The conditional power is sum over D2 of b(D2; N.final - n1, psi.plan) g(D1 + D2), the probability of rejection given D1 under the planning probabilities, formula (4) of Schepers et al. (2026) for the exact conditional McNemar test.

Value

An object of class bbssr_pbssr, a data frame with one row containing the interim data n1 and D1, the blinded estimate psi.hat of the probability of a discordant pair, the value psi.plan used in the re-estimation, the planning probabilities p10.plan and p01.plan, the re-estimated number of pairs N.re before the bounds are applied (at most N.max with ss.method = 'exact', whose search does not go beyond it, and within the bounds with ss.method = 'conditional.power'), the number n.stage2 of pairs still to be enrolled, the final number of pairs N.final, the power Power of the final analysis with N.final pairs under the planning probabilities, and its conditional power CP given D1, computed with ss.Test at the level ss.alpha. The attributes hold the design settings.

References

Schepers M, Brannath W, Hoffmann E, Stingl J, Schmidtmann I (2026). Blinded sample size review for McNemar's test based on primary and surrogate endpoints. arXiv:2608.17784.

Examples

# 25 interim pairs of which 5 are discordant, assumed difference 0.15
PairedBSSR(n1 = 25, D1 = 5, Delta.A = 0.15, alpha = 0.05, tar.power = 0.8,
           Test = 'McNemar-exact', alternative = 'two.sided',
           ss.method = 'conditional.power', N.max = 150)

Description

Calculates the exact power of a test comparing two treatments on a binary endpoint in a matched-pairs design, for given probabilities of the two kinds of discordant pairs.

Usage

PairedPower(
  p10,
  p01,
  N,
  alpha,
  Test,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  n.grid = 100,
  bb.gamma = 0,
  margin = 0,
  ref.pvalue = FALSE
)

Arguments

Details

The numbers of the two kinds of discordant pairs and of concordant pairs follow the multinomial distribution with N trials and probabilities p10, p01 and 1 - p10 - p01, and the power is the probability of the rejection region of PairedRR under this distribution, computed by complete enumeration. The probabilities of the concordant pairs with both and with neither treatment responding do not enter, since no test depends on how the concordant pairs split.

Value

An object of class bbssr_ppower, a data frame with one row for each element of p10, containing:

p10, p01

Probabilities of the two kinds of discordant pairs

N

Number of pairs

alpha

Level of significance

Test

Name of the statistical test

alternative

Direction of the alternative hypothesis

Power

Exact power

The attribute margin holds the margin.

Examples

# Average exact power of the asymptotic McNemar test with 25 pairs over the alternatives
# of Berger and Sidik (2003, Section 5.1)
alt <- do.call(rbind, lapply(seq(0.025, 0.475, by = 0.05), function(q) {
  data.frame(p01 = q, p10 = seq(q + 0.05, 1 - q, by = 0.05))
}))
pw <- PairedPower(alt$p10, alt$p01, N = 25, alpha = 0.05, Test = 'McNemar')
mean(pw$Power)

Description

Calculates the exact power and the distribution of the final number of pairs of a matched-pairs design with blinded sample size re-estimation, together with the power of the fixed design with the planned number of pairs. The number of pairs is re-estimated at an interim analysis from the number of discordant pairs, without the direction in which they are discordant, and the final analysis uses all pairs.

Usage

PairedPowerBSSR(
  psi,
  Delta.T,
  Delta.A,
  N,
  omega = NULL,
  alpha,
  tar.power,
  Test,
  restricted = FALSE,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  n.grid = 100,
  bb.gamma = 0,
  ss.method = c("exact", "standard", "conditional.power"),
  ss.Test = Test,
  ss.alpha = alpha,
  search = c("crossing", "smallest", "stable"),
  search.limit = c(2, 50),
  N.min = NULL,
  N.max = NULL,
  n.interim = NULL,
  margin = 0,
  ref.pvalue = FALSE
)

Arguments

Details

Among the n1 pairs of the interim analysis, the number D1 of discordant pairs is binomial with n1 trials and probability psi, and the blinded estimate of psi is D1 / n1. The assumed difference Delta.A is kept, and the estimate is raised to |Delta.A| when it is smaller, since psi >= |p10 - p01|. The planning probabilities are then p10 = (psi.plan + Delta.A) / 2 and p01 = (psi.plan - Delta.A) / 2, as in Xu and Yu (2013) and Schepers et al. (2026).

The final number of pairs depends on the interim data only through D1. Given the numbers of discordant pairs of the two stages, the number of pairs in which only treatment 1 responds is binomial with the total number of discordant pairs and probability p10 / psi, whatever the re-estimation did. The power is therefore sum over D1 and D2 of b(D1; n1, psi) b(D2; N(D1) - n1, psi) g(D1 + D2), where g(D) is the probability that the final analysis with N(D1) pairs rejects given D discordant pairs. It is computed exactly by enumeration.

With ss.method = 'conditional.power' the final number of pairs is the smallest number N between the bounds at which sum over D2 of b(D2; N - n1, psi.plan) g_N(D1 + D2), computed with the planning probabilities and the test ss.Test at the level ss.alpha, attains tar.power. With the exact conditional McNemar test this is the conditional power (4) of Schepers et al. (2026), which they evaluate with p* = 0.5 + Delta / (2 psi) at the blinded estimate of psi. When no number up to N.max attains the target, N.max is used, a choice the article leaves open.

The exact conditional McNemar test keeps its level whatever blinded rule is used, since the number of pairs in which only treatment 1 responds stays binomial given the total number of discordant pairs (Schepers et al., 2026). The other tests can exceed their nominal level after re-estimation, see PairedTypeIErrorBSSR.

Value

An object of class bbssr_ppowerbssr, a data frame with one row for each element of psi that gives probabilities p10 and p01 in [0, 1], containing:

psi, p10, p01

True probabilities of a discordant pair and of its two kinds

power.BSSR

Power of the design with re-estimation

power.TRAD

Power of the fixed design with N pairs

E.N

Expected final number of pairs

The attribute reestimation holds the final number of pairs for every interim number of discordant pairs, N.dist the distribution of the final number of pairs in each scenario, and the other attributes the design settings.

References

Schepers M, Brannath W, Hoffmann E, Stingl J, Schmidtmann I (2026). Blinded sample size review for McNemar's test based on primary and surrogate endpoints. arXiv:2608.17784.

Xu J, Yu M (2013). Sample size determination and re-estimation for matched pair designs with multiple binary endpoints. Biometrical Journal, 55(3), 430-443.

Examples

res <- PairedPowerBSSR(psi = c(0.15, 0.2, 0.3), Delta.T = 0.15, Delta.A = 0.15, N = 72,
                       n.interim = 30, alpha = 0.05, tar.power = 0.8,
                       Test = 'McNemar-exact', alternative = 'two.sided',
                       ss.method = 'standard')
print(res)


# Conditional power rule of Schepers et al. (2026) with at most 150 pairs
res <- PairedPowerBSSR(psi = c(0.15, 0.2, 0.3), Delta.T = 0.15, Delta.A = 0.15, N = 72,
                       n.interim = 30, alpha = 0.05, tar.power = 0.8,
                       Test = 'McNemar-exact', alternative = 'two.sided',
                       ss.method = 'conditional.power', N.max = 150)
print(res)

Description

Provides the rejection region of a test comparing two treatments on a binary endpoint in a matched-pairs design, such as a cross-over trial or a comparison of two diagnostic procedures on the same patients. Six tests are supported. Each can be applied with a one-sided or a two-sided alternative, and the score test also tests non-inferiority and equivalence with a margin on the scale of the difference of the response probabilities.

Usage

PairedRR(
  N,
  alpha,
  Test,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  n.grid = 100,
  bb.gamma = 0,
  margin = 0,
  ref.pvalue = FALSE
)

Arguments

Details

A pair contributes one of four outcomes: both treatments respond, only treatment 1 responds (probability p10), only treatment 2 responds (probability p01), or neither responds. The difference of the response probabilities of the two treatments is p10 - p01, and only the numbers a and b of the two kinds of discordant pairs enter the tests. The function supports the following tests:

• The asymptotic McNemar test (McNemar), which refers Z = (a - b) / sqrt(a + b) to the standard normal distribution without a continuity correction, with Z = 0 when a + b = 0

• The asymptotic McNemar test with a continuity correction (McNemar-cc), formula (2) of Fagerland et al. (2013), which refers (|a - b| - 1) / sqrt(a + b) to the standard normal distribution, and (a - b - 1) / sqrt(a + b) for the alternative 'greater', with the p-value 1 when a + b = 0

• The exact conditional McNemar test (McNemar-exact), which refers a to the binomial distribution with a + b trials and probability 1/2

• The mid-p version of the exact conditional test (McNemar-midP), formulae (5) and (6) of Fagerland et al. (2013)

• The exact unconditional test of Suissa and Shuster (1991) (McNemar-uncond), which orders the outcomes by Z and maximizes the null tail probability over the probability psi = p10 + p01 of a discordant pair, the test Z of Berger and Sidik (2003)

• The score test of Nam (1997) and Tango (1998) for the null hypothesis p10 - p01 = -margin (Paired-Score), which refers (a - b + N margin) / sqrt(N (2 q01 - margin (margin + 1))) to the standard normal distribution, where q01 is the maximum likelihood estimate of p01 under the null hypothesis, formulae (24) to (26) of Tango (1998). With margin = 0 it is the asymptotic McNemar test

The conditional distribution of a given a + b is symmetric under the null hypothesis, so the usual conventions for the two-sided p-value of a conditional test agree. The two-sided p-value of the exact conditional test is twice the smaller tail probability, at most 1, and the two-sided mid-p value follows formulae (5) and (6) of Fagerland et al. (2013). The two-sided versions of 'McNemar', 'McNemar-uncond' and 'Paired-Score' order the outcomes by the absolute value of the statistic. The two-sided p-value of 'McNemar-cc' is twice the smaller of its two one-sided p-values, at most 1, which is the p-value of stats::mcnemar.test with correct = TRUE. Its one-sided p-value is the normal approximation with a continuity correction to the tail probability of the exact conditional test, and Fagerland et al. (2013) set the p-value to 1 when a + b = 0, where the statistic is not defined.

The test 'McNemar-uncond' maximizes the tail probability of each outcome, a polynomial of degree N in psi, over a grid of n.grid points. The maximum on the grid can fall below the maximum over the unit interval. With ref.pvalue = TRUE the grid is extended by points equally spaced on the arcsine square-root scale and every local maximum on the grid is refined by a golden-section search between its two neighbouring grid points, as in BinaryRR. With a positive bb.gamma the maximization is restricted to the Clopper-Pearson interval of level 1 - bb.gamma for psi computed from a + b, and bb.gamma is added, the confidence interval p-value of Berger and Sidik (2003).

The alternative 'less' is handled by exchanging a and b. With alternative = 'equivalence' the null hypothesis is tested by two one-sided score tests, against 'greater' with the margin lower and against 'less' with the margin upper, each at the level alpha, and the p-value of an outcome is the larger of the two one-sided p-values.

The p-values are kept for the rest of the session and reused by later calls with the same number of pairs and test, see bbssr-package. They form a matrix of (N + 1)^2 values, which takes about 2 GB of memory for 16,000 pairs, so the memory and the time of the exact calculations grow with the square of N.

Value

An object of class bbssr_prr, a logical matrix of dimension (N + 1) by (N + 1) whose entry [a + 1, b + 1] is TRUE when the null hypothesis is rejected with a pairs in which only treatment 1 responds and b pairs in which only treatment 2 responds. Entries with a + b > N are impossible outcomes and are FALSE. The p-values are stored in the attribute p.value, with NA at the impossible outcomes, and the design settings as further attributes

References

Berger RL, Sidik K (2003). Exact unconditional tests for a 2 x 2 matched-pairs design. Statistical Methods in Medical Research, 12(2), 91-108.

Fagerland MW, Lydersen S, Laake P (2013). The McNemar test for binary matched-pairs data: mid-p and asymptotic are better than exact conditional. BMC Medical Research Methodology, 13, 91.

Nam J (1997). Establishing equivalence of two treatments and sample size requirements in matched-pairs design. Biometrics, 53(4), 1422-1430.

Suissa S, Shuster JJ (1991). The 2 x 2 matched-pairs trial: exact unconditional design and analysis. Biometrics, 47(2), 361-372.

Tango T (1998). Equivalence test and confidence interval for the difference in proportions for the paired-sample design. Statistics in Medicine, 17(8), 891-908.

Examples

RR <- PairedRR(N = 20, alpha = 0.025, Test = 'McNemar-exact')
print(RR)

# Non-inferiority with a margin of 0.1 by the score test
RR <- PairedRR(N = 44, alpha = 0.05, Test = 'Paired-Score', margin = 0.1)
sum(RR)


# Exact unconditional test with the Berger-Boos procedure
RR <- PairedRR(N = 30, alpha = 0.05, Test = 'McNemar-uncond', bb.gamma = 0.0005)
plot(RR)

Description

Calculates the number of pairs required for a test comparing two treatments on a binary endpoint in a matched-pairs design to attain a target power. The number can be obtained from the exact power of the selected test or from the normal approximation.

Usage

PairedSampleSize(
  p10,
  p01,
  alpha,
  tar.power,
  Test,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  n.grid = 100,
  bb.gamma = 0,
  method = c("exact", "standard"),
  search = c("crossing", "smallest", "stable"),
  search.limit = c(2, 50),
  margin = 0,
  ref.pvalue = FALSE
)

Arguments

Details

The normal approximation is formula (9) of Nam (1997), n = (z.a sqrt(v0) + z.b sqrt(v1))^2 / (d1 - d0)^2, where d1 = p10 - p01 is the true difference, d0 = -margin the difference under the null hypothesis, v1 = p10 + p01 - d1^2 the variance under the alternative, and v0 = 2 p01.bar + d0 - d0^2 the variance under the null hypothesis evaluated at the large sample value p01.bar of the restricted maximum likelihood estimate of p01, formula (5) of that article. z.a is the upper alpha quantile of the standard normal distribution, the upper alpha / 2 quantile for a two-sided alternative, and z.b the tar.power quantile. With margin = 0 the formula is formula (3) of Connor (1987). For alternative = 'less' the probabilities p10 and p01 are exchanged. For alternative = 'equivalence' the approximate power of each one-sided test is obtained in the same way for its own margin, at the level alpha, and the normal approximation is the smallest number of pairs at which the sum of the two approximate powers minus 1 attains the target power. The sum minus 1 is a lower bound of the approximate probability that both tests reject.

The normal approximation does not depend on the test, and for 'McNemar-cc' it leaves out the continuity correction. It is the starting point of the exact search for every test. The exact power is not monotone in the number of pairs, so the three searches can return different numbers, see BinarySampleSize.

Value

An object of class bbssr_psamplesize, a data frame with one row containing:

p10, p01

Probabilities of the two kinds of discordant pairs

alpha

Level of significance

tar.power

Target power

Test

Name of the statistical test

alternative

Direction of the alternative hypothesis

Power

Exact power of Test with the required number of pairs

N

Required number of pairs

The attributes hold the remaining settings, among them the unrounded normal approximation n.raw and the limit search.limit of the search 'stable' (otherwise NA).

References

Connor RJ (1987). Sample size for testing differences in proportions for the paired-sample design. Biometrics, 43(1), 207-211.

Nam J (1997). Establishing equivalence of two treatments and sample size requirements in matched-pairs design. Biometrics, 53(4), 1422-1430.

Examples

# Example of Connor (1987, p. 210): theta1 = 0.8, theta2 = 0.7 and psi = 0.3
PairedSampleSize(p10 = 0.2, p01 = 0.1, alpha = 0.05, tar.power = 0.9,
                 Test = 'McNemar', method = 'standard')


# Exact number of pairs of the exact conditional test
PairedSampleSize(p10 = 0.2, p01 = 0.1, alpha = 0.05, tar.power = 0.9,
                 Test = 'McNemar-exact')

Description

Calculates the exact type I error rate of a matched-pairs design with blinded sample size re-estimation, and of the fixed design with the planned number of pairs, over the probability of a discordant pair on the boundary of the null hypothesis, together with the largest rate.

Usage

PairedTypeIErrorBSSR(
  Delta.A,
  N,
  omega = NULL,
  alpha,
  tar.power,
  Test,
  restricted = FALSE,
  alternative = c("greater", "less", "two.sided", "equivalence"),
  n.grid = 100,
  bb.gamma = 0,
  ss.method = c("exact", "standard", "conditional.power"),
  ss.Test = Test,
  ss.alpha = alpha,
  search = c("crossing", "smallest", "stable"),
  search.limit = c(2, 50),
  N.min = NULL,
  N.max = NULL,
  n.interim = NULL,
  psi = seq(0, 1, by = 0.01),
  maximize = c("certified", "refined", "grid"),
  margin = 0,
  ref.pvalue = FALSE
)

Arguments

Details

The type I error rate is evaluated on the boundary p10 - p01 = d0 of the null hypothesis, with d0 = 0 for a test of superiority, d0 = -margin for alternative = 'greater' and d0 = margin for 'less', as for two independent groups. For a fixed design, Berger and Sidik (2003, Theorem 1) show that the largest rate over the null hypothesis of superiority lies on this boundary for rejection regions that are Barnard convex. A test of equivalence has two boundaries, -lower and upper, and the largest rate is the larger of the maxima on the two.

On a boundary the rejection probability is a polynomial in psi: given the numbers of discordant pairs, the number of pairs in which only treatment 1 responds is binomial with probability p10 / psi, which is fixed on the boundary up to the linear reparametrization of paired_boundary, and the re-estimation depends on the interim data only through the number of discordant pairs. The probability is computed exactly. With maximize = 'certified' the Bernstein coefficients of the polynomial over the interval spanned by the values of psi on the boundary are bounded by subdivision, as in BinaryTypeIErrorBSSR, which gives an upper bound of the largest rate over the interval within 1e-12 of the maximum found.

The exact conditional McNemar test keeps its level whatever blinded rule is used (Schepers et al., 2026), so its largest rate does not exceed alpha.

Value

An object of class bbssr_ptie, a data frame with one row for each value of psi on the boundary, containing psi, the probabilities p10 and p01 on the boundary, and the rates TIE.BSSR of the design with re-estimation and TIE.TRAD of the fixed design. For a test of equivalence the rates on the two boundaries are stacked, with the column boundary. The attribute max holds the largest rates TIE of both designs, the values psi at which they occur, the upper bounds bound of the certified maximization (otherwise NA) and, for a test of equivalence, the boundary. The attribute reestimation holds the final number of pairs for every interim number of discordant pairs, and the other attributes the design settings.

References

Berger RL, Sidik K (2003). Exact unconditional tests for a 2 x 2 matched-pairs design. Statistical Methods in Medical Research, 12(2), 91-108.

Schepers M, Brannath W, Hoffmann E, Stingl J, Schmidtmann I (2026). Blinded sample size review for McNemar's test based on primary and surrogate endpoints. arXiv:2608.17784.

Examples

tie <- PairedTypeIErrorBSSR(Delta.A = 0.15, N = 72, n.interim = 30, alpha = 0.05,
                            tar.power = 0.8, Test = 'McNemar',
                            alternative = 'two.sided', ss.method = 'standard')
print(tie)


plot(tie)

Description

Draws the conditional rejection probabilities of a design with blinded sample size re-estimation over the pooled responder counts of the two stages, or the type I error rate given the pooled number of interim responders.

Usage

## S3 method for class 'bbssr_crp'
plot(
  x,
  what = c("CRP", "CRP.total", "by.s"),
  main = NULL,
  sub = NULL,
  xlab = NULL,
  ylab = NULL,
  legend.title = NULL,
  colours = NULL,
  base_size = 11,
  ...
)

Arguments

Value

A ggplot object

Examples

crp <- BinaryCondRejectBSSR(
  Delta.A = 0.3, N1 = 12, N2 = 12, n.interim = c(6, 6), r = 1,
  alpha = 0.025, tar.power = 0.8, Test = 'Fisher', ss.method = 'standard',
  theta = c(0.3, 0.5)
)
plot(crp)
plot(crp, what = 'by.s')

Description

Draws the power or the expected total sample size of the designs of BinaryGridBSSR against the true pooled response probability, with one colour per value of a chosen column and, optionally, one panel per value of another.

Usage

## S3 method for class 'bbssr_grid'
plot(
  x,
  what = c("power", "E.N"),
  colour.by = NULL,
  facet.by = NULL,
  main = NULL,
  sub = NULL,
  xlab = NULL,
  ylab = NULL,
  ref.line = NULL,
  legend.title = NULL,
  base_size = 11,
  ...
)

Arguments

Value

A ggplot object

Examples

design <- expand.grid(Test = c('Chisq', 'Fisher'), omega = c(0.3, 0.5),
                      stringsAsFactors = FALSE)
grid <- BinaryGridBSSR(design, p = c(0.3, 0.4, 0.5), Delta.A = 0.3, N1 = 30, N2 = 30,
                       r = 1, alpha = 0.025, tar.power = 0.8, ss.method = 'standard')
plot(grid, colour.by = 'Test', facet.by = 'omega')
plot(grid, what = 'E.N', colour.by = 'omega', facet.by = 'Test')

Description

Plot Exact Power against the Response Probability of Group 1

Usage

## S3 method for class 'bbssr_power'
plot(
  x,
  main = NULL,
  sub = NULL,
  xlab = NULL,
  ylab = NULL,
  ylim = c(0, 1),
  show.points = TRUE,
  colours = NULL,
  base_size = 11,
  ...
)

Arguments

Details

The vertical range is imposed with coord_cartesian, so points outside ylim are hidden rather than removed from the data.

Value

A ggplot object

Examples

pw <- BinaryPower(p1 = seq(0.3, 0.8, by = 0.1), p2 = rep(0.2, 6),
                  N1 = 20, N2 = 20, alpha = 0.025, Test = 'Chisq')
plot(pw)

# Enlarge the type, rescale the vertical axis, rename the axes and drop the markers
plot(pw, base_size = 14, ylim = c(0.2, 1), sub = NA, show.points = FALSE,
     xlab = 'Response probability, experimental group', ylab = 'Exact power')

Description

Plot the Power of a BSSR Design against the Fixed-Sample Design

Usage

## S3 method for class 'bbssr_powerbssr'
plot(
  x,
  main = NULL,
  sub = NULL,
  xlab = NULL,
  ylab = NULL,
  ylim = NULL,
  ref.line = NULL,
  legend.title = NULL,
  legend.labels = NULL,
  show.points = TRUE,
  colours = NULL,
  base_size = 11,
  ...
)

Arguments

Details

Setting Delta.T to 0 in BinaryPowerBSSR turns the two power columns into rejection probabilities under the null hypothesis. The default reference line at the target power is then out of place, and the level of significance passed through ref.line together with a rescaled ylim gives a readable plot of the type I error rate.

The vertical range is imposed with coord_cartesian, so points outside ylim are hidden rather than removed from the data.

Value

A ggplot object

Examples

res <- BinaryPowerBSSR(
  p = seq(0.23, 0.47, by = 0.04),
  Delta.A = 0.3, Delta.T = 0.3,
  N1 = 39, N2 = 39, omega = 0.5, r = 1,
  alpha = 0.025, tar.power = 0.8, Test = 'Chisq'
)
plot(res)

# Type I error rate, with the reference line moved to the level of significance
tie <- BinaryPowerBSSR(
  p = seq(0.23, 0.47, by = 0.04),
  Delta.A = 0.3, Delta.T = 0,
  N1 = 39, N2 = 39, omega = 0.5, r = 1,
  alpha = 0.025, tar.power = 0.8, Test = 'Chisq'
)
plot(tie, ref.line = 0.025, ylim = c(0.015, 0.030), base_size = 14,
     show.points = FALSE,
     main = 'Type I error rate of the BSSR design', ylab = 'Type I error rate',
     legend.title = 'Design', legend.labels = c('BSSR', 'Fixed'))

Description

Displays the possible outcomes of a matched-pairs trial and shades the outcomes for which the null hypothesis is rejected.

Usage

## S3 method for class 'bbssr_prr'
plot(
  x,
  main = NULL,
  sub = NULL,
  xlab = NULL,
  ylab = NULL,
  legend.title = NULL,
  legend.labels = NULL,
  colours = NULL,
  base_size = 11,
  ...
)

Arguments

Details

The vertical axis counts the pairs in which only treatment 1 responds and runs downwards, and the horizontal axis counts the pairs in which only treatment 2 responds, as in the map printed by print.bbssr_prr. Only the possible outcomes, with at most N discordant pairs, are drawn.

Value

A ggplot object

Examples

RR <- PairedRR(N = 20, alpha = 0.025, Test = 'McNemar-midP')
plot(RR)

Description

Draws the type I error rate of a matched-pairs design with blinded sample size re-estimation and of the fixed design against the probability of a discordant pair on the boundary of the null hypothesis, with a reference line at the nominal level. For a test of equivalence the two boundaries are drawn in separate panels.

Usage

## S3 method for class 'bbssr_ptie'
plot(
  x,
  main = NULL,
  sub = NULL,
  xlab = NULL,
  ylab = NULL,
  ylim = NULL,
  ref.line = NULL,
  legend.title = NULL,
  legend.labels = NULL,
  colours = NULL,
  base_size = 11,
  ...
)

Arguments

Value

A ggplot object

Examples

tie <- PairedTypeIErrorBSSR(Delta.A = 0.2, N = 40, n.interim = 20, alpha = 0.05,
                            tar.power = 0.8, Test = 'McNemar',
                            alternative = 'two.sided', ss.method = 'standard',
                            psi = seq(0.1, 0.9, by = 0.05))
plot(tie)

Description

Displays the outcome grid of a two-arm trial with a binary endpoint and shades the outcomes for which the null hypothesis is rejected.

Usage

## S3 method for class 'bbssr_rr'
plot(
  x,
  main = NULL,
  sub = NULL,
  xlab = NULL,
  ylab = NULL,
  legend.title = NULL,
  legend.labels = NULL,
  colours = NULL,
  base_size = 11,
  ...
)

Arguments