Permutation Test for Local Correlation Screening

Performs feature-wise permutation testing for local correlation statistics computed by lcor. By default, vertex labels of feature columns are permuted (permute = "z"), which is appropriate for screening associations between a fixed response field and candidate features.

Usage

permutation.test.lcor(
  adj.list,
  weight.list,
  y,
  z,
  type = c("derivative", "unit", "sign"),
  y.diff.type = c("difference", "logratio"),
  z.diff.type = c("difference", "logratio"),
  statistic = c("mean.abs", "mean", "max.abs"),
  permute = c("z", "y"),
  n.perm = 200L,
  seed = 1L,
  return.perm.stats = FALSE,
  verbose = FALSE,
  epsilon = 0,
  winsorize.quantile = 0,
  hop.radius = 1L,
  strata = NULL
)

Arguments

adj.list

Adjacency list (1-based indices).

weight.list

Edge-length (weight) list matching adj.list.

y

Numeric response vector of length n.

z

Numeric feature vector, matrix, or data frame with n rows.

type

Local-correlation weighting mode passed to lcor.

y.diff.type

Edge difference type for y; passed to lcor.

z.diff.type

Edge difference type for z; passed to lcor.

statistic

Summary statistic computed per feature from vertex-wise local-correlation coefficients.

"mean.abs"

Mean absolute local correlation (default).

"mean"

Signed mean local correlation.

"max.abs"

Maximum absolute local correlation.

permute

Permutation target:

"z"

Permute feature rows (default).

"y"

Permute response values.

n.perm

Integer \(\ge 1\); number of permutations.

seed

Optional integer RNG seed. A supplied seed is local: the caller's random-number state is restored, even on error. NULL advances the current stream.

return.perm.stats

Logical; if TRUE, include permutation statistics matrix in the result.

verbose

Logical; if TRUE, prints progress every 25 permutations.

epsilon, winsorize.quantile, hop.radius

Settings passed unchanged to lcor() for both observed and permuted statistics.

strata

Optional vector of group labels, one per vertex, without missing values. Permutations stay within groups; singleton groups remain fixed.

Value

A list with class "lcor_permutation_test" containing:

table

Data frame with feature, observed statistic, p-value, q-value.

stat.obs

Named numeric vector of observed statistics.

p.value

Named numeric vector of permutation p-values.

q.value

Named numeric vector of BH-adjusted p-values.

statistic

Statistic definition used.

permute

Permutation target used.

n.perm

Number of permutations.

stat.perm

Permutation statistics matrix (optional).

Details

Permuted rows must be exchangeable under the null conditional on the fixed graph, edge lengths, and unpermuted field. A common permutation is applied across feature columns. Local correlations and their feature summaries are recomputed, but graphs, fitted fields, and neighborhood selection are not. With strata, rows must be exchangeable within the supplied groups under that same conditional null. Grouping alone does not make spatial dependence exchangeable, and is not a replacement for an appropriate null model. The signed mean statistic uses an upper-tail comparison. P-values use the add-one Monte Carlo correction. BH-adjusted q.value refers to feature tests, not vertex tests, and its false discovery rate interpretation requires valid p-values and suitable dependence conditions.

Examples

# Independent null features on a fixed path: rows are exchangeable.
local({
  had <- exists(".Random.seed", envir = .GlobalEnv)
  if (had) old <- .Random.seed
  on.exit(if (had) assign(".Random.seed", old, envir = .GlobalEnv) else
    rm(".Random.seed", envir = .GlobalEnv))
  set.seed(42)
  a <- list(2L, c(1L, 3L), c(2L, 4L), c(3L, 5L), 4L)
  w <- lapply(a, function(v) rep(1, length(v)))
  z <- matrix(rnorm(15), 5, 3, dimnames = list(NULL, c("A", "B", "C")))
  result <- permutation.test.lcor(a, w, c(0, 1, 2, 1, 0), z,
                                   n.perm = 19, seed = 7)
  print(result)
})
# Nineteen draws give resolution 1/20; this tiny run illustrates the null,
# not a well-powered study. BH values concern features, not vertices.