ma_r: Meta-analysis of correlations
In psychmeta/psychmeta: Psychometric Meta-Analysis Toolkit

View source: R/ma_r.R

ma_r	R Documentation

Meta-analysis of correlations

Description

The ma_r_bb, ma_r_ic, and ma_r_ad functions implement bare-bones, individual-correction, and artifact-distribution correction methods for correlations, respectively. The ma_r function is the master function for meta-analyses of correlations - it facilitates the computation of bare-bones, artifact-distribution, and individual-correction meta-analyses of correlations for any number of construct pairs. When artifact-distribution meta-analyses are performed, ma_r 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_r 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_r are employed when sample_ids and/or construct names are provided.

Usage

ma_r(
  rxyi,
  n,
  n_adj = NULL,
  sample_id = NULL,
  citekey = NULL,
  ma_method = c("bb", "ic", "ad"),
  ad_type = c("tsa", "int"),
  correction_method = "auto",
  construct_x = NULL,
  construct_y = NULL,
  facet_x = NULL,
  facet_y = NULL,
  measure_x = NULL,
  measure_y = NULL,
  construct_order = NULL,
  wt_type = c("sample_size", "inv_var_mean", "inv_var_sample", "DL", "HE", "HS", "SJ",
    "ML", "REML", "EB", "PM"),
  correct_bias = TRUE,
  correct_rel = NULL,
  correct_rxx = TRUE,
  correct_ryy = TRUE,
  correct_rr = NULL,
  correct_rr_x = TRUE,
  correct_rr_y = TRUE,
  indirect_rr = NULL,
  indirect_rr_x = TRUE,
  indirect_rr_y = TRUE,
  rxx = NULL,
  rxx_restricted = TRUE,
  rxx_type = "alpha",
  k_items_x = NULL,
  ryy = NULL,
  ryy_restricted = TRUE,
  ryy_type = "alpha",
  k_items_y = NULL,
  ux = NULL,
  ux_observed = TRUE,
  uy = NULL,
  uy_observed = TRUE,
  sign_rz = NULL,
  sign_rxz = 1,
  sign_ryz = 1,
  moderators = NULL,
  cat_moderators = TRUE,
  moderator_type = c("simple", "hierarchical", "none"),
  supplemental_ads = NULL,
  data = NULL,
  control = control_psychmeta(),
  ...
)

ma_r_ad(
  ma_obj,
  ad_obj_x = NULL,
  ad_obj_y = NULL,
  correction_method = "auto",
  use_ic_ads = c("tsa", "int"),
  correct_rxx = TRUE,
  correct_ryy = TRUE,
  correct_rr_x = TRUE,
  correct_rr_y = TRUE,
  indirect_rr_x = TRUE,
  indirect_rr_y = TRUE,
  sign_rxz = 1,
  sign_ryz = 1,
  control = control_psychmeta(),
  ...
)

