lfisher_cpp: lfisher_cpp

Description

Takes a four integers corresponding to a 2x2 contingency matrix and calculates a natural-log transformed Fisher p-value.

Usage

lfisher_cpp(a, b, c, d, e_precision = 12, alternative = 1L)

Value

This function returns a numeric (double in C++) natural log-Fisher p-value.

Arguments

a

(required) This corresponds to cell 1 of the contingency matrix. In the context of GSNA, assuming two gene sets, this is used as the number of observable genes in the background that are not present either gene set.

b

(required) This corresponds to cell 2 of the contingency matrix. For GSNA this is the number of observable genes present in gene set 1, but not gene set 2.

c

(required) This corresponds to cell 3 of the contingency matrix. For GSNA this is the number of observable genes present in gene set 2, but not gene set 1.

d

(required) This corresponds to cell 4 of the contingency matrix. For GSNA this is the number of observable genes present in both gene sets 1 and 2.

e_precision

(optional) Numeric value that determines the precision of summation of partial p-values. For the less-than, greater-than and two-sided options in calculating the log-Fisher p-value, log-space summation of partial p-values must be accomplished using the so-called Log-Sum-Exponent trick. Due to limitations of precision in C++, however, numbers that differ by more than about 11 powers of e cannot be summed. By specifying a value less than 12, slightly less precise p-values can be calculated slightly faster. This option was included as way to accelerate calculation of p-values, but has not proven to significantly improve performance, so it may be removed in the future. Defaults to 12.

alternative

(optional) Integer corresponding to 4 options:

1: single-sided, greater-than. Sums p-values for intersections greater than and equal to d.

2

single-sided, less-than. Sums p-values for intersections less than and equal to d.

3

two-sided, sums all partial p-values less than or equal to the partial p-value for intersections equal to d.

4

partial. Calculates single p-value for intersections equal to d.

Details

Calculation of Fisher p-values is discussed in detail elsewhere, but partial natural-log transformed p-values are calculated as follows:

Given a 2x2 contingency matrix of the form:

$$\biggl[\begin{matrix}a & b \\ c & d\end{matrix}\biggr]$$

The natural log of the partial p-values is given by:

$$ln(p) = ln((a+b)!) + ln((c+d)!) + ln((a+c)!) + ln((b+d)!) - ln(a!) - ln(b!) - ln(c!) - ln(d!) - ln((a + b + c + d)!)$$

For the single and two-tailed alternatives, partial p-values are summed using the so-called 'log-sum-exponent' method.

Examples

Run this code


library(GSNA)

# Calculate a single natural log Fisher_p value:
log_fisher_p <- lfisher_cpp( a = 16000,
                             b = 200,
                             c = 170,
                             d = 100,
                             alternative = 3 )