Movatterモバイル変換

Type:

Package

Title:

Permutation-Based All-Resolutions Inference

Version:

1.1.3

Date:

2025-09-23

Description:

Computes the All-Resolution Inference method in the permutation framework, i.e., simultaneous lower confidence bounds for the number of true discoveries. <doi:10.1002/sim.9725>.

Depends:

R (≥ 3.5.0)

License:

GPL-2 |GPL-3 [expanded from: GPL (≥ 2)]

Imports:

Rcpp (≥ 1.0.3), matrixStats, RNifti, stats, grDevices,graphics, plyr, ARIbrain, utils

LinkingTo:

Rcpp, RcppArmadillo

Suggests:

knitr, rmarkdown

VignetteBuilder:

knitr

RoxygenNote:

7.3.2

Encoding:

UTF-8

Language:

en-US

BugReports:

https://github.com/angeella/pARI/issues

URL:

https://github.com/angeella/pARI

NeedsCompilation:

yes

Packaged:

2025-09-23 11:10:26 UTC; Andreella

Author:

Angela Andreella

[aut, cre] (Main author)

Maintainer:

Angela Andreella <angela.andreella@unive.it>

Repository:

CRAN

Date/Publication:

2025-09-23 11:40:03 UTC

Create Statistical Parametric Mapping (SPM)

Description

Creates the statistical parametric mapping in NIfTI format.

Usage

Statmap(copes, alternative = "two.sided", path = getwd(), name = "map", Pmap = FALSE, mask = NULL)

Arguments

copes

List of NIfTI file. The list of copes, i.e., contrasts maps, one for each subject used to compute the statistical tests.

alternative

Character string. It refers to the alternative hypothesis, must be one of"two.sided" (default),"greater" or"lower".

path

Character string. Path to save the plot. The path does not must end with/. Default togetwd().

name

Character string. The name of file that will be used to save the plot. Default to "map".

Pmap

Boolean value. IfTRUE the SPM of thep-values is returned. Default toFALSE.

mask

NIfTI file or character string. 3D array of logical values (i.e.TRUE/FALSE in/out of the brain). Alternatively it may be a (character) NIfTI file name. Ifmask=NULL, it is assumed that none of the voxels have to be excluded.

Value

Save the Statistical Parametric Mapping Nifti file inpath with name specified inname.

Author(s)

Angela Andreella

Examples

## Not run: library(fMRIdata)data(Auditory_copes)data(Auditory_mask)Statmap(copes = Auditory_copes, mask = Auditory_mask)## End(Not run)

Critical vector

Description

Compute critical vector curve.

Usage

criticalVector(pvalues, family = "simes", alpha = 0.05, lambda, delta = 1, m = NULL)

Arguments

pvalues

Matrix of pvalues with dimensionsm \times B used instead of the data matrixX. Default toNULL.

family

String character. Name of the family confidence envelope to compute the critical vector from"simes","aorc","beta","higher.criticism", and"power".Default to "simes".

alpha

Numeric value in '[0,1]'.\alpha level to control the family-wise error rate. Default to 0.05.

lambda

Numeric value.\lambda value computed bylambdaOpt.Default to 1.

delta

Numeric value.\delta value. Please see the reference below. Default to 1.

m

Numeric value. Number of hypothesis. Default toNULL.

Value

Numeric vector. Critical vector curve with lengthm.

Author(s)

Angela Andreella

References

Andreella, A., Hemerik, J., Finos, L., Weeda, W., & Goeman, J. (2023). Permutation-based true discovery proportions for functional magnetic resonance imaging cluster analysis. Statistics in Medicine, 42(14), 2311-2340.

Examples

db <- simulateData(pi0 = 0.8, m = 100, n = 20, rho = 0)out <- pARI::signTest(X = db)pv <- cbind(out$pv, out$pv_H0)cv <- criticalVector(pvalues = pv, family = "simes", lambda = 1)plot(sort(pv[,1]), type = "l")lines(cv)