ma_r_bb(
  r,
  n,
  n_adj = NULL,
  sample_id = NULL,
  citekey = NULL,
  wt_type = c("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_r_ic(
  rxyi,
  n,
  n_adj = NULL,
  sample_id = NULL,
  citekey = NULL,
  wt_type = c("sample_size", "inv_var_mean", "inv_var_sample", "DL", "HE", "HS", "SJ",
    "ML", "REML", "EB", "PM"),
  correct_bias = TRUE,
  correct_rxx = TRUE,
  correct_ryy = TRUE,
  correct_rr_x = TRUE,
  correct_rr_y = TRUE,
  indirect_rr_x = TRUE,
  indirect_rr_y = TRUE,
  rxx = NULL,
  rxx_restricted = TRUE,
  rxx_type = "alpha",
  k_items_x = NULL,
  ryy = NULL,
  ryy_restricted = TRUE,
  ryy_type = "alpha",
  k_items_y = NULL,
  ux = NULL,
  ux_observed = TRUE,
  uy = NULL,
  uy_observed = TRUE,
  sign_rxz = 1,
  sign_ryz = 1,
  moderators = NULL,
  cat_moderators = TRUE,
  moderator_type = c("simple", "hierarchical", "none"),
  supplemental_ads_x = NULL,
  supplemental_ads_y = NULL,
  data = NULL,
  control = control_psychmeta(),
  ...
)

Arguments

`rxyi, r`	Vector or column name of observed correlations. The `r` argument is used with the `ma_r_bb` (i.e., the barebones function) function and the `rxyi` argument is used with `ma_r` and `ma_r_ic` (i.e., the function in which corrections are applied). NOTE: Beginning in psychmeta version 2.5.2, `rxyi` values of exactly 0 in individual-correction meta-analyses are replaced with a functionally equivalent value via the `zero_substitute` argument for `control_psychmeta` to facilitate the estimation of corrected error variances.
`n`	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").
`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". Dpecifies the type of artifact distribution to use: "int" or "tsa".
`correction_method`	For when ma_method is "ad". Character scalar or a square matrix with the collective levels of `construct_x` and `construct_y` as row names and column names. 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 interative artifact distributions are provided). See "Details" of `ma_r_ad` for descriptions of the available methods.
`construct_x, construct_y`	Vector of construct names for constructs initially designated as "X" or as "Y".
`facet_x, facet_y`	Vector of facet names for constructs initially designated as "X" or 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_x, measure_y`	Vector of names for measures associated with constructs initially designated as "X" or as "Y".
`construct_order`	Vector indicating the order in which variables should be arranged, with variables listed earlier in the vector being preferred for designation as X.
`wt_type`	Type of weight to use in the meta-analysis: options are "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_rxx` and `correct_ryy`. Names should correspond to construct names in `construct_x` and `construct_y` to determine which constructs should be corrected for unreliability.
`correct_rxx, correct_ryy`	Logical scalar or vector that determines whether to correct the X or Y variable for measurement error (`TRUE`) or not (`FALSE`).
`correct_rr`	Optional named vector that supersedes `correct_rr_x` and `correct_rr_y`. Names should correspond to construct names in `construct_x` and `construct_y` to determine which constructs should be corrected for range restriction.
`correct_rr_x`	Logical scalar, logical vector, or column name determining whether each correlation in `rxyi` should be corrected for range restriction in X (`TRUE`) or not (`FALSE`). If using artifact distribution methods, this must be a scalar value.
`correct_rr_y`	Logical scalar, logical vector, or column name determining whether each correlation in `rxyi` should be corrected for range restriction in Y (`TRUE`) or not (`FALSE`). If using artifact distribution methods, this must be a scalar value.
`indirect_rr`	Optional named vector that supersedes `indirect_rr_x` and `indirect_rr_y`. Names should correspond to construct names in `construct_x` and `construct_y` to determine which constructs should be corrected for indirect range restriction.
`indirect_rr_x`	Logical vector or column name determining whether each correlation in `rxyi` should be corrected for indirect range restriction in X (`TRUE`) or not (`FALSE`). Superseded in evaluation by `correct_rr_x` (i.e., if `correct_rr_x` == `FALSE`, the value supplied for `indirect_rr_x` is disregarded).
`indirect_rr_y`	Logical vector or column name determining whether each correlation in `rxyi` 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).
`rxx`	Vector or column name of reliability estimates for X.
`rxx_restricted`	Logical vector or column name determining whether each element of `rxx` is an incumbent reliability (`TRUE`) or an applicant reliability (`FALSE`).
`rxx_type, ryy_type`	String vector identifying the types of reliability estimates supplied. Acceptable reliability types are: internal_consistency A generic designation for internal-consistency reliability estimates derived from responses to a single test administration. multiple_administrations A generic designation for reliability estimates derived from multiple administrations of a test. alpha Coefficient alpha. lambda Generic designation for a Guttman's lambda coefficient. lambda1 Guttman's lambda 1 coefficient. lambda2 Guttman's lambda 2 coefficient. lambda3 Guttman's lambda 3 coefficient. lambda4 Guttman's lambda 4 coefficient. lambda5 Guttman's lambda 5 coefficient. lambda6 Guttman's lambda 6 coefficient. omega Omega coefficient indicating the proportion variance in a variable accounted for by modeled latent factors. icc Intraclass correlation coefficient. interrater_r Inter-rater correlation coefficient. interrater_r_sb Inter-rater correlation coefficient, stepped up with the Spearman-Brown formula. splithalf Split-half reliability coefficient. splithalf_sb Split-half reliability coefficient, corrected toward the full test length with the Spearman-Brown formula. retest Test-retest reliability coefficient. parallel Parallel-forms reliability coefficient with tests taken during the same testing session. alternate Alternate-forms reliability coefficient with tests taken during the same testing session. parallel_delayed Parallel-forms reliability coefficient with tests taken during separate testing sessions with a time delay in between. alternate_delayed Alternate-forms reliability coefficient with tests taken during separate testing sessions with a time delay in between.
`k_items_x, k_items_y`	Numeric vector identifying the number of items in each scale.
`ryy`	Vector or column name of reliability estimates for Y.
`ryy_restricted`	Logical vector or column name determining whether each element of coderyy is an incumbent reliability (`TRUE`) or an applicant reliability (`FALSE`).
`ux`	Vector or column name of u ratios for X.
`ux_observed`	Logical vector or column name determining whether each element of ux is an observed-score u ratio (`TRUE`) or a true-score u ratio (`FALSE`).
`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_rxz` and `sign_ryz`. Names should correspond to construct names in `construct_x` and `construct_y` to determine the sign of each construct's relationship with the selection mechanism.
`sign_rxz`	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`	Either (1) a vector of column names in `data` of moderator variables to be used in the meta-analysis (names can be quoted or unquoted), or (2) a vector, data frame, or matrix containing moderator variables.
`cat_moderators`	Either (1) A character vector listing the variable names in `moderators` that are categorical, or (2) a logical scalar or vector identifying whether each variable in `moderators` is categorical (`TRUE`) or continuous (`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, and "hierarchical" means that all possible combinations and subsets of moderators are to be examined.
`supplemental_ads`	For `ma_r` only: 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_r_ad` only: Meta-analysis object of correlations or d values (regardless of input metric, output metric will be r).
`ad_obj_x`	For `ma_r_ad` only: Artifact-distribution object for the X variable (output of the `create_ad` function). 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_x` 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_r_ad` only: Artifact-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_r_ad` only: Determines whether artifact distributions should be extracted from the individual correction results in `ma_obj`. Only evaluated when `ad_obj_x` 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_x, supplemental_ads_y`	For `ma_r_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 pairing.
construct_x
Name of the variable analyzed as construct X.
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_r
Mean observed correlation.
var_r
Weighted variance of observed correlations.
var_e
Predicted sampling-error variance of observed correlations.
var_res
Variance of observed correlations after removing predicted sampling-error variance.
sd_r
Square root of var_r.
se_r
Standard error of mean_r.
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_r, where "XX" represents the confidence level as a percentage.
CI_UL_XX
Upper limit of the confidence interval around mean_r, where "XX" represents the confidence level as a percentage.
CR_LL_XX
Lower limit of the credibility interval around mean_r, where "XX" represents the credibility level as a percentage.
CR_UL_XX
Upper limit of the credibility interval around mean_r, 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 pairing.
construct_x
Name of the variable analyzed as construct X.
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_r
Mean observed correlation.
var_r
Weighted variance of observed correlations.
var_e
Predicted sampling-error variance of observed correlations.
var_res
Variance of observed correlations after removing predicted sampling-error variance.
sd_r
Square root of var_r.
se_r
Standard error of mean_r.
sd_e
Square root of var_e.
sd_res
Square root of var_res.
mean_rho
Mean artifact-corrected correlation.
var_r_c
Variance of artifact-corrected correlations.
var_e_c
Predicted sampling-error variance of artifact-corrected correlations.
var_rho
Variance of artifact-corrected correlations after removing predicted sampling-error variance.
sd_r_c
Square root of var_r_c.
se_r_c
Standard error of mean_rho.
sd_e_c
Square root of var_e_c.
sd_rho
Square root of var_rho.
CI_LL_XX
Lower limit of the confidence interval around mean_rho, where "XX" represents the confidence level as a percentage.
CI_UL_XX
Upper limit of the confidence interval around mean_rho, where "XX" represents the confidence level as a percentage.
CR_LL_XX
Lower limit of the credibility interval around mean_rho, where "XX" represents the credibility level as a percentage.
CR_UL_XX
Upper limit of the credibility interval around mean_rho, 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 pairing.
construct_x
Name of the variable analyzed as construct X.
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_r
Mean observed correlation.
var_r
Weighted variance of observed correlations.
var_e
Predicted sampling-error variance of observed correlations.
var_art
Amount of variance in observed correlations 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 correlations after removing predicted sampling-error variance and predicted artifact variance.
sd_r
Square root of var_r.
se_r
Standard error of mean_r.
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_rho
Mean artifact-corrected correlation.
var_r_c
Weighted variance of observed correlations corrected to the metric of rho.
var_e_c
Predicted sampling-error variance of observed correlations corrected to the metric of rho.
var_art_c
Amount of variance in observed correlations that is attributable to measurement-error and range-restriction artifacts corrected to the metric of rho.
var_pre_c
Total predicted artifactual variance (i.e., the sum of var_e and var_art) corrected to the metric of rho.
var_rho
Variance of artifact-corrected correlations after removing predicted sampling-error variance and predicted artifact variance.
sd_r_c
Square root of var_r corrected to the metric of rho.
se_r_c
Standard error of mean_r corrected to the metric of rho.
sd_e_c
Square root of var_e corrected to the metric of rho.
sd_art_c
Square root of var_art corrected to the metric of rho.
sd_pre_c
Square root of var_pre corrected to the metric of rho.
sd_rho
Square root of var_rho.
CI_LL_XX
Lower limit of the confidence interval around mean_rho, where "XX" represents the confidence level as a percentage.
CI_UL_XX
Upper limit of the confidence interval around mean_rho, where "XX" represents the confidence level as a percentage.
CR_LL_XX
Lower limit of the credibility interval around mean_rho, where "XX" represents the credibility level as a percentage.
CR_UL_XX
Upper limit of the credibility interval around mean_rho, 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–438. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1037/0021-9010.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–395. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1037/0021-9010.68.3.382")}

