R: BORR Ordering, internal calculation functions

borrOrderingInternal {exact2x2} | R Documentation

## 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)

[Package exact2x2 version 1.6.3 Index]