create_ad {psychmeta}

Generate an artifact distribution object for use in artifact-distribution meta-analysis programs.

Description

This function generates artifact-distribution objects containing either interactive or Taylor series artifact distributions. Use this to create objects that can be supplied to the ma_r_ad and ma_r_ad functions to apply psychometric corrections to barebones meta-analysis objects via artifact distribution methods.

Allows consolidation of observed and estimated artifact information by cross-correcting artifact distributions and forming weighted artifact summaries.

For u ratios, error variances can be computed for independent samples (i.e., settings in which the unrestricted standard deviation comes from an external study) or dependent samples (i.e., settings in which the range-restricted standard deviation comes from a sample that represents a subset of the applicant sample that provided the unrestricted standard deviation). The former circumstance is presumed to be more common, so error variances are computed for independent samples by default.

Usage

create_ad(
  ad_type = c("tsa", "int"),
  rxxi = NULL,
  n_rxxi = NULL,
  wt_rxxi = n_rxxi,
  rxxi_type = rep("alpha", length(rxxi)),
  k_items_rxxi = rep(NA, length(rxxi)),
  rxxa = NULL,
  n_rxxa = NULL,
  wt_rxxa = n_rxxa,
  rxxa_type = rep("alpha", length(rxxa)),
  k_items_rxxa = rep(NA, length(rxxa)),
  ux = NULL,
  ni_ux = NULL,
  na_ux = NULL,
  wt_ux = ni_ux,
  dep_sds_ux_obs = rep(FALSE, length(ux)),
  ut = NULL,
  ni_ut = NULL,
  na_ut = NULL,
  wt_ut = ni_ut,
  dep_sds_ut_obs = rep(FALSE, length(ut)),
  mean_qxi = NULL,
  var_qxi = NULL,
  k_qxi = NULL,
  mean_n_qxi = NULL,
  qxi_dist_type = rep("alpha", length(mean_qxi)),
  mean_k_items_qxi = rep(NA, length(mean_qxi)),
  mean_rxxi = NULL,
  var_rxxi = NULL,
  k_rxxi = NULL,
  mean_n_rxxi = NULL,
  rxxi_dist_type = rep("alpha", length(mean_rxxi)),
  mean_k_items_rxxi = rep(NA, length(mean_rxxi)),
  mean_qxa = NULL,
  var_qxa = NULL,
  k_qxa = NULL,
  mean_n_qxa = NULL,
  qxa_dist_type = rep("alpha", length(mean_qxa)),
  mean_k_items_qxa = rep(NA, length(mean_qxa)),
  mean_rxxa = NULL,
  var_rxxa = NULL,
  k_rxxa = NULL,
  mean_n_rxxa = NULL,
  rxxa_dist_type = rep("alpha", length(mean_rxxa)),
  mean_k_items_rxxa = rep(NA, length(mean_rxxa)),
  mean_ux = NULL,
  var_ux = NULL,
  k_ux = NULL,
  mean_ni_ux = NULL,
  mean_na_ux = rep(NA, length(mean_ux)),
  dep_sds_ux_spec = rep(FALSE, length(mean_ux)),
  mean_ut = NULL,
  var_ut = NULL,
  k_ut = NULL,
  mean_ni_ut = NULL,
  mean_na_ut = rep(NA, length(mean_ut)),
  dep_sds_ut_spec = rep(FALSE, length(mean_ut)),
  estimate_rxxa = TRUE,
  estimate_rxxi = TRUE,
  estimate_ux = TRUE,
  estimate_ut = TRUE,
  var_unbiased = TRUE,
  ...
)

Arguments

ad_type

Type of artifact distribution to be computed: Either "tsa" for Taylor series approximation or "int" for interactive.

rxxi

Vector of incumbent reliability estimates.

n_rxxi

Vector of sample sizes associated with the elements of rxxi.

wt_rxxi

Vector of weights associated with the elements of rxxi (by default, sample sizes will be used as weights).

rxxi_type, rxxa_type, qxi_dist_type, rxxi_dist_type, qxa_dist_type, rxxa_dist_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_rxxi, mean_k_items_qxi, mean_k_items_rxxi, k_items_rxxa, mean_k_items_qxa, mean_k_items_rxxa

Numeric vector of the number of items in each scale (or mean number of items, for pre-specified distributions).

rxxa

Vector of applicant reliability estimates.

n_rxxa

Vector of sample sizes associated with the elements of rxxa.

wt_rxxa

