Help for package pARI

Type:

Package

Title:

Permutation-Based All-Resolutions Inference

Version:

1.1.2

Date:

2024-09-06

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:

2024-09-06 13:57:08 UTC; Andreella

Author:

Angela Andreella

[aut, cre] (Main author)

Maintainer:

Angela Andreella <angela.andreella@unive.it>

Repository:

CRAN

Date/Publication:

2024-09-06 18:50:06 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 to getwd().

name

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

Pmap

Boolean value. If TRUE the SPM of the p-values is returned. Default to FALSE.

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. If mask=NULL, it is assumed that none of the voxels have to be excluded.

Value

Save the Statistical Parametric Mapping Nifti file in path with name specified in name.

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 dimensions m \times B used instead of the data matrix X. Default to NULL.

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 by lambdaOpt. Default to 1.

delta

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

m

Numeric value. Number of hypothesis. Default to NULL.

Value

Numeric vector. Critical vector curve with length m.

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 by criticalVector.

pvalues

If iterative = TRUE you must put here the matrix of p-values with dimensions m \times B where m is the number of variables and B the number of permutations. Instead, if iterative = FALSE, you can put directly the vector of m observed p-values.

iterative

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

approx

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

ncomb

Numeric value. If approx = 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 cluster ix 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 vector criticalVector.

Usage

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

Arguments

pvalues

Matrix of p-values with dimensions m \times B where m is the number of variables and B the number of permutations used instead of the data matrix X. Default to NULL.

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 to FALSE If you want to compute the lambda calibration parameter using the step-down approach put TRUE. Please see the reference below.

max.step

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

m

Numeric value. Number of hypotheses. Default to NULL.

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 by pARIbrain.

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 the path specified the true discovery proportion NIfTI map with name specified in name.

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 the p-values permutation distribution. The function computes simultaneous lower bounds for the number of true discoveries for each set of hypotheses specified in ix controlling family-wise error rate at level alpha.

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 the m variables and columns the n observations.

ix

Numeric vector which expresses the set of hypotheses of interest. It can be a vector with length equals m indicating the corresponding cluster for each variable, (in this case, you must put clusters = 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 of p-values with dimensions m \times B where m is the number of variables and B the number of permutations used instead of the data matrix X. 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. If TRUE the sets of critical vectors and the raw p-values are returned. Default to FALSE.

clusters

Boolean value. If ix indicates many clusters/sets must be TRUE. Default @FALSE.

iterative

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

approx

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

ncomb

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

step.down

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

max.step

Numeric value. Default to 10. Maximum number of steps for the step down approach, so useful when step.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

If complete = TRUE the raw pvalues and cv 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 to NULL.

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. If cluster=NULL the cluster map is computed by the cluster_threshold function with threshold equals thr.

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 to FALSE. If TRUE 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 to FALSE. If rand = TRUE, the p-values are computed by rowRanks. Please see signTest

iterative

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

approx

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

ncomb

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

step.down

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

max.step

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

...

further arguments. See signTest.

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 the m variables and columns the n 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. If TRUE the sets of critical vectors and the raw p-values are returned. Default to FALSE.

iterative

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

approx

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

ncomb

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

step.down

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

max.step

Numeric value. Default to 10. Maximum number of steps for the step down approach, so useful when step.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

If complete = TRUE the raw pvalues and cv 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 the m variables and columns the n 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 to NULL

mask

rand

Boolean value. Default to FALSE. If rand = TRUE, the p-values are computed by rowRanks.

label

Numeric/character vector. Labels of the observations, if NULL the columns's name are considered. Default to NULL.

Value

Returns a list with the following objects:

Test: Vector with length equals m. Observed two-samples t-tests, one for each m variable
Test_H0: Matrix with dimensions m \times B-1. Test statistics under the null hypothesis
pv: Vector with length equals m. Observed p-values, one for each m variable
pv_H0: Matrix with dimensions m \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-based p-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 of p-values with dimensions m \times B where m is the number of variables and B the number of permutations used instead of the data matrix X. Default to NULL.

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 to getwd().

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 in family.

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 to FALSE. If rand = TRUE, the p-values are computed by rowRanks.

B

Numeric value. Number of permutations, default to 1000.

Value

Save a plot in path with name specified in name describing the p-values null distribution with critical value curve and observed p-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 the m variables and columns the n 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 to NULL

mask

rand

Boolean value. Default to FALSE. If rand = TRUE, the p-values are computed by rowRanks.

Value

Returns a list with the following objects:

Test: Vector with length equals m. Observed two-samples t-tests, one for each m variable
Test_H0: Matrix with dimensions m \times B-1. Test statistics under the null hypothesis
pv: Vector with length equals m. Observed p-values, one for each m variable
pv_H0: Matrix with dimensions m \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 to NULL

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 dimensions m \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 combinations of vector c = (1, \dots, m1/3), then \Sigma_\theta = \exp(-\theta K) where K is the matrix containing the euclidean 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 to NULL

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 dimensions m \times n.

Author(s)

Angela Andreella

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 permutation p-values distribution

Description

Usage

Arguments

Value

Author(s)

References

Examples

Plot permutation `p`-values distribution