ma_d: Meta-analysis of _d_ values

View source: R/ma_d.R

ma_dR Documentation

Meta-analysis of d values

Description

The ma_r_bb, ma_r_ic, and ma_r_ad functions implement bare-bones, individual-correction, and artifact-distribution correction methods for d values, respectively. The ma_d function is the master function for meta-analyses of d values - it facilitates the computation of bare-bones, artifact-distribution, and individual-correction meta-analyses of correlations for any number of group-wise contrasts and any number of dependent variables. When artifact-distribution meta-analyses are performed, ma_d will automatically extract the artifact information from a database and organize it into the requested type of artifact distribution object (i.e., either Taylor series or interactive artifact distributions). ma_d is also equipped with the capability to clean databases containing inconsistently recorded artifact data, impute missing artifacts (when individual-correction meta-analyses are requested), and remove dependency among samples by forming composites or averaging effect sizes and artifacts. The automatic compositing features in ma_d are employed when sample_ids and/or construct names are provided.

Usage

ma_d(
  d,
  n1,
  n2 = NULL,
  n_adj = NULL,
  sample_id = NULL,
  citekey = NULL,
  treat_as_r = FALSE,
  ma_method = c("bb", "ic", "ad"),
  ad_type = c("tsa", "int"),
  correction_method = "auto",
  group_id = NULL,
  group1 = NULL,
  group2 = NULL,
  group_order = NULL,
  construct_y = NULL,
  facet_y = NULL,
  measure_y = NULL,
  construct_order = NULL,
  wt_type = c("n_effective", "sample_size", "inv_var_mean", "inv_var_sample", "DL", "HE",
    "HS", "SJ", "ML", "REML", "EB", "PM"),
  correct_bias = TRUE,
  correct_rel = NULL,
  correct_rGg = FALSE,
  correct_ryy = TRUE,
  correct_rr = NULL,
  correct_rr_g = TRUE,
  correct_rr_y = TRUE,
  indirect_rr = NULL,
  indirect_rr_g = TRUE,
  indirect_rr_y = TRUE,
  rGg = NULL,
  pi = NULL,
  pa = NULL,
  ryy = NULL,
  ryy_restricted = TRUE,
  ryy_type = "alpha",
  k_items_y = NULL,
  uy = NULL,
  uy_observed = TRUE,
  sign_rz = NULL,
  sign_rgz = 1,
  sign_ryz = 1,
  moderators = NULL,
  cat_moderators = TRUE,
  moderator_type = c("simple", "hierarchical", "none"),
  supplemental_ads = NULL,
  data = NULL,
  control = control_psychmeta(),
  ...
)

ma_d_ad(
  ma_obj,
  ad_obj_g = NULL,
  ad_obj_y = NULL,
  correction_method = "auto",
  use_ic_ads = c("tsa", "int"),
  correct_rGg = FALSE,
  correct_ryy = TRUE,
  correct_rr_g = TRUE,
  correct_rr_y = TRUE,
  indirect_rr_g = TRUE,
  indirect_rr_y = TRUE,
  sign_rgz = 1,
  sign_ryz = 1,
  control = control_psychmeta(),
  ...
)

ma_d_bb(
  d,
  n1,
  n2 = rep(NA, length(d)),
  n_adj = NULL,
  sample_id = NULL,
  citekey = NULL,
  wt_type = c("n_effective", "sample_size", "inv_var_mean", "inv_var_sample", "DL", "HE",
    "HS", "SJ", "ML", "REML", "EB", "PM"),
  correct_bias = TRUE,
  moderators = NULL,
  cat_moderators = TRUE,
  moderator_type = c("simple", "hierarchical", "none"),
  data = NULL,
  control = control_psychmeta(),
  ...
)