Lower bound for the number of true discoveries

Description

Calculates 1-\alpha lower confidence bound for the set-wise of false null hypotheses.

Usage

dI(ix, cv, pvalues, iterative, approx, ncomb, ...)

Arguments

ix

Numeric vector: set-wise hypotheses considered.

cv

Numeric vector: critical vector computed bycriticalVector.

pvalues

Ifiterative = TRUE you must put here the matrix ofp-values with dimensionsm \times B wherem is the number of variables andB the number of permutations. Instead, ifiterative = FALSE, you can put directly the vector ofm observedp-values.

iterative

Boolean value. Ifiterative = TRUE, the iterative method is applied (computationally demanding). Default toFALSE. Please see the reference below.

approx

Boolean value. Default toTRUE. If you are analyzing high dimensional data, we suggest to putapprox = TRUE to speed up the computation time. Please see the reference below.

ncomb

Numeric value. Ifapprox = TRUE, you must decide how many random sub collections (level of approximation) considered. Default to 100.

...

Further arguments for the iterative approach, i.e.,iterative = TRUE.

Value

Numeric value: the lower confidence bound for the number of true discoveries concerning the clusterix specified.

Author(s)

Angela Andreella

References

Examples

db <- simulateData(pi0 = 0.7, m = 100, n = 20, rho = 0)out <- signTest(X = db)pv <- cbind(out$pv, out$pv_H0)cv <- criticalVector(pvalues = pv, family = "simes", lambda = 0.1, alpha = 0.1)dI(ix = c(1:100), cv = cv, pvalues = pv)

Lambda calibration

Description

Computes the optimal lambda calibration parameter used in the critical vectorcriticalVector.

Usage

lambdaOpt(pvalues, family, alpha = 0.05, delta = 0, step.down = FALSE, max.step = 10, m = NULL)

Arguments

pvalues

Matrix ofp-values with dimensionsm \times B wherem is the number of variables andB the number of permutations used instead of the data matrixX. Default toNULL.

family

String character. Name of the family confidence envelope to compute the critical vector from"simes","aorc","beta","higher.criticism", and"power".Default to "simes".

alpha

Numeric value in '[0,1]'.\alpha level to control the family-wise error rate. Default to 0.05.

delta

Numeric value.\delta value. Please see the reference below. Default to 0.

step.down

Boolean value. Default toFALSE If you want to compute the lambda calibration parameter using the step-down approach putTRUE. Please see the reference below.

max.step

Numeric value. Default to 10. Maximum number of steps for the step down approach, so useful whenstep.down = TRUE.

m

Numeric value. Number of hypotheses. Default toNULL.

Value

Numeric value.\lambda parameter estimate.

Author(s)

Angela Andreella

References

Examples

db <- simulateData(pi0 = 0.8, m = 100, n = 20, rho = 0)out <- signTest(X = db)pv <- cbind(out$pv, out$pv_H0)cv <- lambdaOpt(pvalues = pv, family = "simes", alpha = 0.05)

True Discovery Proportion brain map

Description

Performs the True Discovery Proportion brain map.

Usage

map_TDP(ARIout,path,name,mask)

Arguments

ARIout

Output object bypARIbrain.

path

Character string. Path to save the NIfTI file. The path does not must end with/.

name

Character string. The name of the map NIfTI file that will be used.

mask

Value

The function write directly in thepath specified the true discovery proportion NIfTI map with name specified inname.

Author(s)

Angela Andreella

Permutation-based All-Resolutions Inference

Description

The main function for All-Resolutions Inference (ARI) method based on the critical vector constructed using thep-values permutation distribution. The function computes simultaneous lower bounds for the number of true discoveries for each set of hypotheses specified inix controlling family-wise error rate at levelalpha.

Usage

pARI(X= NULL, ix, alpha = 0.05, family = "simes", delta = 0, B = 1000, pvalues = NULL, test.type = "one_sample", complete = FALSE, clusters = FALSE, iterative = FALSE, approx = TRUE, ncomb = 100, step.down = FALSE, max.step = 10, ...)