Examples

## Not run: 
## The 'ma_r' function can compute multi-construct bare-bones meta-analyses:
ma_obj <- ma_r(rxyi = rxyi, n = n, rxx = rxxi, ryy = ryyi,
     construct_x = x_name, construct_y = y_name, sample_id = sample_id,
     moderators = moderator, data = data_r_meas_multi)
summary(ma_obj)

## It can also perform multiple individual-correction meta-analyses:
ma_obj <- ma_r(ma_method = "ic", rxyi = rxyi, n = n, rxx = rxxi, ryy = ryyi,
               construct_x = x_name, construct_y = y_name, sample_id = sample_id,
               moderators = moderator, data = data_r_meas_multi)
summary(ma_obj)
ma_obj$meta_tables[[1]]$individual_correction$true_score

## And 'ma_r' can also curate artifact distributions and compute multiple
## artifact-distribution meta-analyses:
ma_obj <- ma_r(ma_method = "ad", ad_type = "int", rxyi = rxyi, n = n, rxx = rxxi, ryy = ryyi,
               correct_rr_x = FALSE, correct_rr_y = FALSE,
               construct_x = x_name, construct_y = y_name, sample_id = sample_id,
               clean_artifacts = FALSE, impute_artifacts = FALSE,
               moderators = moderator, data = data_r_meas_multi)
