compute_dmod: Comprehensive d_Mod calculator

View source: R/compute_dmod.R

compute_dmodR Documentation

Comprehensive d_{Mod} calculator

Description

This is a general-purpose function to compute d_{Mod} effect sizes from raw data and to perform bootstrapping. It subsumes the functionalities of the compute_dmod_par (for parametric computations) and compute_dmod_npar (for non-parametric computations) functions and automates the generation of regression equations and descriptive statistics for computing d_{Mod} effect sizes. Please see documentation for compute_dmod_par and compute_dmod_npar for details about how the effect sizes are computed.

Usage

compute_dmod(
  data,
  group,
  predictors,
  criterion,
  referent_id,
  focal_id_vec = NULL,
  conf_level = 0.95,
  rescale_cdf = TRUE,
  parametric = TRUE,
  bootstrap = TRUE,
  boot_iter = 1000,
  stratify = FALSE,
  empirical_ci = FALSE,
  cross_validate_wts = FALSE
)

Arguments

data

Data frame containing the data to be analyzed (if not a data frame, must be an object convertible to a data frame via the as.data.frame() function). The data set must contain a criterion variable, at least one predictor variable, and a categorical variable that identifies the group to which each case (i.e., row) in the data set belongs.

group

Name or column-index number of the variable that identifies group membership in the data set.

predictors

Name(s) or column-index number(s) of the predictor variable(s) in the data set. No predictor can be a factor-type variable. If multiple predictors are specified, they will be combined into a regression-weighted composite that will be carried forward to compute d_{Mod} effect sizes.

  • Note: If weights other than regression weights should be used to combine the predictors into a composite, the user must manually compute such a composite, include the composite in the dat data set, and identify the composite variable in predictors.

criterion

Name or column-index number of the criterion variable in the data set. The criterion cannot be a factor-type variable.

referent_id

Label used to identify the referent group in the group variable.

focal_id_vec

Label(s) to identify the focal group(s) in the group variable. If NULL (the default), the specified referent group will be compared to all other groups.

conf_level

Confidence level (between 0 and 1) to be used in generating confidence intervals. Default is .95

rescale_cdf

Logical argument that indicates whether parametric d_{Mod} results should be rescaled to account for using a cumulative density < 1 in the computations (TRUE; default) or not (FALSE).

parametric

Logical argument that indicates whether d_{Mod} should be computed using an assumed normal distribution (TRUE; default) or observed frequencies (FALSE).

bootstrap

Logical argument that indicates whether d_{Mod} should be bootstrapped (TRUE; default) or not (FALSE).

boot_iter

Number of bootstrap iterations to compute (default = 1000).

stratify

Logical argument that indicates whether the random bootstrap sampling should be stratified (TRUE) or unstratified (FALSE; default).

empirical_ci

Logical argument that indicates whether the bootstrapped confidence intervals should be computed from the observed empirical distributions (TRUE) or computed using bootstrapped means and standard errors via the normal-theory approach (FALSE).

cross_validate_wts

Only relevant when multiple predictors are specified and bootstrapping is performed. Logical argument that indicates whether regression weights derived from the full sample should be used to combine predictors in the bootstrapped samples (TRUE) or if a new set of weights should be derived during each iteration of the bootstrapping procedure (FALSE; default).

Value

If bootstrapping is selected, the list will include:

  • point_estimate: A matrix of effect sizes (d_{Mod_{Signed}}, d_{Mod_{Unsigned}}, d_{Mod_{Under}}, d_{Mod_{Over}}), proportions of under- and over-predicted criterion scores, minimum and maximum differences, and the scores associated with minimum and maximum differences. All of these values are computed using the full data set.

  • bootstrap_mean: A matrix of the same statistics as the point_estimate matrix, but the values in this matrix are the means of the results from bootstrapped samples.

  • bootstrap_se: A matrix of the same statistics as the point_estimate matrix, but the values in this matrix are bootstrapped standard errors (i.e., the standard deviations of the results from bootstrapped samples).

  • bootstrap_CI_Lo: A matrix of the same statistics as the point_estimate matrix, but the values in this matrix are the lower confidence bounds of the results from bootstrapped samples.

  • bootstrap_CI_Hi: A matrix of the same statistics as the point_estimate matrix, but the values in this matrix are the upper confidence bounds of the results from bootstrapped samples.

If no bootstrapping is performed, the output will be limited to the point_estimate matrix.

References

Nye, C. D., & Sackett, P. R. (2017). New effect sizes for tests of categorical moderation and differential prediction. Organizational Research Methods, 20(4), 639–664. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1177/1094428116644505")}

Examples

# Generate some hypothetical data for a referent group and three focal groups:
set.seed(10)
refDat <- MASS::mvrnorm(n = 1000, mu = c(.5, .2),
                        Sigma = matrix(c(1, .5, .5, 1), 2, 2), empirical = TRUE)
foc1Dat <- MASS::mvrnorm(n = 1000, mu = c(-.5, -.2),
                         Sigma = matrix(c(1, .5, .5, 1), 2, 2), empirical = TRUE)
foc2Dat <- MASS::mvrnorm(n = 1000, mu = c(0, 0),
                         Sigma = matrix(c(1, .3, .3, 1), 2, 2), empirical = TRUE)
foc3Dat <- MASS::mvrnorm(n = 1000, mu = c(-.5, -.2),
                         Sigma = matrix(c(1, .3, .3, 1), 2, 2), empirical = TRUE)
colnames(refDat) <- colnames(foc1Dat) <- colnames(foc2Dat) <- colnames(foc3Dat) <- c("X", "Y")
dat <- rbind(cbind(G = 1, refDat), cbind(G = 2, foc1Dat),
             cbind(G = 3, foc2Dat), cbind(G = 4, foc3Dat))

# Compute point estimates of parametric d_mod effect sizes:
compute_dmod(data = dat, group = "G", predictors = "X", criterion = "Y",
     referent_id = 1, focal_id_vec = 2:4,
     conf_level = .95, rescale_cdf = TRUE, parametric = TRUE,
     bootstrap = FALSE)

# Compute point estimates of non-parametric d_mod effect sizes:
compute_dmod(data = dat, group = "G", predictors = "X", criterion = "Y",
     referent_id = 1, focal_id_vec = 2:4,
     conf_level = .95, rescale_cdf = TRUE, parametric = FALSE,
     bootstrap = FALSE)

# Compute unstratified bootstrapped estimates of parametric d_mod effect sizes:
compute_dmod(data = dat, group = "G", predictors = "X", criterion = "Y",
     referent_id = 1, focal_id_vec = 2:4,
     conf_level = .95, rescale_cdf = TRUE, parametric = TRUE,
     boot_iter = 10, bootstrap = TRUE, stratify = FALSE, empirical_ci = FALSE)

# Compute unstratified bootstrapped estimates of non-parametric d_mod effect sizes:
compute_dmod(data = dat, group = "G", predictors = "X", criterion = "Y",
     referent_id = 1, focal_id_vec = 2:4,
     conf_level = .95, rescale_cdf = TRUE, parametric = FALSE,
     boot_iter = 10, bootstrap = TRUE, stratify = FALSE, empirical_ci = FALSE)

psychmeta documentation built on June 22, 2024, 6:52 p.m.