Arguments

X

Data matrix where rows represent them variables and columns then observations.

ix

Numeric vector which expresses the set of hypotheses of interest. It can be a vector with length equalsm indicating the corresponding cluster for each variable,(in this case, you must putclusters = TRUE), or a vector containing the position indices of the variables of interest if only one set/cluster of hypotheses is considered.

alpha

Numeric value in '[0,1]'.\alpha level to control the family-wise error rate. Default to 0.05.

family

String character. Name of the family confidence envelope to compute the critical vector from"simes","aorc","beta","higher.criticism", and"power".Default to "simes".

delta

Numeric value.\delta value. Please see the reference below. Default to 0.

B

Numeric value. Number of permutations, default to 1000.

pvalues

Matrix ofp-values with dimensionsm \times B wherem is the number of variables andB the number of permutations used instead of the data matrixX. Default to NULL.

test.type

Character string. Choose a type of tests among"one_sample", i.e., one-sample t-tests, or"two_samples", i.e., two-samples t-tests. Default"one_sample".

complete

Boolean value. IfTRUE the sets of critical vectors and the rawp-values are returned. Default toFALSE.

clusters

Boolean value. Ifix indicates many clusters/sets must beTRUE. Default @FALSE.

iterative

Boolean value. Ifiterative = TRUE, the iterative method is applied (computationally demanding). Default toFALSE. Please see the reference below.

approx

Boolean value. Default toTRUE. If you are analyzing high dimensional data, we suggest to putapprox = TRUE to speed up the computation time. Please see the reference below.

ncomb

Numeric value. Ifapprox = TRUE, you must decide how many random sub collections (level of approximation) considered. Default to 100.

step.down

Boolean value. Default toFALSE If you want to compute the lambda calibration parameter using the step-down approach putTRUE. Please see the reference below.

max.step

Numeric value. Default to 10. Maximum number of steps for the step down approach, so useful whenstep.down = TRUE.

...

Further arguments

Value

by default returns a list with the following objects:

discoveries: lower bound for the number of true discoveries in the set selected
ix: selected variables

Ifcomplete = TRUE the rawpvalues andcv critical vector are also returned.

Author(s)

Angela Andreella

References

For the general framework of All-Resolutions Inference see:

Goeman, Jelle J., and Aldo Solari. "Multiple testing for exploratory research." Statistical Science 26.4 (2011): 584-597.

For permutation-based All-Resolutions Inference see:

Examples

datas <- simulateData(pi0 = 0.8, m = 1000, n = 30, power = 0.9, rho = 0,seed = 123)out <- pARI(X = datas, ix = c(1:200),test.type = "one_sample")out

Permutation-based All-Resolutions Inference for brain imaging.

Description

Usage

pARIbrain(copes, thr=NULL, mask=NULL, alpha=.05, clusters = NULL, alternative = "two.sided", summary_stat=c("max", "center-of-mass"),silent=FALSE, family = "simes", delta = 0, B = 1000, rand = FALSE, iterative = FALSE, approx = TRUE, ncomb = 100, step.down = FALSE, max.step = 10, ...)

Arguments

copes

List of NIfTI file. The list of copes, i.e., contrasts maps, one for each subject used to compute the statistical tests.

thr

Numeric value. Threshold used to construct the cluster map. Default toNULL.

mask

alpha

Numeric value in '[0,1]'.\alpha level to control the family-wise error rate. Default to 0.05.

clusters

NIfTI file or character string. 3D array of cluster ids (0 when voxel does not belong to any cluster) or a (character) NIfTI file name. Ifcluster=NULL the cluster map is computed by thecluster_threshold function with threshold equalsthr.

alternative

Character string. It refers to the alternative hypothesis, must be one of"two.sided" (default),"greater" or"lower".

summary_stat

Character string. Choose among=c("max", "center-of-mass").

silent

Boolean value. Default toFALSE. IfTRUE the function prints the results.

