MDMR (version 0.5.2)

delta: Compute univariate MDMR effect sizes

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

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
)

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.

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.

Author

Daniel B. McArtor ([e-mail]) [aut, cre]

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.

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

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)