borrTest: Boundary-Optimized Rejection Region Test

Description Usage Arguments Details Value Note Author(s) References Examples

View source: R/borrFunctions.R

Description

An unconditional exact test for the two-sample binomial problem when it is expected that theta1 (probability of an event in group 1) will be close to 1. Used for test versus control when all controls are expected to fail.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
borrTest(x1, n1, x2, n2, tuningParm = 0.025,
    parmtype = c("ratio", "difference", "oddsratio"), 
    nullparm = NULL, alternative = c("less", "greater", "two.sided"), 
    conf.int = TRUE, conf.level = 0.975,  
    controlUC = ucControl(), controlborr = borrControl(), ...)

borrPvals(n1,n2, tuningParm=0.025,    
    parmtype = c("ratio", "difference","oddsratio"), 
    nullparm = NULL, alternative = c("less", "greater","two.sided"),  
    conf.int = TRUE, conf.level = 0.975,
    controlUC=ucControl(), controlborr=borrControl(),...)

borrOrdering(n1,n2,tuningParm = .025,
            controlborr=borrControl())
            
powerBorr(n1,n2,p1,p2,alpha=0.025,...)

Arguments

x1

number of events in group 1

n1

sample size in group 1

x2

number of events in group 2

n2

sample size in group 2

tuningParm

tuning parameter, default is 0.025 and designs BORR tests with maximum power for one-sided 0.025 tests

parmtype

parameter type, either 'ratio' for theta2/theta1, 'difference' for theta2-theta1, or 'oddsratio' for theta2*(1-theta1)/(theta1*(1-theta2)).

nullparm

null parameter value, default=NULL gives parameter value for theta1=theta2 (e.g., 1 for 'ratio' or 0 for 'difference' ).

alternative

alternative hypothesis, BORR tests are designed for alternative='less' (see Note for other alternatives)

conf.int

logical, should confidence interval be calculated?

conf.level

confidence level, default is 0.975 (see note)

controlUC

a list of control parameters to define algorithms in the call to uncondExact2x2, see ucControl

controlborr

a list of control parameters to define algorithms, see borrControl

p1

probability of an event in group 1

p2

probability of an event in group 2

alpha

alpha-level for rejecting, reject when p-value

≤q

alpha

...

extra arguments passed (only used for powerBorr, passes arguments to the borrPvals function)

Details

The boundary-optimized rejection region test is designed to test the one-sided alternative that theta2 < theta1, where X1 is binomial(n1,theta1), and X2 is binomial(n2,theta2). The test is designed to be optimal when theta1 is very close to 1. For example, in a vaccine malaria challenge study where we expect all n1 individuals that got the control vaccine to have the event (get malaria when challenged with malaria). For details see Gabriel et al (2018).

The function borrTest tests the results of one study, and returns an htest object. The function borrPvals calculates the p-values for every possible result of a study. The function borrOrdering orders every possible result of the study. See borrOrderingInternal for calculation details. The function powerBorr calculates the power where p-values are calculated by borrPvals and rejection is when

p ≤q

alpha.

Value

The function borrPvals returns a (n1+1) by (n2+1) matrix of p-values for all possible x1 and x2 values. The function borrOrdering returns a matrix with the rank of all possible x1 and x2 values. The function borrTest returns a list of class htest with elements:

statistic

proportion in sample 1

parameter

proportion in sample 2

p.value

p-value from test

conf.int

confidence interval on parameter given by parmtype

estimate

MLE estimate of parameter given by parmtype

null.value

null hypothesis value of parameter given by parmtype

alternative

alternative hypothesis

method

description of test

data.name

description of data

Note

The tests are designed to have good power for the one-sided test that H0: theta2 theta1, with alternative H1: theta2 < theta1 at significance level equal to tuningParm. Since the default tuningParm is 0.025, the default confidence level is 0.975 so that the confidence intervals will be compatible with the test where the one-sided p-values reject at level 0.025.

Sometimes you may want two-sided confidence intervals on the parameter of interest. If you ask for a two-sided alternative, then the confidence interval and the resulting p-value will be two-sided as well. The default is a 'central' interval, so the two-sided p-value should be twice the minimum of the one-sided p-values. Further, with a conf.level of 0.95 for the two-sided alternative, the error on each side will be bounded by 0.025.

Author(s)

Martha Nason, Erin Gabriel, Michael P. Fay

References

Gabriel, EE, Nason, M, Fay, MP, and Follmann, DA. (2018). A boundary-optimized rejection region test for the two-sample binomial problem. Statistics in Medicine. 37(7): 1047-1058 (DOI: 10.1002/sim.7579).

Gabriel, EE, Nason, M, Fay, MP, and Follmann, DA. (2018). Reply to letter from Martin Andres. Statistics in Medicine 37(14): 2303-2306.

Martin Andres, Antonio. (2018). Letter to the editor about Gabriel et al. Statistics in Medicine 37(14) 2301-2302.

Examples

1
2
3
4
## Not run: borrTest(4,4,1,4)
# Note Figure 2 in Gabriel et al is incorrect. The correct value 
# is in the response letter, and given by 
borrOrdering(4,4,tuningParm=0.025)$rankMat

Example output

Loading required package: exactci
Loading required package: ssanv
     x2=0 x2=1 x2=2 x2=3 x2=4
x1=0   21   22   23   24   25
x1=1    8   13   15   16   20
x1=2    5    9   11   14   19
x1=3    3    6   10   12   18
x1=4    1    2    4    7   17

exact2x2 documentation built on Dec. 11, 2021, 9:43 a.m.