brainPvals: Permutation p-Values for Brain Imaging

In annavesely/sumSome: True Discovery Guarantee by Sum-Based Tests

Permutation p-Values for Brain Imaging

Description

This function computes p-value combinations for different permutations of brain imaging data. A voxel's p-value is calculated by performing the one-sample t test for the null hypothesis that its mean contrast over the different subjects is zero.

Usage

brainPvals(copes, mask = NULL, alternative = "two.sided", alpha = 0.05, B = 200, 
           seed = NULL, truncFrom = NULL, truncTo = 0.5,
           type = "vovk.wang", r = 0, rand = FALSE)

Arguments

copes	list of 3D numeric arrays (contrasts maps for each subject).
mask	3D logical array, where TRUE values correspond to voxels inside the brain, or character for a Nifti file name.
alternative	direction of the alternative hypothesis (greater, lower, two.sided).
alpha	significance level.
B	number of permutations, including the identity.
seed	seed.
truncFrom	truncation parameter: values greater than truncFrom are truncated. If NULL, it is set to alpha.
truncTo	truncation parameter: truncated values are set to truncTo. If NULL, p-values are not truncated.
type	p-value combination among edgington, fisher, pearson, liptak, cauchy, harmonic, vovk.wang (see details).
r	parameter for Vovk and Wang's p-value combination.
rand	logical, TRUE to compute p-values by permutation distribution.

Details

A p-value p is transformed as following.

• Edgington: p (Edgington, 1972)

• Fisher: -2log(p) (Fisher, 1925)

• Pearson: 2log(1-p) (Pearson, 1933)

• Liptak: qnorm(1-p) (Liptak, 1958; Stouffer et al., 1949)

• Cauchy: tan[(0.5-p)pi] with pi=3.142 (Liu and Xie, 2020)

• Harmonic mean: 1/p (Wilson, 2019)

• Vovk and Wang: p^r (log(p) for r=0) (Vovk and Wang, 2020)

An error message is returned if the transformation produces infinite values.

For Vovk and Wang, r=0 corresponds to Fisher, and r=-1 to the harmonic mean.

Truncation parameters should be such that truncTo is not smaller than truncFrom. As Pearson's and Liptak's transformations produce infinite values in 1, for such methods truncTo should be strictly smaller than 1.

The significance level alpha should be in the interval [1/B, 1).

Value

brainPvals returns an object of class sumBrain, containing

• statistics: numeric matrix of p-values, where columns correspond to voxels inside the brain, and rows to permutations. The first permutation is the identity

• mask: 3D logical array, where TRUE values correspond to voxels inside the brain

• alpha: significance level

• truncFrom: transformed first truncation parameter

• truncTo: transformed second truncation parameter

Author(s)

Anna Vesely.

References

Goeman J. J. and Solari A. (2011). Multiple testing for exploratory research. Statistical Science, doi: 10.1214/11-STS356.

Vesely A., Finos L., and Goeman J. J. (2023). Permutation-based true discovery guarantee by sum tests. Journal of the Royal Statistical Society, Series B (Statistical Methodology), doi: 10.1093/jrsssb/qkad019.

See Also

Permutation statistics for brain imaging using t scores: brainScores

True discovery guarantee for cluster analysis: brainAnalysis

Suprathreshold clusters: brainClusters

Examples

# simulate 20 copes with dimensions 10x10x10
set.seed(42)
copes <- list()
for(i in seq(20)){copes[[i]] <- array(rnorm(10^3, mean = -10, sd = 30), dim=c(10,10,10))}

# cluster map where t scores are grater than 2.8, in absolute value
thr <- 2.8
cl <- brainClusters(copes = copes, thr = thr)

# create object of class sumBrain (combination: Cauchy)
res <- brainPvals(copes = copes, alpha = 0.2, seed = 42, type = "cauchy")
res
summary(res)

# confidence bound for the number of true discoveries and the TDP within clusters
out <- brainAnalysis(res, clusters = cl$clusters)
out$summary

annavesely/sumSome documentation built on Jan. 28, 2025, 8:15 a.m.