shiftrPermBinary {shiftR}

Fast Enrichment Testing on Binary Outcomes via Circular Permutations

Description

This function performs very fast feature enrichment permutation testing between two binary data sets. Circular permutations are used instead of simple permutations to preserve local dependence of test statistics. The input data sets can be preprocessed with shiftrPrepareLeft and shiftrPrepareRight functions.

Usage

shiftrPermBinary(
    left,
    right,
    offsets,
    alsoDoFisher = TRUE,
    returnPermOverlaps = FALSE)

Arguments

left

The first vector of binary (0/1) outcomes.
For repeated use it can be preprocessed with shiftrPrepareLeft function.

right

The second vector of binary (0/1) outcomes.
For repeated use it can be preprocessed with shiftrPrepareRight function.

offsets

Vector of offsets, can be generated by getOffsetsRandom, getOffsetsUniform, or getOffsetsAll.

alsoDoFisher

If TRUE, also perform Fisher exact test (via fisher.test).

returnPermOverlaps

If TRUE return overlap counts under all tested permutations.

Value

Returns a list with:

nfeatures

Number of features in input data sets.

lfeatures

Number of active features in the left data set.

rfeatures

Number of active features in the right data set.

overlap

Number of features simultaneously active in both data sets.

overlapUnderNull

Expected value of overlap if input data sets were independent.

enrichment

Enrichment ratio, equal to overlap / overlapUnderNull

permPVenrich

Permutation p-value for enrichment (one-sided).

permPVdeplete

Permutation p-value for depletion (one-sided).

permPV

Permutation p-value for depletion (two-sided).

permZ

Permutation z-statistic, calculated by fitting normal distribution to the overlap values under permutations.
Positive values indicate enrichment.

fisherTest

Fisher exact test, as output by fisher.test

fisherMat

Input 2x2 matrix for Fisher exact test.

overlapsPerm

Vector of length npermute with overlap values under permutations.

Author(s)

Andrey A Shabalin [e-mail]

See Also

This function essentially involves npermute calls of singlePermutation function and calculation of summary statistics and p-values.

Examples

### Number of features
nf = 1e6
npermute = 10000

### Generate data sets
# The vector of a few common active feature to create dependence
common = sample(c(0L,1L), size = nf, replace = TRUE, prob = c(0.999,0.001))

# Left and right data sets with the common active features
lset = sample(c(0L,1L), size = nf, replace = TRUE, prob = c(0.8,0.2)) | common
rset = sample(c(0L,1L), size = nf, replace = TRUE, prob = c(0.8,0.2)) | common

offsets = getOffsetsUniform(n = nf, npermute = npermute)

show(head(offsets))
show(tail(offsets))

z = shiftrPermBinary(lset, rset, offsets)

show(z)