brainPvals: Permutation p-Values for Brain Imaging
In sumSome: Permutation True Discovery Guarantee by Sum-Based Tests

Description Usage Arguments Details Value Author(s) References See Also Examples

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.

1
2
3

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)

`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`, `vovk.wang` (see details).
`r`	parameter for Vovk and Wang's p-value combination.
`rand`	logical, `TRUE` to compute p-values by permutation distribution.

A p-value p is transformed as following.

Edgington: -p
Fisher: -log(p)
Pearson: log(1-p)
Liptak: -qnorm(p)
Cauchy: tan(0.5 - p)/p
Vovk and Wang: - sign(r)p^r

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

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).

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

Anna Vesely.

Goeman, J. J. and Solari, A. (2011). Multiple testing for exploratory research. Statistical Science, 26(4):584-597.

Hemerik, J. and Goeman, J. J. (2018). False discovery proportion estimation by permutations: confidence for significance analysis of microarrays. JRSS B, 80(1):137-155.

Vesely, A., Finos, L., and Goeman, J. J. (2020). Permutation-based true discovery guarantee by sum tests. Pre-print arXiv:2102.11759.

Permutation statistics for brain imaging using t scores: brainScores

True discovery guarantee for cluster analysis: clusterAnalysis

Suprathreshold clusters: findClusters

# 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 <- findClusters(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 <- clusterAnalysis(res, clusters = cl$clusters)