mgc.test: MGC Permutation Test
In mgc: Multiscale Graph Correlation

Description Usage Arguments Value Details Author(s) References Examples

Test of Dependence using MGC Approach.

mgc.test(
  X,
  Y,
  is.dist.X = FALSE,
  dist.xfm.X = mgc.distance,
  dist.params.X = list(method = "euclidean"),
  dist.return.X = NULL,
  is.dist.Y = FALSE,
  dist.xfm.Y = mgc.distance,
  dist.params.Y = list(method = "euclidean"),
  dist.return.Y = NULL,
  nperm = 1000,
  option = "mgc",
  no_cores = 1
)

`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.X=FALSE`. a `[n x n]` distance matrix X is a distance matrix. Use flag `is.dist.X=TRUE`.
`Y`	is interpreted as: a `[n x d]` data matrix Y is a data matrix with `n` samples in `d` dimensions, if flag `is.dist.Y=FALSE`. a `[n x n]` distance matrix Y is a distance matrix. Use flag `is.dist.Y=TRUE`.
`is.dist.X`	a boolean indicating whether your `X` input is a distance matrix or not. Defaults to `FALSE`.
`dist.xfm.X`	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.X`	a list of trailing arguments to pass to the distance function specified in `dist.xfm.X`. Defaults to `list(method='euclidean')`.
`dist.return.X`	the return argument for the specified `dist.xfm.X` 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.X[[dist.return]]` as the distance matrix. Should be a `[n x n]` matrix.
`is.dist.Y`	a boolean indicating whether your `Y` input is a distance matrix or not. Defaults to `FALSE`.
`dist.xfm.Y`	if `is.dist == FALSE`, a distance function to transform `Y`. 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 `dist.return.Y` return argument. See mgc.distance for details.
`dist.params.Y`	a list of trailing arguments to pass to the distance function specified in `dist.xfm.Y`. Defaults to `list(method='euclidean')`.
`dist.return.Y`	the return argument for the specified `dist.xfm.Y` containing the distance matrix. Defaults to `FALSE`. `is.null(dist.return)` use the return argument directly from `dist.xfm.Y(Y)` as the distance matrix. Should be a `[n x n]` matrix. `is.character(dist.return) \| is.integer(dist.return)` use `dist.xfm.Y(Y)[[dist.return]]` as the distance matrix. Should be a `[n x n]` matrix.
`nperm`	specifies the number of replicates to use for the permutation test. Defaults to `1000`.
`option`	is a string that specifies which global correlation to build up-on. Defaults to `'mgc'`. `'mgc'` use the MGC global correlation. `'dcor'` use the dcor global correlation. `'mantel'` use the mantel global correlation. `'rank'` use the rank global correlation.
`no_cores`	the number of cores to use for the permutations. Defaults to `1`.

A list containing the following:

`p.value`	P-value of MGC
`stat`	is the sample MGC statistic within `[-1,1]`
`p.localCorr`	P-value of the local correlations by double matrix index.
`localCorr`	the local correlations
`optimalScale`	the optimal scale identified by MGC
`option`	specifies which global correlation was used

A test of independence using the MGC approach, described in Vogelstein et al. (2019). For X ~ Fx, Y ~ Fy:

H0: Fx != Fy

and:

Ha: Fx = Fy

Note that one should avoid report positive discovery via minimizing individual p-values of local correlations, unless corrected for multiple hypotheses.

For details on usage see the help vignette: vignette("mgc", package = "mgc")

Eric Bridgeford and C. Shen

Joshua T. Vogelstein, et al. "Discovering and deciphering relationships across disparate data modalities." eLife (2019).

## Not run: 
library(mgc)

n = 100; d = 2
data <- mgc.sims.linear(n, d)
# note: on real data, one would put nperm much higher (at least 100)
# nperm is set to 10 merely for demonstration purposes
result <- mgc.test(data$X, data$Y, nperm=10)

## End(Not run)