summary(ma_obj)
ma_obj$meta_tables[[1]]$artifact_distribution$true_score

## Even if no studies in the database provide artifact information,
## pre-specified artifact distributions from previous meta-analyses
## can still be used! (These results should match the previous example.)
ma_obj <- ma_r(ma_method = "ad", rxyi = rxyi, n = n,
               correct_rr_x = FALSE, correct_rr_y = FALSE,
               construct_x = x_name, construct_y = y_name, sample_id = sample_id,
               clean_artifacts = FALSE, impute_artifacts = FALSE,
               moderators = moderator, data = data_r_meas_multi,
               supplemental_ads =
                    list(X = list(mean_qxi = 0.8927818, var_qxi = 0.0008095520, k_qxi = 40,
                                  mean_n_qxi = 11927 / 40, qxi_dist_type = "alpha"),
                         Y = list(mean_qxi = 0.8941266, var_qxi = 0.0009367234, k_qxi = 40,
                                  mean_n_qxi = 11927 / 40, qxi_dist_type = "alpha"),
                         Z = list(mean_qxi = 0.8962108, var_qxi = 0.0007840593, k_qxi = 40,
                                  mean_n_qxi = 11927 / 40, qxi_dist_type = "alpha")))
summary(ma_obj)
ma_obj$meta_tables[[1]]$artifact_distribution$true_score

