borrOrderingInternal: BORR Ordering, internal calculation functions

In exact2x2: Exact Tests and Confidence Intervals for 2x2 Tables

BORR Ordering, internal calculation functions

Description

Three functions for calculating the BORR ordering. The default did some slow borrOrdering calculations are done ahead of time and stored in sysdata.rda, for n1 and n2 smaller than 21 and for tuningParm=0.025.

Usage

borrOrderingAlphaGrid(n1, n2, tuningParm = 0.025, controlborr = borrControl())

borrOrderingByRR(n1, n2, tuningParm = 0.025, controlborr = borrControl())

borrOrderingPreCalc(n1, n2, tuningParm=0.025, orderPreCalc=orderPreCalc)

borrPreCalc(NList=seq(2,20),
           tuningParm = 0.025,
           controlborr = borrControl())
           
calcRejectProb(p.ctrl, Threshold, p.trt = p.ctrl, n.trt, n.ctrl, max.uninf.ctrls = n.ctrl)

getThreshold(n.ctrl, n.trt, tuningParm = 0.025, nThetaGrid = 1000, 
    max.uninf.ctrls = n.ctrl, forceConvex = TRUE)

Arguments

n1	sample size in group 1
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
controlborr	a list of control parameters to define algorithms, see borrControl
orderPreCalc	a list of precalculated orderings (see details)
NList	list of n1 and n2 values for creating orderPreCalc object. Does all possible combinations
p.ctrl	vector of theta values for theta1, usually determined by controlborr$nThetaGrid
Threshold	vector of threshold values that define one rejection region.
p.trt	vector of theta values for theta2, usually determined by controlborr$nThetaGrid
n.trt	n2 (notation matches the Gabriel, et al paper)
n.cntrl	n1 (notation matches the Gabriel, et al paper)
max.uninf.ctrls	set to n.cntrl, see code before changing it
forceConvex	logical, should always be TRUE. If you want to try FALSE check the code first.

Details

All BORR ordering functions automatically enforce Barnard's convexity in the rejection regions (in response to the letter of Martin Andres). Note that the original ordering in Figure 2 of Gabriel et al was incorrect. The correct value is in the response letter by Gabriel et al (see also the example code in borrTest).

The controlborr$orderFunc determines which function calculates the borr ordering. When controlborr$orderFunc=NULL (the default) the code first searches to see if there is a precalculated ordering (see below), and if not it calls borrOrderingByRR if n1+n2<=16, and otherwise calls borrOrderingAlphaGrid. When controlborr$orderFunc='AlphaGrid' then it calls borrOrderingAlphaGrid, when controlborr$orderFunc='ByRR' then it calls borrOrderingByRR.

The function borrOrderingByRR calculates the ordering based on trying convex rejection regions and calculating the alpha star value when different points that are added are just barely rejected. This leads to fast and accurate calculates for small n1 and n2 (less than 8), but can be slow for larger n1 and n2. It rounds the alpha star values to the nearest controlborr$digits, to avoid computer problems with ties (remember the alpha star values themselves are calculated by a grid on the theta values).

The function borrOrderingAlphaGrid calculates the ordering based on a grid of alpha values. It can be faster for larger n1 and n2, but its accuracy depends on the controlborr$nAlphaGrid.

The function borrPreCalc as run in the example should produce orderPreCalc. It was actually run on a parallel processing machine as 361 separate jobs. These calculations can take a bit of time. Then borrOrdering (when controlborr$orderFunc=NULL) will automatically check to see if the ordering has previously been calculated and if so will call borrOrderingPreCalc and if not call borrOrderingAlphaGrid.

The functions calcRejectProb and getThreshold are called by both borrOrderingAlphaGrid and borrOrderingByRR.

Value

The function borrOrderingAlphaGrid and borrOrderingByRR returns an rank matrix as well as an alpha matrix. The alpha matrix is the minimum alpha for each point to just enter the rejection region (in the notation of Gabriel et al, it is Min(alphastar: delta(alphastar, NC, NT, YC, YT)=1)). The rank matrix is the ordering matrix as in Figure 2 (see correction in letter). The borrOrderingPreCalc only returns the rank matrix. The list orderPreCalc has elements:

orderList	a list of the rank matrices, with orderList[[i]] associated with n1List[i] and n2List[i]
controlborr	control used in calculating orderings, see borrControl
tuningParm	the tuning parmeter used in the orderings
n1List	the n1List used in the orderings
n2List	the n2List used in the orderings

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) (DOI: 10.1002/sim.7579).

Antonio Martin Andres. Letter to the editor about Gabriel et al. Statistics in Medicine (to appear).

Gabriel, EE, Nason, M, Fay, MP, and Follmann, DA. Reply to letter from Martin Andres. Statistics in Medicine (to appear).

Examples

## Not run: 
# This is the call that should produce the orderPreCalc object 
# used by borrOrderingPreCalc
orderPreCalc<-borrPreCalc(NList=2:20,
    tuningParm = 0.025,
    controlborr = borrControl(nAlphaGrid = 10000, 
    nThetaGrid=1000, maxIter=0)) 

## End(Not run)

exact2x2 documentation built on Feb. 16, 2023, 10:11 p.m.