Conduct MDMR with analytic pvalues
Description
mdmr
(multivariate distance matrix regression) is used to regress a
distance matrix onto a set of predictors. It returns the test statistic,
pseudo Rsquare statistic, and analytic pvalues for all predictors
jointly and for each predictor individually, conditioned on the rest.
Usage
1 2 3 
Arguments
X 
A n x p matrix or data frame of predictors. Unordered factors
will be tested with contrastcodes by default, and ordered factors will be
tested with polynomial contrasts. For finer control of how categorical
predictors are handled, or if higherorder effects are desired, the output
from a call to 
D 
Distance matrix computed on the outcome data. Can be either a
matrix or an R 
G 
Gower's centered similarity matrix computed from 
lambda 
Optional argument: Eigenvalues of 
return.lambda 
Logical; indicates whether or not the eigenvalues of

start.acc 
Starting accuracy of the Davies (1980) algorithm
implemented in the 
ncores 
Integer; if 
perm.p 
Logical: should permutationbased pvalues be computed instead
of analytic pvalues? Default behavior is 
nperm 
Number of permutations to use if permutationbased pvalues are to be computed. 
seed 
Random seed to use to generate the permutation null distribution. Defaults to a random seed. 
Details
This function is the fastest approach to conducting MDMR. It uses the fastest known computational strategy to compute the MDMR test statistic (see Appendix A of McArtor et al., second revision under review), and it uses fast, analytic pvalues.
The slowest part of conducting MDMR is now the necessary eigendecomposition
of the G
matrix, whose computation time is a function of
n^3. If MDMR is to be conducted multiple times on the same
distance matrix, it is recommended to compute eigenvalues of G
in
advance and pass them to the function rather than computing them every
time mdmr
is called, as is the case if the argument lambda
is left NULL
.
The distance matrix D
can be passed to mdmr
as either a
distance object or a symmetric matrix.
Value
An object with six elements and a summary function. Calling
summary(mdmr.res)
produces a data frame comprised of:
Statistic 
Value of the corresponding MDMR test statistic 
Numer DF 
Numerator degrees of freedom for the corresponding effect 
Pseudo R2 
Size of the corresponding effect on the distance matrix 
pvalue 
The pvalue for each effect. 
In addition to the information in the three columns comprising
summary(res)
, the res
object also contains:
p.prec 
A data.frame reporting the precision of each pvalue. If
analytic pvalues were computed, these are the maximum error bound of the
pvalues reported by the 
lambda 
A vector of the eigenvalues of 
nperm 
Number of permutations used. Will read 
Note that the printed output of summary(res)
will truncate pvalues
to the smallest trustworthy values, but the object returned by
summary(res)
will contain the pvalues as computed. The reason for
this truncation differs for analytic and permutation pvalues. For an
analytic pvalue, if the error bound of the Davies algorithm is larger than
the pvalue, the only conclusion that can be drawn with certainty is that
the pvalue is smaller than (or equal to) the error bound. For a permutation
test, the estimated pvalue will be zero if no permuted test statistics are
greater than the observed statistic, but the zero pvalue is only a product
of the finite number of permutations conduted. The only conclusion that can
be drawn is that the pvalue is smaller than 1/nperm
.
Author(s)
Daniel B. McArtor (dmcartor@nd.edu) [aut, cre]
References
Davies, R. B. (1980). The Distribution of a Linear Combination of chisquare Random Variables. Journal of the Royal Statistical Society. Series C (Applied Statistics), 29(3), 323333.
Duchesne, P., & De Micheaux, P. L. (2010). Computing the distribution of quadratic forms: Further comparisons between the LiuTangZhang approximation and exact methods. Computational Statistics and Data Analysis, 54(4), 858862.
McArtor, D. B., Lubke, G. H., & Bergeman, C. S. (second revision under review). Extending multivariate distance matrix regression with an effect size measure and the distribution of the test statistic.
Examples
1 2 3 4 5 6 7 8 9 10 11 