## Artifact information may also be supplied by passing "ad_obj" class objects with the
## "supplemental_ads" argument.
## Create a list of artifact-distribution objects:
ad_list <- create_ad_list(n = n, rxx = rxxi, ryy = ryyi,
                          construct_x = x_name, construct_y = y_name,
                          sample_id = sample_id,
                          data = data_r_meas_multi)
ad_list <- setNames(ad_list$ad_x, ad_list$construct_x)

## Run the artifact-distribution meta-analysis:
ma_obj <- ma_r(ma_method = "ad", rxyi = rxyi, n = n,
               correct_rr_x = FALSE, correct_rr_y = FALSE,
               construct_x = x_name, construct_y = y_name, sample_id = sample_id,
               clean_artifacts = FALSE, impute_artifacts = FALSE,
               moderators = moderator, data = data_r_meas_multi,
               supplemental_ads = ad_list)
summary(ma_obj)
ma_obj$meta_tables[[1]]$artifact_distribution$true_score


## Artifact information from studies not included in the meta-analysis can also be used to make
## corrections. Passing artifact information with the 'supplemental_ads' argument allows for
## additional artifact values and/or means and variances of artifacts to be used.
## The 'supplemental_ads' analysis below gives the same results as the prior meta-analysis.
x_ids <- c(data_r_meas_multi$x_name, data_r_meas_multi$y_name) == "X"
rxxi <- c(data_r_meas_multi$rxxi, data_r_meas_multi$ryyi)[x_ids]
n_rxxi = c(data_r_meas_multi$n, data_r_meas_multi$n)[x_ids]

y_ids <- c(data_r_meas_multi$x_name, data_r_meas_multi$y_name) == "Y"
ryyi <- c(data_r_meas_multi$rxxi, data_r_meas_multi$ryyi)[y_ids]
n_ryyi = c(data_r_meas_multi$n, data_r_meas_multi$n)[y_ids]

z_ids <- c(data_r_meas_multi$x_name, data_r_meas_multi$y_name) == "Z"
rzzi <- c(data_r_meas_multi$rxxi, data_r_meas_multi$ryyi)[z_ids]
n_rzzi = c(data_r_meas_multi$n, data_r_meas_multi$n)[z_ids]

ma_obj <- ma_r(ma_method = "ad", rxyi = rxyi, n = n,
               correct_rr_x = FALSE, correct_rr_y = FALSE,
               construct_x = x_name, construct_y = y_name,
               moderators = moderator, sample_id = sample_id, data = data_r_meas_multi,
               supplemental_ads = list(X = list(rxxi = rxxi, n_rxxi = n_rxxi, wt_rxxi = n_rxxi),
                                       Y = list(rxxi = ryyi, n_rxxi = n_ryyi, wt_rxxi = n_ryyi),
                                       Z = list(rxxi = rzzi, n_rxxi = n_rzzi, wt_rxxi = n_rzzi)))
summary(ma_obj)
ma_obj$meta_tables[[1]]$artifact_distribution$true_score

## If 'use_all_arts' is set to TRUE, artifacts from studies without valid correlations
## will be used to inform artifact distributions. Below, correlations and artifacts
## are provided by non-overlapping sets of studies.
dat1 <- dat2 <- data_r_meas_multi
dat1$rxxi <- dat1$ryyi <- NA
dat2$rxyi <- NA
dat2$sample_id <- dat2$sample_id + 40
dat <- rbind(dat1, dat2)
ma_obj <- ma_r(ma_method = "ad", rxyi = rxyi, n = n, rxx = rxxi, ryy = ryyi,
               correct_rr_x = FALSE, correct_rr_y = FALSE,
               construct_x = x_name, construct_y = y_name,
               sample_id = sample_id, moderators = moderator,
               use_all_arts = TRUE, data = dat)
summary(ma_obj)
ma_obj$meta_tables[[1]]$artifact_distribution$true_score



