permutation_power: Power calculation for the permutation test
In astamm/fdahotelling: Inference for Functional Data Analysis in R

Description Usage Arguments Details Value See Also Examples

permutation_power computes an estimate of the statistical power of permutation-based test on the mean function (or on the difference between mean functions) using Monte-Carlo simulations.

1
2
3

permutation_power(mu1 = 0, Sigma = diag(length(mu1)), n1 = 10L,
  n2 = NULL, MC = 1000L, alpha = 0.05, paired = FALSE, step_size = 0,
  B = 1000L, statistic = "Hotelling", mc.cores = 1L)

`mu1`	True mean function or difference between mean functions (default: 0).
`Sigma`	True covariance matrix Σ (default: 1).
`n1`	Sample size of data pertaining to the 1st population (default: 10).
`n2`	Sample size of data pertaining to the 2nd population (default: `NULL`).
`MC`	Number of Monte-Carlo runs to estimate statistical power (default: 1000).
`alpha`	Significance level (default: 0.05).
`paired`	Is the input data paired? (default: `FALSE`).
`step_size`	The step size used to perform integral approximation via the method of rectangles (default: `0`). When set to `0`, it assumes that we are dealing with multivariate data rather than functional data and thus no integration is necessary.
`B`	Number of bootstrap permutations (default: 1000).
`statistic`	Statistic to be used within the permutation framework. Choices are Hotelling (default), L1, L2, Linf, StandardizedL1, StandardizedL2, StandardizedLinf and All.
`mc.cores`	Number of cores to run the estimation on (default: 1).

This function computes the statistical power of permutation-based tests using a set of user-specified statistics. The power calculation relies on a specific generative model. It is assumed that data is generated from a Gaussian distribution. The user-defined inputs are

mu1: a numeric vector containing the actual mean function of the distribution (or difference between mean functions) evaluated in a pointwise fashion on a uniform grid.
Sigma: a numeric matrix containing the actual covariance kernel of the distribution (or pooled covariance kernel) evaluated in a pointwise fashion on a uniform grid.

An estimate of the statistical power of the test.

The underlying statistical test is described in details in the technical report by Pini, A., Stamm, A., & Vantini, S. (2015). Hotelling T^2 in functional Hilbert spaces, available online at https://mox.polimi.it/publication-results/?id=524&tipo=add_qmox.

# Set the sample sizes for a two-sample test
n1 <- 10
n2 <- 10
# Set the dimensionality for curve approximation
p <- 100
# Set the actual covariance kernel
Sigma <- diag(1, p)
#----------------------------------------------------------------------------
# The following lines of code computes the actual significance level of the
# test and runs in about 1 minute on a single core. Computation time is
# linear in the number of cores and does not depend on the statistic or the
# number of statistics used in the testing procedure.
mu1 <- rep(0, p)
permutation_power(mu1, Sigma, n1, n2, MC = 100, B = 250)
#----------------------------------------------------------------------------
# Usually, it is recommended to set MC = 1000 and B = 1000, which would take
# about 40 minutes. However, this function is parallelized and can be run on
# multiple cores by setting the optional argument mc.cores to a suitable
# integer. On a computer with 4 physical cores, the following lines of code
# runs in about 10 minutes:
## Not run: 
mu1 <- rep(0, p)
permutation_power(mu1, Sigma, n1, n2, MC = 1000, B = 1000, mc.cores = 4)

## End(Not run)
#----------------------------------------------------------------------------
# We can use more complex covariance matrices and compute an estimate of the
# statistical power of the test for a given non-null mean difference.
## Not run: 
mu1 <- rep(4, p)
s <- seq(-1, 1, length.out = 100)
Sigma <- outer(s, s, function(t, s) exp(-abs(t - s)))
permutation_power(mu1, Sigma, n1, n2, MC = 1000, B = 1000, mc.cores = 4)

## End(Not run)