Vector of weights associated with the elements of rxxa (by default, sample sizes will be used as weights).

ux

Vector of observed-score u ratios.

ni_ux

Vector of incumbent sample sizes associated with the elements of ux.

na_ux

Vector of applicant sample sizes that can be used in estimating the sampling error of supplied ux values. NULL by default. Only used when ni_ux is not NULL. If supplied, must be either a scalar or the same length as ni_ux.

wt_ux

Vector of weights associated with the elements of ux (by default, sample sizes will be used as weights).

dep_sds_ux_obs

Logical scalar or vector determining whether supplied ux values were computed using dependent samples (TRUE) or independent samples (FALSE).

ut

Vector of true-score u ratios.

ni_ut

Vector of incumbent sample sizes associated with the elements of ut.

na_ut

Vector of applicant sample sizes that can be used in estimating the sampling error of supplied ut values. NULL by default. Only used when ni_ut is not NULL. If supplied, must be either a scalar or the same length as ni_ut.

wt_ut

Vector of weights associated with the elements of ut (by default, sample sizes will be used as weights).

dep_sds_ut_obs

Logical scalar or vector determining whether supplied ut values were computed using dependent samples (TRUE) or independent samples (FALSE).

mean_qxi

Vector that can be used to supply the means of externally computed distributions of incumbent square-root reliabilities.

var_qxi

Vector that can be used to supply the variances of externally computed distributions of incumbent square-root reliabilities.

k_qxi

Vector that can be used to supply the number of studies included in externally computed distributions of incumbent square-root reliabilities.

mean_n_qxi

Vector that can be used to supply the mean sample sizes of externally computed distributions of incumbent square-root reliabilities.

mean_rxxi

Vector that can be used to supply the means of externally computed distributions of incumbent reliabilities.

var_rxxi

Vector that can be used to supply the variances of externally computed distributions of incumbent reliabilities.

k_rxxi

Vector that can be used to supply the number of studies included in externally computed distributions of incumbent reliabilities.

mean_n_rxxi

Vector that can be used to supply the mean sample sizes of externally computed distributions of incumbent reliabilities.

mean_qxa

Vector that can be used to supply the means of externally computed distributions of applicant square-root reliabilities.

var_qxa

Vector that can be used to supply the variances of externally computed distributions of applicant square-root reliabilities.

k_qxa

Vector that can be used to supply the number of studies included in externally computed distributions of applicant square-root reliabilities.

mean_n_qxa

Vector that can be used to supply the mean sample sizes of externally computed distributions of applicant square-root reliabilities.

mean_rxxa

Vector that can be used to supply the means of externally computed distributions of applicant reliabilities.

var_rxxa

Vector that can be used to supply the variances of externally computed distributions of applicant reliabilities.

k_rxxa

Vector that can be used to supply the number of studies included in externally computed distributions of applicant reliabilities.

mean_n_rxxa

Vector that can be used to supply the mean sample sizes of externally computed distributions of applicant reliabilities.

mean_ux

Vector that can be used to supply the means of externally computed distributions of observed-score u ratios.

var_ux

Vector that can be used to supply the variances of externally computed distributions of observed-score u ratios.

k_ux

Vector that can be used to supply the number of studies included in externally computed distributions of observed-score u ratios.

mean_ni_ux

Vector that can be used to supply the mean incumbent sample sizes of externally computed distributions of observed-score u ratios.

mean_na_ux

Vector or scalar that can be used to supply the mean applicant sample size(s) of externally computed distributions of observed-score u ratios.

dep_sds_ux_spec

Logical scalar or vector determining whether externally computed ux distributions were computed using dependent samples (TRUE) or independent samples (FALSE).

mean_ut

Vector that can be used to supply the means of externally computed distributions of true-score u ratios.

var_ut

Vector that can be used to supply the variances of externally computed distributions of true-score u ratios.

k_ut

Vector that can be used to supply the number of studies included in externally computed distributions of true-score u ratios.

mean_ni_ut

Vector that can be used to supply the mean sample sizes for of externally computed distributions of true-score u ratios.

mean_na_ut

Vector or scalar that can be used to supply the mean applicant sample size(s) of externally computed distributions of true-score u ratios.

dep_sds_ut_spec

Logical scalar or vector determining whether externally computed ut distributions were computed using dependent samples (TRUE) or independent samples (FALSE).

estimate_rxxa

Logical argument to estimate rxxa values from other artifacts (TRUE) or to only used supplied rxxa values (FALSE). TRUE by default.