ma_d_ic(
  d,
  n1,
  n2 = NULL,
  n_adj = NULL,
  sample_id = NULL,
  citekey = NULL,
  treat_as_r = FALSE,
  wt_type = c("n_effective", "sample_size", "inv_var_mean", "inv_var_sample", "DL", "HE",
    "HS", "SJ", "ML", "REML", "EB", "PM"),
  correct_bias = TRUE,
  correct_rGg = FALSE,
  correct_ryy = TRUE,
  correct_rr_g = FALSE,
  correct_rr_y = TRUE,
  indirect_rr_g = TRUE,
  indirect_rr_y = TRUE,
  rGg = NULL,
  pi = NULL,
  pa = NULL,
  ryy = NULL,
  ryy_restricted = TRUE,
  ryy_type = "alpha",
  k_items_y = NULL,
  uy = NULL,
  uy_observed = TRUE,
  sign_rgz = 1,
  sign_ryz = 1,
  moderators = NULL,
  cat_moderators = TRUE,
  moderator_type = c("simple", "hierarchical", "none"),
  supplemental_ads_y = NULL,
  data = NULL,
  control = control_psychmeta(),
  ...
)

Arguments

d

Vector or column name of observed d values. NOTE: Beginning in psychmeta version 2.5.2, d values of exactly 0 in individual-correction meta-analyses are replaced with a functionally equivalent value (in the correlation metric) via the zero_substitute argument for control_psychmeta to facilitate the estimation of corrected error variances.

n1

Vector or column name of sample sizes.

n2

Vector or column name of sample sizes.

n_adj

Optional: Vector or column name of sample sizes adjusted for sporadic artifact corrections.

sample_id

Optional vector of identification labels for samples/studies in the meta-analysis.

citekey

