mgc (version 2.0.2)

discr.test.one_sample: Discriminability One Sample Permutation Test

Description

A function that performs a one-sample test for whether the discriminability differs from random chance.

Usage

discr.test.one_sample(
  X,
  Y,
  is.dist = FALSE,
  dist.xfm = mgc.distance,
  dist.params = list(method = "euclidean"),
  dist.return = NULL,
  remove.isolates = TRUE,
  nperm = 500,
  no_cores = 1
)

Arguments

X

is interpreted as:

a [n x d] data matrix

X is a data matrix with n samples in d dimensions, if flag is.dist=FALSE.

a [n x n] distance matrix

X is a distance matrix. Use flag is.dist=TRUE.

Y

[n] a vector containing the sample ids for our n samples.

is.dist

a boolean indicating whether your X input is a distance matrix or not. Defaults to FALSE.

dist.xfm

if is.dist == FALSE, a distance function to transform X. If a distance function is passed, it should accept an [n x d] matrix of n samples in d dimensions and return a [n x n] distance matrix as the $D return argument. See mgc.distance for details.

dist.params

a list of trailing arguments to pass to the distance function specified in dist.xfm. Defaults to list(method='euclidean').

dist.return

the return argument for the specified dist.xfm containing the distance matrix. Defaults to FALSE.

is.null(dist.return)

use the return argument directly from dist.xfm as the distance matrix. Should be a [n x n] matrix.

is.character(dist.return) | is.integer(dist.return)

use dist.xfm[[dist.return]] as the distance matrix. Should be a [n x n] matrix.

remove.isolates

remove isolated samples from the dataset. Isolated samples are samples with only one instance of their class appearing in the Y vector. Defaults to TRUE.

nperm

the number of permutations to perform. Defaults to 500.

no_cores

the number of cores to use for permutation test. Defaults to 1.

Value

A list containing the following:

stat

the discriminability of the data.

null

the discriminability scores under the null, computed via permutation.

p.value

the pvalue associated with the permutation test.

Details

Performs a test of whether an observed discriminability is significantly different from chance, as described in Bridgeford et al. (2019). With \(\hat D_X\) the sample discriminability of \(X\): $$H_0: D_X = D_0$$ and:$$H_A: D_X > D_0$$ where \(D_0\) is the discriminability that would be observed by random chance.

References

Eric W. Bridgeford, et al. "Optimal Decisions for Reference Pipelines and Datasets: Applications in Connectomics." Bioarxiv (2019).

Examples

# NOT RUN {
require(mgc)
n = 100; d=5

# simulation with a large difference between the classes
# meaning they are more discriminable
sim <- discr.sims.linear(n=n, d=d, K=2, signal.lshift=10)
X <- sim$X; Y <- sim$Y

# p-value is small
discr.test.one_sample(X, Y)$p.value
# }