estimate_rxxi

Logical argument to estimate rxxi values from other artifacts (TRUE) or to only used supplied rxxi values (FALSE). TRUE by default.

estimate_ux

Logical argument to estimate ux values from other artifacts (TRUE) or to only used supplied ux values (FALSE). TRUE by default.

estimate_ut

Logical argument to estimate ut values from other artifacts (TRUE) or to only used supplied ut values (FALSE). TRUE by default.

var_unbiased

Logical scalar determining whether variance should be unbiased (TRUE) or maximum-likelihood (FALSE).

...

Further arguments.

Value

Artifact distribution object (matrix of artifact-distribution means and variances) for use artifact-distribution meta-analyses.

Examples

## Example computed using observed values only:
create_ad(ad_type = "tsa", rxxa = c(.9, .8), n_rxxa = c(50, 150),
              rxxi = c(.8, .7), n_rxxi = c(50, 150),
              ux = c(.9, .8), ni_ux = c(50, 150))

create_ad(ad_type = "int", rxxa = c(.9, .8), n_rxxa = c(50, 150),
              rxxi = c(.8, .7), n_rxxi = c(50, 150),
              ux = c(.9, .8), ni_ux = c(50, 150))

## Example computed using all possible input arguments (arbitrary values):
rxxa <- rxxi <- ux <- ut <- c(.7, .8)
n_rxxa <- n_rxxi <- ni_ux <- ni_ut <- c(50, 100)
na_ux <- na_ut <- c(200, 200)
mean_qxa <- mean_qxi <- mean_ux <- mean_ut <- mean_rxxi <- mean_rxxa <- c(.7, .8)
var_qxa <- var_qxi <- var_ux <- var_ut <- var_rxxi <- var_rxxa <- c(.1, .05)
k_qxa <- k_qxi <- k_ux <- k_ut <- k_rxxa <- k_rxxi <- 2
mean_n_qxa <- mean_n_qxi <- mean_ni_ux <- mean_ni_ut <- mean_n_rxxa <- mean_n_rxxi <- c(100, 100)
dep_sds_ux_obs <- dep_sds_ux_spec <- dep_sds_ut_obs <- dep_sds_ut_spec <- FALSE
mean_na_ux <- mean_na_ut <- c(200, 200)

wt_rxxa <- n_rxxa
wt_rxxi <- n_rxxi
wt_ux <- ni_ux
wt_ut <- ni_ut

estimate_rxxa <- TRUE
estimate_rxxi <- TRUE
estimate_ux <- TRUE
estimate_ut <- TRUE
var_unbiased <- TRUE

create_ad(rxxa = rxxa, n_rxxa = n_rxxa, wt_rxxa = wt_rxxa,
              mean_qxa = mean_qxa, var_qxa = var_qxa,
              k_qxa = k_qxa, mean_n_qxa = mean_n_qxa,
              mean_rxxa = mean_rxxa, var_rxxa = var_rxxa,
              k_rxxa = k_rxxa, mean_n_rxxa = mean_n_rxxa,

              rxxi = rxxi, n_rxxi = n_rxxi, wt_rxxi = wt_rxxi,
              mean_qxi = mean_qxi, var_qxi = var_qxi,
              k_qxi = k_qxi, mean_n_qxi = mean_n_qxi,
              mean_rxxi = mean_rxxi, var_rxxi = var_rxxi,
              k_rxxi = k_rxxi, mean_n_rxxi = mean_n_rxxi,

              ux = ux, ni_ux = ni_ux, na_ux = na_ux, wt_ux = wt_ux,
              dep_sds_ux_obs = dep_sds_ux_obs,
              mean_ux = mean_ux, var_ux = var_ux, k_ux =
               k_ux, mean_ni_ux = mean_ni_ux,
              mean_na_ux = mean_na_ux, dep_sds_ux_spec = dep_sds_ux_spec,

              ut = ut, ni_ut = ni_ut, na_ut = na_ut, wt_ut = wt_ut,
              dep_sds_ut_obs = dep_sds_ut_obs,
              mean_ut = mean_ut, var_ut = var_ut,
              k_ut = k_ut, mean_ni_ut = mean_ni_ut,
              mean_na_ut = mean_na_ut, dep_sds_ut_spec = dep_sds_ut_spec,

              estimate_rxxa = estimate_rxxa, estimate_rxxi = estimate_rxxi,
              estimate_ux = estimate_ux, estimate_ut = estimate_ut, var_unbiased = var_unbiased)