# delta: Compute univariate MDMR effect sizes In MDMR: Multivariate Distance Matrix Regression

## Description

`delta` computes permutation-based effect sizes on individual items comprising the distance matrix outcome used in multivariate distance matrix regression. It returns the omnibus estimates of delta (i.e. effect size of the entire design matrix on each outcome) as well as estimates of each pair-wise effect size (i.e. the effect of each predictor on each outcome variable, conditional on the rest of the predictors).

## Usage

 ```1 2 3``` ```delta(X, Y = NULL, dtype = NULL, niter = 10, x.inds = NULL, y.inds = NULL, G = NULL, G.list = NULL, ncores = 1, seed = NULL, plot.res = F, grayscale = F, cex = 1, y.las = 2) ```

## Arguments

 `X` A n x p matrix or data frame of predictors. Unordered factors will be tested with contrast-codes by default, and ordered factors will be tested with polynomial contrasts. For finer control of how categorical predictors are handled, or if higher-order effects are desired, the output from a call to `model.matrix()` can be supplied to this argument as well. `Y` Outcome data: n x q matrix of scores along the dependent variables. `dtype` Measure of dissimilarity that will be used by `dist` to compute the distance matrix based on `Y`. As is the case when calling `dist` directly, this must be one of `"euclidean"`, `"maximum"`, `"manhattan"`, `"canberra"`, `"binary"` or `"minkowski"`, and unambiguous substring can be given. `niter` Number of times to permute each outcome item in the procedure to compute delta. The final result is the average of all `niter` iterations. Higher values of `niter` require more computation time, but result in more precise estimates. `x.inds` Vector indicating which columns of X should have their conditional effect sizes computed. Default value of `NULL` results in all effects being computed, and a value of `0` results in no conditional effects being computed, such that only the omnibus effect sizes will be reported. `y.inds` Vector indicating which columns of Y effect sizes should be computed on. Default value of `NULL` results in all columns being used. `G` Gower's centered similarity matrix computed from `D`. Either `D` or `G` must be passed to `mdmr()`. `G.list` List of length q where the i^{th} element contains the `G` matrix computed from distance a matrix that was computed on a version of `Y` where the i^{th} column has been randomly permuted. `ncores` Integer; if `ncores` > 1, the `parallel` package is used to speed computation. Note: Windows users must set `ncores = 1` because the `parallel` pacakge relies on forking. See `mc.cores` in the `mclapply` function in the `parallel` pacakge for more details. `seed` Integer; sets seed for the permutations of each variable comprising Y so that results can be replicated. `plot.res` Logical; Indicates whether or not a heat-map of the results should be plotted. `grayscale` Logical; Indicates whether or not the heat-map should be plotted in grayscale. `cex` Multiplier for cex.axis, cex.lab, cex.main, and cex that are passed to the plotted result. `y.las` Orientation of labels for the outcome items. Defaults to vertical (2). Value of 1 prints horizontal labels, and is only recommended if the multivariate outcome is comprised of few variables.

## Details

See McArtor et al. (2017) for a detailed description of how delta is computed. Note that it is a relative measure of effect, quantifying which effects are strong (high values of delta) and weak (low values of delta) within a single analysis, but estimates of delta cannot be directly compared across different datasets.

There are two options for using this function. The first option is to specify the predictor matrix `X`, the outcome matrix `Y`, the distance type `dtype` (supported by "dist" in R), and number of iterations `niter`. This option conducts the permutation of each Y-item `niter` times (to average out random association in each permutation) and reports the median estimates of delta over the `niter` reps.

The second option is to specify `X`, `G`, and `G.list`, a list of G matrices where the permutation has already been done for each item comprising Y. The names of the elements in `G.list` should correspond to the names of the variables that were permuted. This option is implemented so that delta can be computed when MDMR is being used in conjunction with distance metrics not supported by `dist`.

## Value

A data frame whose rows correspond to the omnibus effects and the effect of each individual predictor (conditional on the rest), and whose columns correspond to each outcome variable whose effect sizes are being quantified. If `plot.res = TRUE`, a heat-map is plotted of this data frame to easily identify the strongest effects. Note that the heatmap is partitioned into the omnibus effect (first row) and pair-wise effects (remaining rows), because otherwise the omnibus effect would dominate the heatmap.

## Author(s)

Daniel B. McArtor ([email protected]) [aut, cre]

## References

McArtor, D. B., Lubke, G. H., & Bergeman, C. S. (2017). Extending multivariate distance matrix regression with an effect size measure and the distribution of the test statistic. Psychometrika, 82, 1052-1077.

## Examples

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16``` ```data(mdmrdata) # --- Method 1 --- # delta(X.mdmr, Y = Y.mdmr, dtype = "euclidean", niter = 1, seed = 12345) # --- Method 2 --- # D <- dist(Y.mdmr, method = "euclidean") G <- gower(D) q <- ncol(Y.mdmr) G.list <- vector(mode = "list", length = q) names(G.list) <- names(Y.mdmr) for(i in 1:q) { Y.shuf <- Y.mdmr Y.shuf[,i] <- sample(Y.shuf[,i]) G.list[[i]] <- gower(dist(Y.shuf, method = "euclidean")) } delta(X.mdmr, G = G, G.list = G.list) ```

MDMR documentation built on Feb. 15, 2018, 1:02 a.m.