family

String character. Name of the family confidence envelope to compute the critical vector from"simes","aorc","beta","higher.criticism", and"power".Default to "simes".

delta

Numeric value.\delta value. Please see the reference below. Default to 0.

B

Numeric value. Number of permutations, default to 1000.

rand

Boolean value. Default toFALSE. Ifrand = TRUE, thep-values are computed byrowRanks. Please seesignTest

iterative

Boolean value. Ifiterative = TRUE, the iterative method is applied (computationally demanding). Default toFALSE. Please see the reference below.

approx

Boolean value. Default toTRUE. If you are analyzing high dimensional data, we suggest to putapprox = TRUE to speed up the computation time. Please see the reference below.

ncomb

Numeric value. Ifapprox = TRUE, you must decide how many random sub collections (level of approximation) considered. Default to 100.

step.down

Boolean value. Default toFALSE If you want to compute the lambda calibration parameter using the step-down approach putTRUE. Please see the reference below.

max.step

Numeric value. Default to 10. Maximum number of steps for the step down approach, so useful whenstep.down = TRUE.

...

further arguments. SeesignTest.

Value

A list with elements:

out: Data.frame containing the size, the number of false null hypotheses, the number of true null hypotheses, the lower bound for the true discovery proportion, and other statistics for each cluster.
clusters: Matrix describing the clusters analyzed.

Author(s)

Angela Andreella

References

For the general framework of All-Resolutions Inference see:

Goeman, Jelle J., and Aldo Solari. "Multiple testing for exploratory research." Statistical Science 26.4 (2011): 584-597.

For All-Resolutions Inference for functional Magnetic Resonance Imaging data see:

Rosenblatt, Jonathan D., et al. "All-resolutions inference for brain imaging." Neuroimage 181 (2018): 786-796.

For permutation-based All-Resolutions Inference see:

Examples

## Not run: library(remotes)install_github("angeella/fMRIdata")library(fMRIdata)data(Auditory_clusterTH3_2)data(Auditory_copes)data(Auditory_mask)auditory_out <- pARIbrain(copes = Auditory_copes, clusters = Auditory_clusterTH3_2, mask = Auditory_mask, alpha = 0.05, silent = TRUE)auditory_out$out## End(Not run)

Permutation-based All-Resolutions Inference for Gene Expression Data

Description

This function computes the lower bound for the number of true discoveries within each cluster (pathways) of Gene Expression Data.

Usage

pARIgene(X= NULL, pathways, alpha = 0.05, family = "simes", delta = 0, B = 1000, test.type = "one_sample", complete = FALSE, iterative = FALSE, approx = TRUE, ncomb = 100, step.down = FALSE, max.step = 10, ...)

Arguments

X

Data matrix where rows represent them variables and columns then observations.

pathways

List of pathways where names indicates the name of the pathway.

alpha

Numeric value in '[0,1]'.\alpha level to control the family-wise error rate. Default to 0.05.

family

String character. Name of the family confidence envelope to compute the critical vector from"simes","aorc","beta","higher.criticism", and"power".Default to "simes".

delta

Numeric value.\delta value. Please see the reference below. Default to 0.

B

Numeric value. Number of permutations, default to 1000.

test.type

Character string. Choose a type of tests among"one_sample", i.e., one-sample t-tests, or"two_samples", i.e., two-samples t-tests. Default"one_sample".

complete

Boolean value. IfTRUE the sets of critical vectors and the rawp-values are returned. Default toFALSE.

iterative

Boolean value. Ifiterative = TRUE, the iterative method is applied (computationally demanding). Default toFALSE. Please see the reference below.

approx

Boolean value. Default toTRUE. If you are analyzing high dimensional data, we suggest to putapprox = TRUE to speed up the computation time. Please see the reference below.

ncomb

Numeric value. Ifapprox = TRUE, you must decide how many random sub collections (level of approximation) considered. Default to 100.

step.down

