Measure pairwise agreement between relatedness matrices

Runs a Mantel test between every pair of matrices in a collection and returns the pairwise agreement as a statistic matrix, a significance matrix, and a pair table.

Usage

precise_correlations(
  data,
  type = NULL,
  method = "pearson",
  permutations = 999,
  parallel = FALSE,
  verbose = FALSE,
  seed = NULL
)

Arguments

data: A tibble from precise_dist(), precise_transform(), precise_fusion(), precise_graph(), or precise_stability(), or a named list of matrices. At least two matrices are required and their keys must be unique.
type: Only for bare-list input. "distance" or "similarity", applying to every element. Must be omitted for tibble input, whose type column is authoritative.
method: "pearson" (the default), "spearman", or "kendall". "mgc" computes multiscale graph correlation and needs the optional mgc package.
permutations: Number of permutations used to assess significance. The default is 999.
parallel: TRUE or FALSE. Run the pairs on the active future::plan(). Do not pass a core count.
verbose: TRUE or FALSE. Report start, finish, and elapsed time. Defaults to FALSE, unlike most of the package.
seed: NULL or a whole number. Makes the permutation p-values reproducible.

Value

A list with four elements. output is a data frame of every pair with the columns distance_1, distance_2, statistic, and significance, sorted by descending statistic and including the self-pairs. statistic is the square agreement matrix, with 1 on the diagonal. signif is the matching square matrix of permutation p-values, with 0 on the diagonal. parameters records the method, permutations, seed, and input_type actually used.

Details

The Mantel test is a base R implementation of the classic permutation test with no external dependency. It correlates the off-diagonal values of two matrices under method and compares that correlation against permutations random relabellings of the observations. method = "mgc" instead calls mgc::mgc.test() and requires the optional mgc package.

Every row must share one type, and that type must be distance or similarity. A mixed set, or one containing correlation or affinity rows, is an error. Keys must be unique, at least two matrices are required, and every matrix must index the same observations in the same order.

statistic values lie in [-1, 1] with a diagonal of 1. signif values lie in [0, 1] with a diagonal of 0, and the smallest attainable p-value is 1 / (permutations + 1).

A pair that fails or is undefined, for example when one matrix is constant, does not stop the run. Those pairs are returned as NA and one warning names them.

parallel = TRUE dispatches the pairs through future.apply::future_lapply() on the active future::plan() and requires the future.apply package. A whole-number seed makes the permutation p-values reproducible and identical between sequential and parallel runs, and the session random-number state is restored on exit.

References

Mantel N (1967). The detection of disease clustering and a generalized regression approach. Cancer Research, 27(2), 209–220.

Vogelstein JT, Bridgeford EW, Wang Q, et al. (2019). Discovering and deciphering relationships across disparate data modalities. eLife, 8, e41690. doi:10.7554/eLife.41690 .

Author

Brian Muchmore

Examples

data(data_cell_cycle, package = "PreciseDist")

cells <- c(1:4, 60:63, 118:121)
cell_cycle <- as.matrix(data_cell_cycle[cells, 2:41])
rownames(cell_cycle) <- paste0(data_cell_cycle$Cell_cycle[cells], "_", cells)

distances <- precise_dist(
  cell_cycle,
  dists = c("euclidean", "manhattan", "canberra", "cosine"),
  verbose = FALSE
)

# A single type is required, so convert the cosine similarity first.
distances <- precise_transform(distances, to = "distance")

agreement <- precise_correlations(
  distances,
  method = "pearson",
  permutations = 99,
  seed = 1,
  verbose = FALSE
)

round(agreement$statistic, 2)
#>           euclidean manhattan canberra cosine
#> euclidean      1.00      0.97     0.43   0.57
#> manhattan      0.97      1.00     0.47   0.52
#> canberra       0.43      0.47     1.00   0.76
#> cosine         0.57      0.52     0.76   1.00
head(agreement$output, 3)
#>   distance_1 distance_2 statistic significance
#> 1  euclidean  euclidean         1            0
#> 2  manhattan  manhattan         1            0
#> 3   canberra   canberra         1            0
agreement$parameters
#> $method
#> [1] "pearson"
#> 
#> $permutations
#> [1] 99
#> 
#> $seed
#> [1] 1
#> 
#> $input_type
#> [1] "distance"
#>