### Demonstration of ma_r_bb ###
## Example analysis using data from Gonzalez-Mule et al. (2014):

## Not correcting for bias and using normal distributions to compute uncertainty intervals
## allows for exact replication of the results reported in the text:
ma_r_bb(r = rxyi, n = n, correct_bias = FALSE, conf_method = "norm", cred_method = "norm",
               data = data_r_gonzalezmule_2014)

## Using hs_override = TRUE allows one to easily implement the traditional Hunter-Schmidt method:
ma_r_bb(r = rxyi, n = n, hs_override = TRUE, data = data_r_gonzalezmule_2014)

## With hs_override = FALSE, the program defaults will compute unbiased variances and use
## t-distributions to estimate confidence and credibility intervals - these settings make
## a noticeable difference for small studies like the textbook example:
ma_r_bb(r = rxyi, n = n, hs_override = FALSE, data = data_r_gonzalezmule_2014)



### Demonstration of ma_r_ic ###
## Simulated example satisfying the assumptions of the Case IV
## range-restriction correction (parameter values: mean_rho = .3, sd_rho = .15):
ma_r_ic(rxyi = rxyi, n = n, rxx = rxxi, ryy = ryyi, ux = ux, data = data_r_uvirr)

## Simulated example satisfying the assumptions of the Case V
## range-restriction correction
ma_r_ic(rxyi = rxyi, n = n, rxx = rxxi, ryy = ryyi,
        rxx_type = "parallel", ryy_type = "parallel",
        ux = ux, uy = uy, data = data_r_bvirr)

## Published example from Gonzalez-Mule et al. (2014)
ma_r_ic(rxyi = rxyi, n = n, hs_override = TRUE, data = data_r_gonzalezmule_2014,
        rxx = rxxi, ryy = ryyi, ux = ux, indirect_rr_x = TRUE,
        moderators = c("Rating source", "Published", "Type", "Complexity"))



### Demonstration of ma_r_ad ###
## Compute barebones meta-analysis
ma_obj <- ma_r_bb(r = rxyi, n = n, correct_bias = FALSE,
                           conf_method = "norm", cred_method = "norm", data = data_r_mcdaniel_1994)

## Construct artifact distribution for X
ad_obj_x <- create_ad(ad_type = "tsa", mean_rxxi = data_r_mcdaniel_1994$Mrxxi[1],
                      var_rxxi = data_r_mcdaniel_1994$SDrxxi[1]^.5,
                      ux = data_r_mcdaniel_1994$ux,
                      wt_ux = data_r_mcdaniel_1994$`ux frequency`)

## Construct artifact distribution for Y
ad_obj_y <- create_ad(ad_type = "tsa", rxxi = data_r_mcdaniel_1994$ryyi,
                      wt_rxxi = data_r_mcdaniel_1994$`ryyi frequency`)

## Compute artifact-distribution meta-analysis, correcting for measurement error only
ma_r_ad(ma_obj = ma_obj, ad_obj_x = ad_obj_x, ad_obj_y = ad_obj_y, correction_method = "meas")

## Compute artifact-distribution meta-analysis, correcting for univariate direct range restriction
ma_r_ad(ma_obj = ma_obj, ad_obj_x = ad_obj_x, ad_obj_y = ad_obj_y, correction_method = "uvdrr",
        correct_rr_y = FALSE, indirect_rr_x = FALSE)


# The results of ma_r() can also be corrected using artifact distributions
ma_obj <- ma_r(ma_method = "bb", rxyi = rxyi, n = n,
               construct_x = x_name, construct_y = y_name, sample_id = sample_id,
               moderators = moderator, data = data_r_meas_multi)

# The create_ad_list function can be used to generate batches of artifact-distribution objects.
# Here is an example in which one distribution is created per construct.
ad_tibble <- create_ad_list(n = n, rxx = rxxi, ryy = ryyi,
                            construct_x = x_name, construct_y = y_name,
                            sample_id = sample_id,
                            data = data_r_meas_multi)
# Passing that collection of distributions to ma_r_ad() corrects 'ma_obj' for artifacts:
ma_obj_tibble <- ma_r_ad(ma_obj = ma_obj,
                         ad_obj_x = ad_tibble, ad_obj_y = ad_tibble)
