multiFit: Multiscale Multivariate Framework for Independence Tests

In MaStatLab/MultiFit: Multiscale Fisher's Independence Test for Multivariate Dependence

Description

Perform multiscale test of independence for multivariate vectors. See vignettes for further examples.

Usage

multiFit(xy, x = NULL, y = NULL, p_star = NULL, R_max = NULL,
  R_star = 1, rank.transform = TRUE, test.method = "Fisher",
  correct = TRUE, min.tbl.tot = 25L, min.row.tot = 10L,
  min.col.tot = 10L, p.adjust.methods = c("H", "Hcorrected", "MH"),
  compute.all.holm = TRUE, cutoff = 0.05, top.max.ps = 4L,
  return.all.pvs = TRUE, save.all.pvs = FALSE, all.pvs.fname = NULL,
  uv.approx.null = FALSE, uv.exact.null = FALSE,
  uv.null.sim = 10000L, plot.marginals = FALSE, rk = FALSE, M = 10,
  verbose = FALSE)

Arguments

xy	A list, whose first element corresponds to the matrix x as below, and its second element corresponds to the matrix y as below. If xy is not specified, x and y need to be assigned.
x	A matrix, number of columns = dimension of random vector, number of rows = number of observations.
y	A matrix, number of columns = dimension of random vector, number of rows = number of observations.
p_star	Numeric, cuboids associated with tests whose p-value is below p_star will be halved and further tested.
R_max	A positive integer (or Inf), the maximal number of resolutions to scan (algorithm will stop at a lower resolution if all tables in it do not meet the criteria specified at min.tbl.tot, min.row.tot and min.col.tot)
R_star	A positive integer, if set to an integer between 0 and R_max, all tests up to and including resolution R_star will be performed (algorithm will stop at a lower resolution than requested if all tables in it do not meet the criteria specified at min.tbl.tot, min.row.tot and min.col.tot). For higher resolutions only the children of tests with p-value lower than p_star will be considered.
rank.transform	Logical, if TRUE, marginal rank transform is performed on all margins of x and y. If FALSE, all margins are scaled to 0-1 scale. When FALSE, the average and top statistics of the negative logarithm of the p-values are only computed for the univariate case.
test.method	String, choose "Fisher" for Fisher's exact test (slowest), "chi.sq" for Chi-squared test, "LR" for likelihood-ratio test and "norm.approx" for approximating the hypergeometric distribution with a normal distribution (fastest).
correct	Logical, if TRUE compute mid-p corrected p-values for Fisher's exact test, or Yates corrected p-values for the Chi-squared test, or Williams corrected p-values for the likelihood-ratio test.
min.tbl.tot	Non-negative integer, the minimal number of observations per table below which a p-value for a given table will not be computed.
min.row.tot	Non-negative integer, the minimal number of observations for row totals in the 2x2 contingency tables below which a contingency table will not be tested.
min.col.tot	Non-negative integer, the minimal number of observations for column totals in the 2x2 contingency tables below which a contingency table will not be tested.
p.adjust.methods	String, choose between "H" for Holm, "Hcorrected" for Holm with the correction as specified in correct, or "MH" for Modified-Holm (for Fisher's exact test only). See documentation for further details.
compute.all.holm	Logical, if FALSE, only global p-value is computed (may be faster, especially when Modified-Holm correction is used). If TRUE adjusted p-values are computed for all tests.
cutoff	Numerical between 0 and 1, an upper limit for the p-values that are to be adjusted (the lower the cutoff - the fewer computations are required for the Modified Holm method).
top.max.ps	Positive integer, report the mean of the top top.max.ps order statistics of the negative logarithm of all p-values.
return.all.pvs	Logical, if TRUE, a data frame with all p-values is returned.
save.all.pvs	Logical, if TRUE a data frame with all p-values is saved to a RData file named according to all.pvs.fname
all.pvs.fname	String, file name to which all p-values are saved if save.all.pvs is TRUE.
uv.approx.null	Logical, in a univariate case, if TRUE and the testing method is either Fisher's exact test or the normal approximation of the hypergeometric distribution, an approximate null distribution for the global test statistics is simulated. See documentation for further details.
uv.exact.null	Logical, in a univariate case, if TRUE and the testing method is either Fisher's exact test or the normal approximation of the hypergeometric distribution, an exact null distribution for the global test statistics is simulated. See documentation for further details.
uv.null.sim	Positive integer, the number of simulated values to be computed in a univariate case when an exact or approximate null distribution is simulated.
plot.marginals	Logical, if TRUE plots the marginal scatter plots between all pairs of margins of x and y, before and after rank transforming or scaling them.
rk	Logical, if FALSE, select only tests with p-values more extreme than p_star to halve and further test. FWER control guaranteed. If TRUE, choose at each resolution the M tests with the most extreme p-values to further halve and test.
M	A positive integer (or Inf), the number of top ranking tests to continue to split at each resolution. FWER control not guaranteed for this method.
verbose	Logical.

Value

test.stats, a named numerical vector containing the test statistics for the global null hypothesis (i.e. x independent of y)

p.values, a named numerical vector containing the p-values of for the global null hypothesis (i.e. x independent of y). These are not computed if p.adjust.methods is NULL.

pvs, a data frame that contains all p-values and adjusted p-values that are computed. Returned if return.all.pvs is TRUE.

all, a nested list. Each entry is named and contains data about a resolution that was tested. Each resolution is a list in itself, with cuboids, a summary of all tested cuboids in a resolution, tables, a summary of all 2x2 contingency tables in a resolution, pv, a numerical vector containing the p-values from the tests of independence on 2x2 contingency table in tables that meet the criteria defined by min.tbl.tot, min.row.tot and min.col.tot. The length of pv is equal to the number of rows of tables. pv.correct, similar to the above pv, corrected p-values are computed and returned when correct is TRUE. rank.tests, logical vector that indicates whether or not a test was ranked among the top M tests in a resolution. The length of rank.tests is equal to the number of rows of tables. parent.cuboids, an integer vector, indicating which cuboids in a resolution are associated with the ranked tests, and will be further halved in the next higher resolution. parent.tests, a logical vector of the same length as the number of rows of tables, indicating whether or not a test was chosen as a parent test (same tests may have multiple children).

approx.nulls, in a univariate case, a list of numerical vectors whose values are the simulated approximate null values.

exact.nulls, in a univariate case, a list of numerical vectors whose values are the simulated theoretical null values.

Examples

set.seed(1)
n = 300
Dx = Dy = 2
x = matrix(0, nrow=n, ncol=Dx)
y = matrix(0, nrow=n, ncol=Dy)
x[,1] = rnorm(n)
x[,2] = runif(n)
y[,1] = rnorm(n)
y[,2] = sin(5*pi*x[,2]) + 1/5*rnorm(n)
fit = multiFit(x=x, y=y, verbose=TRUE)
w = multiSummary(x=x, y=y, fit=fit, alpha=0.0001)

MaStatLab/MultiFit documentation built on Jan. 11, 2020, 5:11 p.m.