Optional vector of bibliographic citation keys for samples/studies in the meta-analysis (if multiple citekeys pertain to a given effect size, combine them into a single string entry with comma delimiters (e.g., "citkey1,citekey2").

treat_as_r

Logical scalar determining whether d values are to be meta-analyzed as d values (FALSE; default) or whether they should be meta-analyzed as correlations and have the final results converted to the d metric (TRUE).

ma_method

Method to be used to compute the meta-analysis: "bb" (barebones), "ic" (individual correction), or "ad" (artifact distribution).

ad_type

For when ma_method is "ad", specifies the type of artifact distribution to use: "int" or "tsa".

correction_method

Character scalar or a matrix with group_id levels as row names and construct_y levels as column names. When ma_method is "ad", select one of the following methods for correcting artifacts: "auto", "meas", "uvdrr", "uvirr", "bvdrr", "bvirr", "rbOrig", "rb1Orig", "rb2Orig", "rbAdj", "rb1Adj", and "rb2Adj". (note: "rb1Orig", "rb2Orig", "rb1Adj", and "rb2Adj" can only be used when Taylor series artifact distributions are provided and "rbOrig" and "rbAdj" can only be used when interactive artifact distributions are provided). See "Details" of ma_d_ad for descriptions of the available methods.

group_id

Vector of group comparison IDs (e.g., Treatment1-Control, Treatment2-Control). The group_id argument supersedes the group1 and group2 arguments. If group_id is not NULL, the values supplied to the group_order argument must correspond to group_id values.

group1, group2

Vector of group identification labels (e.g., Treatment1, Treatment2, Control)

group_order

Optional vector indicating the order in which (1) group1 and group2 values or (2) group_ids should be arranged. If group_order is NULL, the order of group pairings will be determined internally using alpha-numeric ordering.

construct_y

Vector of construct names for construct designated as "Y".

facet_y

Vector of facet names for constructs designated as "Y". Facet names "global", "overall", and "total" are reserved to indicate observations that represent effect sizes that have already been composited or that represent construct-level measurements rather than facet-level measurements. To avoid double-compositing, any observation with one of these reserved names will only be eligible for auto-compositing with other such observations and will not be combined with narrow facets.

measure_y

Vector of names for measures associated with constructs designated as "Y".

construct_order

Vector indicating the order in which Y variables should be arranged.

wt_type

Type of weight to use in the meta-analysis: options are "n_effective" (effective sample size), "sample_size", "inv_var_mean" (inverse variance computed using mean effect size), and "inv_var_sample" (inverse variance computed using sample-specific effect sizes). Supported options borrowed from metafor are "DL", "HE", "HS", "SJ", "ML", "REML", "EB", and "PM" (see metafor documentation for details about the metafor methods).

correct_bias

Logical scalar that determines whether to correct correlations for small-sample bias (TRUE) or not (FALSE).

correct_rel

Optional named vector that supersedes correct_rGg and correct_ryy. Names should correspond to construct names in group_id and construct_y to determine which constructs should be corrected for unreliability.

correct_rGg

Logical scalar or vector that determines whether to correct the grouping variable for measurement error (TRUE) or not (FALSE).

correct_ryy

Logical scalar or vector that determines whether to correct the Y variable for measurement error (TRUE) or not (FALSE).

correct_rr

Optional named vector that supersedes correct_rr_g and correct_rr_y. Names should correspond to construct names in group_id and construct_y to determine which constructs should be corrected for range restriction.

correct_rr_g

Logical scalar or vector or column name determining whether each d value should be corrected for range restriction in the grouping variable (TRUE) or not (FALSE).

correct_rr_y

Logical scalar or vector or column name determining whether each d should be corrected for range restriction in Y (TRUE) or not (FALSE).

indirect_rr

Optional named vector that supersedes indirect_rr_g and indirect_rr_y. Names should correspond to construct names in group_id and construct_y to determine which constructs should be corrected for indirect range restriction.

indirect_rr_g

Logical vector or column name determining whether each d should be corrected for indirect range restriction in the grouping variable (TRUE) or not (FALSE). Superseded in evaluation by correct_rr_g (i.e., if correct_rr_g == FALSE, the value supplied for indirect_rr_g is disregarded).

indirect_rr_y

Logical vector or column name determining whether each d should be corrected for indirect range restriction in Y (TRUE) or not (FALSE). Superseded in evaluation by correct_rr_y (i.e., if correct_rr_y == FALSE, the value supplied for indirect_rr_y is disregarded).

rGg

Vector or column name of reliability estimates for X.

pi

Scalar or vector containing the restricted-group proportions of group membership. If a vector, it must either (1) have as many elements as there are d values or (2) be named so as to match with levels of the group_id argument.

pa

Scalar or vector containing the unrestricted-group proportions of group membership (default = .5). If a vector, it must either (1) have as many elements as there are d values or (2) be named so as to match with levels of the group_id argument.

ryy

Vector or column name of reliability estimates for Y.

ryy_restricted

Logical vector or column name determining whether each element of ryy is an incumbent reliability (TRUE) or an applicant reliability (FALSE).

ryy_type

String vector identifying the types of reliability estimates supplied (e.g., "alpha", "retest", "interrater_r", "splithalf"). See the documentation for ma_r for a full list of acceptable reliability types.

k_items_y

Numeric vector identifying the number of items in each scale.

uy

Vector or column name of u ratios for Y.

uy_observed

Logical vector or column name determining whether each element of uy is an observed-score u ratio (TRUE) or a true-score u ratio (FALSE).

sign_rz

Optional named vector that supersedes sign_rgz and sign_ryz. Names should correspond to construct names in group_id and construct_y to determine the sign of each construct's relationship with the selection mechanism.

sign_rgz

Sign of the relationship between X and the selection mechanism (for use with bvirr corrections only).

sign_ryz

Sign of the relationship between Y and the selection mechanism (for use with bvirr corrections only).

moderators

Matrix or column names of moderator variables to be used in the meta-analysis (can be a vector in the case of one moderator).

cat_moderators

Logical scalar or vector identifying whether variables in the moderators argument are categorical variables (TRUE) or continuous variables (FALSE).

moderator_type

Type of moderator analysis: "none" means that no moderators are to be used, "simple" means that moderators are to be examined one at a time, "hierarchical" means that all possible combinations and subsets of moderators are to be examined, and "all" means that simple and hierarchical moderator analyses are to be performed.

supplemental_ads

Named list (named according to the constructs included in the meta-analysis) of supplemental artifact distribution information from studies not included in the meta-analysis. This is a list of lists, where the elements of a list associated with a construct are named like the arguments of the create_ad() function.

data

Data frame containing columns whose names may be provided as arguments to vector arguments and/or moderators.

control

Output from the control_psychmeta() function or a list of arguments controlled by the control_psychmeta() function. Ellipsis arguments will be screened for internal inclusion in control.

...

Further arguments to be passed to functions called within the meta-analysis.

ma_obj

For ma_d_ad only: Meta-analysis object of correlations or d values (regardless of input metric, output metric will be d).

ad_obj_g

For ma_d_ad only: Artifact-distribution object for the grouping variable (output of the link{create_ad} or link{create_ad_group} functions). If ma_obj is of the class ma_master (i.e., the output of ma_r or ma_d), the object supplied for ad_obj_g must be a named list of artifact distributions with names. corresponding to the "X" constructs in the meta-analyses contained within ma_obj.

ad_obj_y

For ma_d_ad only: AArtifact-distribution object for the Y variable (output of the create_ad function). If ma_obj is of the class ma_master, the object supplied for ad_obj_y must be a named list of artifact distributions with names corresponding to the "Y" constructs in the meta-analyses contained within ma_obj.

use_ic_ads

For ma_d_ad only: Determines whether artifact distributions should be extracted from the individual correction results in ma_obj. Only evaluated when ad_obj_g or ad_obj_y is NULL and ma_obj does not contain individual correction results. Use one of the following commands: tsa to use the Taylor series method or int to use the interactive method.

supplemental_ads_y

For ma_d_ic only: List supplemental artifact distribution information from studies not included in the meta-analysis. The elements of this list are named like the arguments of the create_ad() function.

Details

The options for correction_method are:

  • "auto": Automatic selection of the most appropriate correction procedure, based on the available artifacts and the logical arguments provided to the function. (default)

  • "meas": Correction for measurement error only.

  • "uvdrr": Correction for univariate direct range restriction (i.e., Case II). The choice of which variable to correct for range restriction is made using the correct_rr_x and correct_rr_y arguments.

  • "uvirr": Correction for univariate indirect range restriction (i.e., Case IV). The choice of which variable to correct for range restriction is made using the correct_rr_x and correct_rr_y arguments.

  • "bvdrr": Correction for bivariate direct range restriction. Use with caution: This correction is an approximation only and is known to have a positive bias.

  • "bvirr": Correction for bivariate indirect range restriction (i.e., Case V).

  • "rbOrig": Not recommended: Raju and Burke's version of the correction for direct range restriction, applied interactively. We recommend using "uvdrr" instead.

  • "rbAdj": Not recommended: Raju and Burke's version of the correction for direct range restriction, applied interactively. Adjusted to account for range restriction in the reliability of the Y variable. We recommend using "uvdrr" instead.

  • "rb1Orig": Not recommended: Raju and Burke's version of the correction for direct range restriction, applied using their TSA1 method. We recommend using "uvdrr" instead.

  • "rb1Adj": Not recommended: Raju and Burke's version of the correction for direct range restriction, applied using their TSA1 method. Adjusted to account for range restriction in the reliability of the Y variable. We recommend using "uvdrr" instead.

  • "rb2Orig": Not recommended: Raju and Burke's version of the correction for direct range restriction, applied using their TSA2 method. We recommend using "uvdrr" instead.

  • "rb2Adj": Not recommended: Raju and Burke's version of the correction for direct range restriction, applied using their TSA2 method. Adjusted to account for range restriction in the reliability of the Y variable. We recommend using "uvdrr" instead.

Value

A nested tabular object of the class "ma_psychmeta". Components of output tables for bare-bones meta-analyses:

  • Pair_ID: Unique identification number for each construct-contrast pairing.

  • group_contrast: Name of the variable analyzed as the group-contrast variable.

  • construct_y: Name of the variable analyzed as construct Y.

  • analysis_id: Unique identification number for each analysis.

  • analysis_type: Type of moderator analyses: Overall, Simple Moderator, or Hierarchical Moderator.

  • k: Number of effect sizes meta-analyzed.

  • N: Total sample size of all effect sizes in the meta-analysis.

  • mean_d: Mean observed d value.

  • var_d: Weighted variance of observed d values.

  • var_e: Predicted sampling-error variance of observed d values.

  • var_res: Variance of observed d values after removing predicted sampling-error variance.

  • sd_d: Square root of var_r.

  • se_d: Standard error of mean_d.

  • sd_e: Square root of var_e.

  • sd_res: Square root of var_res.

  • CI_LL_XX: Lower limit of the confidence interval around mean_d, where "XX" represents the confidence level as a percentage.

  • CI_UL_XX: Upper limit of the confidence interval around mean_d, where "XX" represents the confidence level as a percentage.

  • CR_LL_XX: Lower limit of the credibility interval around mean_d, where "XX" represents the credibility level as a percentage.

  • CR_UL_XX: Upper limit of the credibility interval around mean_d, where "XX" represents the credibility level as a percentage.

Components of output tables for individual-correction meta-analyses:

  • pair_id: Unique identification number for each construct-contrast pairing.

  • group_contrast: Name of the variable analyzed as the group-contrast variable.

  • construct_y: Name of the variable analyzed as construct Y.

  • analysis_id: Unique identification number for each analysis.

  • analysis_type: Type of moderator analyses: Overall, Simple Moderator, or Hierarchical Moderator.

  • k: Number of effect sizes meta-analyzed.

  • N: Total sample size of all effect sizes in the meta-analysis.

  • mean_d: Mean observed d value.

  • var_d: Weighted variance of observed d values.

  • var_e: Predicted sampling-error variance of observed d values.

  • var_res: Variance of observed d values after removing predicted sampling-error variance.

  • sd_d: Square root of var_r.

  • se_d: Standard error of mean_d.

  • sd_e: Square root of var_e.

  • sd_res: Square root of var_res.

  • mean_delta: Mean artifact-corrected d value.

  • var_d_c: Variance of artifact-corrected d values.

  • var_e_c: Predicted sampling-error variance of artifact-corrected d values.

  • var_delta: Variance of artifact-corrected d values after removing predicted sampling-error variance.

  • sd_d_c: Square root of var_r_c.

  • se_d_c: Standard error of mean_delta.

  • sd_e_c: Square root of var_e_c.

  • sd_delta: Square root of var_delta.

  • CI_LL_XX: Lower limit of the confidence interval around mean_delta, where "XX" represents the confidence level as a percentage.

  • CI_UL_XX: Upper limit of the confidence interval around mean_delta, where "XX" represents the confidence level as a percentage.

  • CR_LL_XX: Lower limit of the credibility interval around mean_delta, where "XX" represents the credibility level as a percentage.

  • CR_UL_XX: Upper limit of the credibility interval around mean_delta, where "XX" represents the credibility level as a percentage.

Components of output tables for artifact-distribution meta-analyses:

  • pair_id: Unique identification number for each construct-contrast pairing.

  • group_contrast: Name of the variable analyzed as the group-contrast variable.

  • construct_y: Name of the variable analyzed as construct Y.

  • analysis_id: Unique identification number for each analysis.

  • analysis_type: Type of moderator analyses: Overall, Simple Moderator, or Hierarchical Moderator.

  • k: Number of effect sizes meta-analyzed.

  • N: Total sample size of all effect sizes in the meta-analysis.

  • mean_d: Mean observed d value.

  • var_d: Weighted variance of observed d values.

  • var_e: Predicted sampling-error variance of observed d values.

  • var_art: Amount of variance in observed d values that is attributable to measurement-error and range-restriction artifacts.

  • var_pre: Total predicted artifactual variance (i.e., the sum of var_e and var_art).

  • var_res: Variance of observed d values after removing predicted sampling-error variance and predicted artifact variance.

  • sd_d: Square root of var_d.

  • se_d: Standard error of mean_d.

  • sd_e: Square root of var_e.

  • sd_art: Square root of var_art.

  • sd_pre: Square root of var_pre.

  • sd_res: Square root of var_res.

  • mean_delta: Mean artifact-corrected d value.

  • var_d: Weighted variance of observed d values corrected to the metric of delta.

  • var_e: Predicted sampling-error variance of observed d values corrected to the metric of delta.

  • var_art: Amount of variance in observed d values that is attributable to measurement-error and range-restriction artifacts corrected to the metric of delta.

  • var_pre: Total predicted artifactual variance (i.e., the sum of var_e and var_art) corrected to the metric of delta.

  • var_delta: Variance of artifact-corrected d values after removing predicted sampling-error variance and predicted artifact variance.

  • sd_d: Square root of var_d corrected to the metric of delta.

  • se_d: Standard error of mean_d corrected to the metric of delta.

  • sd_e: Square root of var_e corrected to the metric of delta.

  • sd_art: Square root of var_art corrected to the metric of delta.

  • sd_pre: Square root of var_pre corrected to the metric of delta.

  • sd_delta: Square root of var_delta.

  • CI_LL_XX: Lower limit of the confidence interval around mean_delta, where "XX" represents the confidence level as a percentage.

  • CI_UL_XX: Upper limit of the confidence interval around mean_delta, where "XX" represents the confidence level as a percentage.

  • CR_LL_XX: Lower limit of the credibility interval around mean_delta, where "XX" represents the credibility level as a percentage.

  • CR_UL_XX: Upper limit of the credibility interval around mean_delta, where "XX" represents the credibility level as a percentage.

Note

The difference between "rb" methods with the "orig" and "adj" suffixes is that the original does not account for the impact of range restriction on criterion reliabilities, whereas the adjusted procedure attempts to estimate the applicant reliability information for the criterion. The "rb" procedures are included for posterity: We strongly recommend using the "uvdrr" procedure to appropriately correct for univariate range restriction.

References

Schmidt, F. L., & Hunter, J. E. (2015). Methods of meta-analysis: Correcting error and bias in research findings (3rd ed.). Sage. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.4135/9781483398105")}. Chapter 4.

Law, K. S., Schmidt, F. L., & Hunter, J. E. (1994). Nonlinearity of range corrections in meta-analysis: Test of an improved procedure. Journal of Applied Psychology, 79(3), 425.

Dahlke, J. A., & Wiernik, B. M. (2020). Not restricted to selection research: Accounting for indirect range restriction in organizational research. Organizational Research Methods, 23(4), 717–749. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1177/1094428119859398")}

Raju, N. S., & Burke, M. J. (1983). Two new procedures for studying validity generalization. Journal of Applied Psychology, 68(3), 382. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1037/0021-9010.68.3.382")}

Examples

### Demonstration of ma_d ###
## The 'ma_d' function can compute multi-construct bare-bones meta-analyses:
ma_d(d = d, n1 = n1, n2 = n2, construct_y = construct, data = data_d_meas_multi)

## It can also perform multiple individual-correction meta-analyses:
ma_d(ma_method = "ic", d = d, n1 = n1, n2 = n2, ryy = ryyi,
     construct_y = construct, data = data_d_meas_multi)

## And 'ma_d' can also curate artifact distributions and compute multiple
## artifact-distribution meta-analyses:
ma_d(ma_method = "ad", d = d, n1 = n1, n2 = n2,
     ryy = ryyi, correct_rr_y = FALSE,
     construct_y = construct, data = data_d_meas_multi)


### Demonstration of ma_d_bb ###
## Example meta-analyses using simulated data:
ma_d_bb(d = d, n1 = n1, n2 = n2,
        data = data_d_meas_multi[data_d_meas_multi$construct == "Y",])
ma_d_bb(d = d, n1 = n1, n2 = n2,
        data = data_d_meas_multi[data_d_meas_multi$construct == "Z",])


### Demonstration of ma_d_ic ###
## Example meta-analyses using simulated data:
ma_d_ic(d = d, n1 = n1, n2 = n2, ryy = ryyi, correct_rr_y = FALSE,
        data = data_d_meas_multi[data_d_meas_multi$construct == "Y",])
ma_d_ic(d = d, n1 = n1, n2 = n2, ryy = ryyi, correct_rr_y = FALSE,
        data = data_d_meas_multi[data_d_meas_multi$construct == "Z",])

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