summary(ma_obj_tibble)
ma_obj_tibble$meta_tables[[1]]$artifact_distribution$true_score


# The same outcomes as the previous example can be achieved by passing a named list of
# artifact information, with each element bearing the name of a construct:
ad_list <- setNames(ad_tibble$ad_x, ad_tibble$construct_x)
ma_obj_list <- ma_r_ad(ma_obj = ma_obj,
                       ad_obj_x = ad_list, ad_obj_y = ad_list)
summary(ma_obj_list)
ma_obj_list$meta_tables[[1]]$artifact_distribution$true_score


# It is also possible to construct artifact distributions in a pairwise fashion.
# For example, if correlations between X and Y and between X and Z are being analyzed,
# X will get a different distribution for its relationships with Y than with Z.
# These pairwise distributions are based only on artifact data from specific construct pairs.
ad_tibble_pair <- create_ad_list(n = n, rxx = rxxi, ryy = ryyi,
                                 construct_x = x_name, construct_y = y_name,
                                 sample_id = sample_id,
                                 control = control_psychmeta(pairwise_ads = TRUE),
                                 data = data_r_meas_multi)
# Passing these pairwise distributions to ma_r_ad() corrects 'ma_obj' for artifacts:
ma_obj_pair <- ma_r_ad(ma_obj = ma_obj,
                       ad_obj_x = ad_tibble_pair, ad_obj_y = ad_tibble_pair)
summary(ma_obj_pair)
ma_obj_pair$meta_tables[[1]]$artifact_distribution$true_score


# Sometimes moderators have important influcnces on artifact distributions as well as
# distributions of effect sizes. When this occurs, moderated artifact distributions
# can be created to make more appropriate corrections.
ad_tibble_mod <- create_ad_list(n = n, rxx = rxxi, ryy = ryyi,
                                construct_x = x_name, construct_y = y_name,
                                sample_id = sample_id,
                                control = control_psychmeta(moderated_ads = TRUE),
                                moderators = moderator,
                                data = data_r_meas_multi)
# Passing these moderated distributions to ma_r_ad() corrects 'ma_obj' for artifacts:
ma_obj_mod <- ma_r_ad(ma_obj = ma_obj,
                      ad_obj_x = ad_tibble_mod, ad_obj_y = ad_tibble_mod)
summary(ma_obj_mod)
ma_obj_mod$meta_tables[[1]]$artifact_distribution$true_score


# It is also possible to create pairwise moderated artifact distributions.
ad_tibble_pairmod <- create_ad_list(n = n, rxx = rxxi, ryy = ryyi,
                                    construct_x = x_name, construct_y = y_name,
                                    sample_id = sample_id,
                                    control = control_psychmeta(moderated_ads = TRUE,
                                                                pairwise_ads = TRUE),
                                    moderators = moderator,
                                    data = data_r_meas_multi)
# Passing these pairwise moderated distributions to ma_r_ad() corrects 'ma_obj' for artifacts:
ma_obj_pairmod <- ma_r_ad(ma_obj = ma_obj,
                          ad_obj_x = ad_tibble_pairmod, ad_obj_y = ad_tibble_pairmod)
summary(ma_obj_pairmod)
ma_obj_pairmod$meta_tables[[1]]$artifact_distribution$true_score


# For even more control over which artifact distributions are used in corrections, you can supply
# un-named list of distributions in which the order of distributions corresponds to the order of
# meta-analyses in ma_obj. It is important for the elements to be un-named, as the absence of names
# and the length of the list are the two ways in which ma_r_ad() validates the lists.
ad_list_pairmod_x <- ad_tibble_pairmod$ad_x
ad_list_pairmod_y <- ad_tibble_pairmod$ad_y
# Passing these lists of distributions to ma_r_ad() corrects 'ma_obj' for artifacts:
ma_obj_pairmodlist <- ma_r_ad(ma_obj = ma_obj,
                              ad_obj_x = ad_list_pairmod_x, ad_obj_y = ad_list_pairmod_y)
summary(ma_obj_pairmodlist)
ma_obj_pairmodlist$meta_tables[[1]]$artifact_distribution$true_score

## End(Not run)

psychmeta/psychmeta documentation built on Feb. 12, 2024, 1:21 a.m.