Boolean value. Default toFALSE If you want to compute the lambda calibration parameter using the step-down approach putTRUE. Please see the reference below.

max.step

Numeric value. Default to 10. Maximum number of steps for the step down approach, so useful whenstep.down = TRUE.

...

Further arguments

Value

by default returns a list with the following objects:

discoveries: lower bound for the number of true discoveries in the set selected
ix: selected variables

Ifcomplete = TRUE the rawpvalues andcv critical vector are also returned.

Author(s)

Angela Andreella

References

For the general framework of All-Resolutions Inference see:

Goeman, Jelle J., and Aldo Solari. "Multiple testing for exploratory research." Statistical Science 26.4 (2011): 584-597.

For permutation-based All-Resolutions Inference see:

Permutation Test

Description

Performs permutation-based two-sample t-tests.

Usage

permTest(X, B = 1000, alternative = "two.sided", seed = NULL, mask = NULL, rand = FALSE, label = NULL)

Arguments

X

Data matrix where rows represent them variables and columns then observations.

B

Numeric value. Number of permutations, default to 1000.

alternative

Character string. It refers to the alternative hypothesis, must be one of"two.sided" (default),"greater" or"lower".

seed

Integer value. If you want to specify the seed. Default to toNULL

mask

rand

Boolean value. Default toFALSE. Ifrand = TRUE, thep-values are computed byrowRanks.

label

Numeric/character vector. Labels of the observations, ifNULL the columns's name are considered. Default toNULL.

Value

Returns a list with the following objects:

Test: Vector with length equalsm. Observed two-samples t-tests, one for eachm variable
Test_H0: Matrix with dimensionsm \times B-1. Test statistics under the null hypothesis
pv: Vector with length equalsm. Observedp-values, one for eachm variable
pv_H0: Matrix with dimensionsm \times B-1.p-values under the null hypothesis

Author(s)

Angela Andreella

Examples

X <- matrix(rnorm(100*20), ncol=20)X[,1:10] <- X[,1:10] + rnorm(100*10, mean = 5)out <- permTest(X = X, alternative = "two.sided", label = c(rep(1,10),rep(0,10)))

Plot permutation`p`-values distribution

Description

Create a plot of permutation-basedp-values with corresponding specified critical vectors.

Usage

plotNullDistribution(P=NULL,family="simes",alpha = 0.05, path = getwd(), name = "plot", delta = 0,copes=NULL,mask=NULL, alternative = "two.sided", rand = FALSE, B = 1000)

Arguments

P

Matrix ofp-values with dimensionsm \times B wherem is the number of variables andB the number of permutations used instead of the data matrixX. Default toNULL.

family

String character. Name of the family confidence envelope to compute the critical vector from"simes","aorc","beta","higher.criticism", and"power".Default to "simes". If more than one critical vector are considered, it must be a vector.

alpha

Numeric value in '[0,1]'.\alpha level to control the family-wise error rate. Default to 0.05.

path

Character string. Path to save the plot. The path does not must end with/. Default togetwd().

name

Character string. The name of file that will be used to save the plot. Default to "plot".

delta

Numeric value.\delta value. Please see the reference below. Default to 0. If more than one critical vector are considered,delta must be a vector having length equals to the length of the vector specified infamily.

copes

List of NIfTI file. The list of copes, i.e., contrasts maps, one for each subject used to compute the statistical tests.

mask

alternative

Character string. It refers to the alternative hypothesis, must be one of"two.sided" (default),"greater" or"lower".

rand

Boolean value. Default toFALSE. Ifrand = TRUE, thep-values are computed byrowRanks.

B

Numeric value. Number of permutations, default to 1000.

Value

Save a plot inpath with name specified inname describing thep-values null distribution with critical value curve and observedp-values in red.

Author(s)

Angela Andreella

References

Examples

## Not run: db <- simulateData(pi0 = 0.8, m = 100, n = 20, rho = 0)out <- signTest(X = db)pv <- cbind(out$pv, out$pv_H0)plotNullDistribution(P = pv)## End(Not run)

