Matrix correlations between multiple distance matrices

This function efficiently applies the Mantel test between all members of either the results of precise_dist or a named list of distance matrices. The Mantel test is a clean-room base-R implementation of the classic permutation test (no external dependency).

Usage

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

Arguments

data

Either a named list of distance matrices or the native output of precise_dist.

method

A string value of the correlation method to use. Options include "pearson" (the default), "spearman" or "kendall". The "mgc" option (distance correlation) requires the optional mgc package.

permutations

Number of permutations in assessing significance.

parallel

TRUE or FALSE. Should the function use future.apply::future_lapply() on the active future plan? See details.

verbose

TRUE or FALSE. Should the function tell you what is happening internally?

seed

Optional whole-number seed. When supplied, permutation p-values are reproducible across sequential and future-backed parallel execution.

Value

A list containing output (the pair table), statistic (the correlation matrix), signif (the significance matrix), and parameters (method, permutations, seed, and input type provenance).

Details

Without specific domain knowledge, choosing the appropriate distance(s) for a dataset can be a very difficult task. Given a list of distance matrices, this function calculates the correlation between all of them i.e. it calculates a correlation matrix of distance relationships. This can be helpful for filtering certain distances from downstream operations, for example, distances which are too similar or too different from other distances. Note that before running this function, the input data should probably be coerced into all distances or all similarities using precise_transform.

References

Muchmore, B., Muchmore P. and Alarcón-Riquelme ME. (2018). Optimal Distance Matrix Construction with PreciseDist and PreciseGraph.

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

Author

Brian Muchmore

Examples

library(PreciseDist)

test_matrix <- replicate(100, rnorm(10))

test_distances <- test_matrix %>%
  precise_dist(dists = c("euclidean", "manhattan", "maximum", "correlation"))
#> precise_dist(): starting 4 metric(s) at 2026-07-14 01:06:11
#> precise_dist(): finished at 2026-07-14 01:06:11 (0.01 seconds)
#> precise_dist(): 4/4 metrics completed.

test_input_data <- test_distances %>%
  precise_transform(to = "distance")

test_mantel_output <- test_input_data %>%
  precise_correlations(method = "pearson", permutations = 999, parallel = FALSE, verbose = TRUE)
#> [1] "Starting distance correlation calculations at 2026-07-14 01:06:11.534288"
#> [1] "Finished calculations at 2026-07-14 01:06:11.710586"
#> [1] "Calculations took: 0.18 seconds"

if (requireNamespace("heatmaply", quietly = TRUE)) {
  heatmaply::heatmaply(test_mantel_output$statistic)
  heatmaply::heatmaply(test_mantel_output$signif)
}
#> Warning: Using `size` aesthetic for lines was deprecated in ggplot2 3.4.0.
#> ℹ Please use `linewidth` instead.
#> ℹ The deprecated feature was likely used in the dendextend package.
#>   Please report the issue at <https://github.com/talgalili/dendextend/issues>.