Skip to contents

Compute a correlation value for every row of X against the vector y and n_perm random permutations of y. If the number of distinct permutations of y is less than or equal to n_perm then an exact test using all permutations is performed instead. In both cases the function returns a data.frame of the original data with additional columns for the test statistic, permutation p-value, and FDR corrected p-value.

Usage

permutation_correlation_test(
  X,
  y,
  n_perm = 10000,
  method = c("pearson", "spearman"),
  alternative = c("two.sided", "greater", "less"),
  chunk_size = 1000,
  n_core = 1
)

Arguments

X

numeric matrix or data.frame that can be converted to a numeric matrix

y

numeric vector of values to correlate with rows of X

n_perm

integer. The desired number of permutations to sample from. Default (10,000)

method

character. One of "pearson" (default) or "spearman"

alternative

character. One of "two.sided" (default), "greater" or "less"

chunk_size

integer. Number of permutations to process at once. Controls memory usage, nrow(X) x chunk_size correlations are held in memory at a time. Default (1000)

n_core

integer. The number of cores to use for processing chunks of permutations. Default (1)

Value

data.frame containing the original values in X along with columns 'cor', 'empirical.p', and 'FDR'

Details

Exact p-values are computed as the proportion of all distinct permutations (including the observed ordering) with a correlation at least as extreme as the observed value. When permutations are randomly sampled, p-values are computed with statmod::permp() (if installed), which gives exact p-values for permutations sampled with replacement (Phipson & Smyth 2010). Otherwise the conservative estimate (b + 1) / (n_perm + 1) is used.

Correlations are computed by standardizing the rows of X once and performing matrix multiplication against chunks of permuted y. Rows of X containing missing values or with zero variance return NA.

References

Phipson B, Smyth GK (2010). Permutation P-values should never be zero: calculating exact P-values when permutations are randomly drawn. Statistical Applications in Genetics and Molecular Biology 9, Article 39.

Examples

# generate example data
X <- matrix(runif(1e3 * 10), nrow = 1e3, ncol = 10)
y <- 1:10
dimnames(X) <- list(paste("feature", 1:1e3, sep = "."), paste("sample", 1:10, sep = "."))

# correlate each row of X with 1,000 random permutations of vector y
res <- permutation_correlation_test(X, y, n_perm = 1e3, method = "spearman")

head(res)
#>            sample.1  sample.2  sample.3  sample.4  sample.5  sample.6  sample.7
#> feature.1 0.8133690 0.9960198 0.4743437 0.1652235 0.2639700 0.6809420 0.3330187
#> feature.2 0.9219679 0.1149627 0.7926740 0.1828164 0.5143388 0.9560175 0.6703622
#> feature.3 0.2524803 0.7884033 0.3725416 0.6177761 0.6039628 0.4534383 0.5096892
#> feature.4 0.7514328 0.9792410 0.2563485 0.2228114 0.8613759 0.2401690 0.7171215
#> feature.5 0.2043386 0.7490342 0.2491957 0.3671232 0.3395513 0.8303735 0.7652814
#> feature.6 0.8292433 0.7759643 0.3202482 0.6549513 0.6654236 0.1866482 0.1851118
#>             sample.8  sample.9 sample.10        cor empirical.p       FDR
#> feature.1 0.09105316 0.8593208 0.1116168 -0.4666667   0.1698300 0.9624071
#> feature.2 0.08446170 0.4930628 0.4521325 -0.2606061   0.4775223 0.9943326
#> feature.3 0.72866679 0.5325417 0.8079125  0.4303030   0.2247751 0.9624071
#> feature.4 0.22783827 0.1861546 0.6905217 -0.4909091   0.1638360 0.9624071
#> feature.5 0.53189127 0.6192076 0.3945705  0.4303030   0.2237761 0.9624071
#> feature.6 0.51473626 0.2175790 0.8036883 -0.3575758   0.3076922 0.9943326