permtest_metric: Permutation test for any metric between brain maps

In neuromapr: Spatial Null Models and Transforms for Brain Map Comparison

Permutation test for any metric between brain maps

Description

Computes a user-specified metric between two vectors and tests significance using either spatially-constrained null surrogates or simple random permutation.

Usage

permtest_metric(
  x,
  y,
  metric_func = stats::cor,
  n_perm = 1000L,
  seed = NULL,
  null_method = NULL,
  distmat = NULL,
  coords = NULL,
  parcellation = NULL,
  ...
)

Arguments

x, y	Numeric vectors.
metric_func	Function taking ⁠(x, y)⁠ and returning a scalar.
n_perm	Integer number of permutations.
seed	Optional integer seed for reproducibility.
null_method	Optional null model method passed to generate_nulls(). If NULL, uses simple random permutation.
distmat	Distance matrix (passed to generate_nulls() if needed).
coords	Coordinate list (passed to generate_nulls() if needed).
parcellation	Integer vector (passed to generate_nulls() if needed).
...	Additional arguments passed to generate_nulls().

Value

List with ⁠$observed⁠, ⁠$null_values⁠, ⁠$p_value⁠, and ⁠$n_perm⁠.

References

Markello RD et al. (2022) Nature Methods 19:1472-1480. doi:10.1038/s41592-022-01625-w

Examples

x <- rnorm(100)
y <- x + rnorm(100)
result <- permtest_metric(x, y, n_perm = 99L, seed = 1L)
result$observed
result$p_value

neuromapr documentation built on Feb. 27, 2026, 5:08 p.m.