Permutatation-based one-sample t-tests

Description

Performs sign-flipped one-sample t-tests.

Usage

signTest(X, B = 1000, alternative = "two.sided", seed = NULL, mask = NULL, rand = FALSE)

Arguments

X

Data matrix where rows represent them variables and columns then observations.

B

Numeric value. Number of permutations, default to 1000.

alternative

Character string. It refers to the alternative hypothesis, must be one of"two.sided" (default),"greater" or"lower".

seed

Integer value. If you want to specify the seed. Default to toNULL

mask

rand

Boolean value. Default toFALSE. Ifrand = TRUE, thep-values are computed byrowRanks.

Value

Returns a list with the following objects:

Test: Vector with length equalsm. Observed two-samples t-tests, one for eachm variable
Test_H0: Matrix with dimensionsm \times B-1. Test statistics under the null hypothesis
pv: Vector with length equalsm. Observedp-values, one for eachm variable
pv_H0: Matrix with dimensionsm \times B-1.p-values under the null hypothesis

Author(s)

Angela Andreella

Examples

X <- matrix(rnorm(100*20), ncol=20)out <- signTest(X = X, alternative = "two.sided")

simulate normal distributed data

Description

Simulate normal distributed data.

Usage

simulateData(pi0,m,n, rho, seed = NULL, power = 0.8, alpha = 0.05)

Arguments

pi0

Numeric value in '[0,1]'. Proportion of true null hypothesis.

m

Numeric value. Number of variables.

n

Numeric value. Number of observations.

rho

Numeric value in '[0,1]'. Level of equi-correlation between pairs of variables.

seed

Integer value. If you want to specify the seed. Default to toNULL

power

Numeric value in '[0,1]'. Level of power. Default to 0.8.

alpha

Numeric value in '[0,1]'.\alpha level to control the family-wise error rate. Default to 0.05.

Value

Returns a matrix with dimensionsm \times n.

Author(s)

Angela Andreella

simulate normal distributed data

Description

Simulate normal distributed data with spatial correlation structure

theta (\theta) describes how rapidly the correlation declines with respect to the distance between two voxels.The three-dimensional coordinates of the voxels are defined as all combinationsof vectorc = (1, \dots, m1/3), then\Sigma_\theta = \exp(-\theta K) whereK is the matrix containing theeuclidean distances between the three-dimensional coordinates' voxels.So,m^{1/3} must be an integer value.

Usage

simulateSpatialData(pi0,m,n, theta, seed = NULL, power = 0.8, alpha = 0.05)

Arguments

pi0

Numeric value in '[0,1]'. Proportion of true null hypothesis.

m

Numeric value. Number of variables.

n

Numeric value. Number of observations.

theta

Numeric value in '[0,1]'. Level of correlation between pairs of variables. See details

seed

Integer value. If you want to specify the seed. Default to toNULL

power

Numeric value in '[0,1]'. Level of power. Default to 0.8.

alpha

Numeric value in '[0,1]'.\alpha level to control the family-wise error rate. Default to 0.05.

Value

Returns a matrix with dimensionsm \times n.

Author(s)

Angela Andreella

Movatterモバイル変換

Create Statistical Parametric Mapping (SPM)

Description

Usage

Arguments

Value

Author(s)

Examples

Critical vector

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Lower bound for the number of true discoveries

Description

Usage

Arguments

Value

Author(s)

References

Examples

Lambda calibration

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

True Discovery Proportion brain map

Description

Usage

Arguments

Value

Author(s)

Permutation-based All-Resolutions Inference

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Permutation-based All-Resolutions Inference for brain imaging.

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

Permutation-based All-Resolutions Inference for Gene Expression Data

Description

Usage

Arguments

Value

Author(s)

References

See Also

Permutation Test

Description

Usage

Arguments

Value

Author(s)

Examples

Plot permutationp-values distribution

Description

Usage

Arguments

Value

Author(s)

References

Plot permutation`p`-values distribution